docs: Add detail to CONTRIBUTING.md and link to tutorial

This adds detailed information on commit message guidelines, a link to the contributing tutorial, and minor typo fixes.

Closes: #1694
Approved by: cgwalters

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index bbe0d5532ffd030b98a5a79fe6898c893e979f11..ed22e90a5a162b927e67e6df84cae732ac5d7d07 100644 (file)
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -1,7 +1,7 @@
 Submitting patches
 ------------------
 
-A majority of current maintainers prefer the Github pull request
+A majority of current maintainers prefer the GitHub pull request
 model, and this motivated moving the primary git repository to
 <https://github.com/ostreedev/ostree>.
 
@@ -12,19 +12,19 @@ for more information.  Instead, we use an instance of
 [Homu](https://github.com/servo/homu), currently known as
 `cgwalters-bot`.
 
-As a review proceeds, the preferred method is to push `fixup!`
-commits via `git commit --fixup`.  Homu knows how to use
-`--autosquash` when performing the final merge.  See the
+As a review proceeds, the preferred method is to push `fixup!` commits. Any commits committed with the `--fixup` option will have have the word `fixup!` in its commit title. This is to indicate that this particular commit will be squashed with the commit that was specified in this command, `git commit --fixup <commit ref or hash>`. Homu knows how to use `--autosquash` when performing the final merge.
+
+See the
 [Git documentation](https://git-scm.com/docs/git-rebase) for more
 information.
 
-Alternative methods if you don't like Github (also fully supported):
+Alternative methods if you don't like GitHub (also fully supported):
 
  1. Send mail to <ostree-list@gnome.org>, with the patch attached
  1. Attach them to <https://bugzilla.gnome.org/>
 
 It is likely however once a patch is ready to apply a maintainer
-will push it to a github PR, and merge via Homu.
+will push it to a GitHub PR, and merge via Homu.
 
 Commit message style
 --------------------
@@ -35,6 +35,37 @@ similar to the
 
 You may use `Signed-off-by`, but we're not requiring it.
 
+**General Commit Message Guidelines**:
+
+1. Title
+    - Specify the context or category of the changes e.g. `lib` for library changes, `docs` for document changes, `bin/<command-name>` for command changes, etc.
+    - Begin the title with the first letter of the first word capitalized.
+    - Aim for less than 50 characters, otherwise 72 characters max.
+    - Do not end the title with a period.
+    - Use an [imperative tone](https://en.wikipedia.org/wiki/Imperative_mood).
+2. Body
+    - Separate the body with a blank line after the title.
+    - Begin a paragraph with the first letter of the first word capitalized.
+    - Each paragraph should be formatted within 72 characters.
+    - Content should be about what was changed and why this change was made.
+    - If your commit fixes an issue, the commit message should end with `Closes: #<number>`.
+
+Commit Message example:
+
+```bash
+<context>: Less than 50 characters for subject title
+
+A paragraph of the body should be within 72 characters.
+
+This paragraph is also less than 72 characters.
+```
+
+For more information see [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
+
+**Editing a Committed Message:**
+
+To edit the message from the most recent commit run `git commit --amend`. To change older commits on the branch use `git rebase -i`. For a successful rebase have the branch track `upstream master`. Once the changes have been made and saved, run `git push --force origin <branch-name>`.
+
 Running the test suite
 ----------------------
 
@@ -136,3 +167,8 @@ Instead do this:
               goto out;
           }
       }
+
+Contributing: Tutorial
+----------------------
+
+For a detailed walk-through on building, modifying, and testing, see this [tutorial on how to start contributing to OSTree](contributing-tutorial.md).
\ No newline at end of file