dehub/docs/tut0.md

Tutorial 0: Say Hello!

This tutorial will guide you through cloning a dehub project locally, creating a comment, and pushing that comment back up to the remote. The project in question: dehub itself!

This tutorial assumes you have dehub installed, you have git and gpg installed, and you have a gpg key already created.

Step 0: Clone the Project

Cloning the dehub project is as simple as cloning its git repo:

git clone https://dehub.dev/src/dehub.git
cd dehub

Once cloned, feel free to look around the project. You should initially find yourself on the main branch, the primary branch of most dehub projects (analogous to the master branch of most git repos).

Calling git log will show the commits messages for all commits in the branch. You will notice the commit messages aren't formatted in the familiar way, for example:

commit 351048e9aabef7dc0f99b00f02547e409859a33f
Author: mediocregopher <>
Date:   Sat Apr 25 15:17:21 2020 -0600

    Completely rewrite SPEC

    ---
    type: change
    description: |-
      Completely rewrite SPEC

      It's good this time, and complete. After this rewrite it will be necessary to
      update a lot of the code, since quite a few things got renamed.
    fingerprint: AG0s3yILU+0uIZltVY7A9/cgxr/pXk2MzGwExsY/hbIc
    credentials:
    - type: pgp_signature
      pub_key_id: 95C46FA6A41148AC
      body: BIG LONG STRING
      account: mediocregopher

Instead of just being a human-readable description they are YAML encoded payload objects. We will dive into these payload objects more throughout this tutorial series.

Step 1: Checkout the Welcome Branch

Next you're going to checkout the public welcome branch. This is done through a normal git checkout command:

git checkout public/welcome

You can do git log to see all the comments people have been leaving in this branch. The public/welcome branch is differentiated from the main branch in two ways:

• It has been configured to allow comment commits from anonymous users to be pushed to it. Project configuration is covered in a future tutorial.

• It has no code files tracked, its only purpose is for comments.

Step 2: Create Your Comment

Now that you've poked around the welcome branch a bit, it's time to leave a comment of your own! This is as easy as doing:

dehub commit --anon-pgp-key=KEY_NAME comment

(KEY_NAME should be replaced with any selector which will match your pgp key, such as the key ID, the name on the key, or the email.)

Your default text editor (defined by the EDITOR environment variable) will pop up and you can then write down your comment. When you save and close your editor dehub will sign the comment with your pgp key and create a commit with it.

If you're having trouble thinking of something to say, here's some prompts to get you going:

• Introduce yourself; say where you're from and what your interests are.

• How did you find dehub? Why is it interesting to you?

• If you're using dehub for a project, shill your project!

• If you'd like to get involved in dehub's development, let us know what your skills are and how you can help. Remember, it takes more than expert programmers to make a project successful.

Once you've created your commit you can call git log to verify that it's been created to your liking. If there's anything about the comment you'd like to change you can amend the commit like so:

dehub commit --anon-pgp-key=KEY_NAME comment --amend

Step 3: Push Your Commit

As of now your comment commit only exists on your local machine. For everyone else to see it you'll need to push it to the dehub server, exactly like with a normal git commit. Pushing is done in the same way as a normal git commit as well: git push.

If you receive an error that's like Updates were rejected because the tip of your current branch is behind then someone else has pushed to the branch in between the last time you pulled and now. Do a git pull --rebase to pull in those new changes, and try pushing again.

Step 4: Follow the Conversation

In order to see other people's responses to your comment, and all other parts of the conversation, all you need to do is call git pull with the public/welcome branch checked out.

You now have all the tools needed to participate in a dehub discussion thread! Continue on to Tutorial 1 to set up your own dehub project and learn about credentials and their verification.