doc: make commit guidelines easier to reference

bf4 · evanlucas · commit 47b39928d5b5 · 2017-05-02T12:46:15.000-05:00
- Can now link to 'Commit Guidelines' from pull requests - Breaks up commit requirements and recommendations PR-URL: #11732 Refs: #11723 (comment) Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com> Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -100,15 +100,28 @@ $ git commit
 Writing good commit logs is important. A commit log should describe what
 changed and why. Follow these guidelines when writing one:
 
-1. The first line should be 50 characters or less and contain a short
-   description of the change. All words in the description should be in
-   lowercase with the exception of proper nouns, acronyms, and the ones that
-   refer to code, like function/variable names. The description should
-   be prefixed with the name of the changed subsystem and start with an
-   imperative verb. Example: "net: add localAddress and localPort
-   to Socket"
+1. The first line should:
+   - contain a short description of the change
+   - be 50 characters or less
+   - be entirely in lowercase with the exception of proper nouns, acronyms, and
+   the words that refer to code, like function/variable names
+   - be prefixed with the name of the changed subsystem and start with an
+   imperative verb. Examples: "net: add localAddress and localPort
+   to Socket", "src: fix typos in node_lttng_provider.h"
+   - be meaningful; it is what other people see when they
+   run `git shortlog` or `git log --oneline`.<br>
+   Check the output of `git log --oneline files/you/changed` to find out
+   what subsystem (or subsystems) your changes touch
 2. Keep the second line blank.
 3. Wrap all other lines at 72 columns.
+   - If your patch fixes an open issue, you can add a reference to it at the end
+    of the log. Use the `Fixes:` prefix and the full issue URL. For other references
+    use `Refs:`. For example:
+    ```txt
+    Fixes: https://github.com/nodejs/node/issues/1337
+    Refs: http://eslint.org/docs/rules/space-in-parens.html
+    Refs: https://github.com/nodejs/node/pull/3615
+    ```
 
 A good commit log can look something like this:
 
@@ -123,22 +136,9 @@ The body of the commit message can be several paragraphs, and
 please do proper word-wrap and keep columns shorter than about
 72 characters or so. That way, `git log` will show things
 nicely even when it is indented.
-```
-
-The header line should be meaningful; it is what other people see when they
-run `git shortlog` or `git log --oneline`.
-
-Check the output of `git log --oneline files_that_you_changed` to find out
-what subsystem (or subsystems) your changes touch.
 
-If your patch fixes an open issue, you can add a reference to it at the end
-of the log. Use the `Fixes:` prefix and the full issue URL. For other references
-use `Refs:`. For example:
-
-```txt
 Fixes: https://github.com/nodejs/node/issues/1337
 Refs: http://eslint.org/docs/rules/space-in-parens.html
-Refs: https://github.com/nodejs/node/pull/3615
 ```
 
 ### Step 4: Rebase
@@ -203,9 +203,6 @@ core modules.
 $ git push origin my-branch
 ```
 
-Go to https://github.com/yourusername/node and select your branch.
-Click the 'Pull Request' button and fill out the form.
-
 Pull requests are usually reviewed within a few days.
 
 ### Step 7: Discuss and update
