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](/index.html#getting-started),
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](tut1.html) to set up your own dehub project and
learn about credentials and their verification.