From 414891865568ee95978bfe2091ef6f8416726a1f Mon Sep 17 00:00:00 2001 From: bubblemelon <12985181+Bubblemelon@users.noreply.github.com> Date: Thu, 16 Aug 2018 17:00:04 -0400 Subject: [PATCH] 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 --- docs/CONTRIBUTING.md | 48 ++++++++++++++++++++++++++++++++++++++------ 1 file changed, 42 insertions(+), 6 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index bbe0d553..ed22e90a 100644 --- 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 . @@ -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 `. 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 , with the patch attached 1. Attach them to 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/` 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: #`. + +Commit Message example: + +```bash +: 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 `. + 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