CONTRIBUTE: More formally specify the commit description

This codifies what people have actually used in git commits over the
past 6 years. I've left off some lesser-used headers that appear to
duplicate others and tried to describe a consistent use for several
others that were used more arbitrarily.

This makes it easier for new committers to find out the kinds of things
we want to acknowledge, makes it easier to perform statistical analysis
on commits, and opens the possibility of performing lint checks on
descriptions before submission.

Reviewed-by: Daniel Stenberg
Reviewed-by: Jay Satiro
Closes #10478

diff --git a/docs/CONTRIBUTE.md b/docs/CONTRIBUTE.md
index bc7b525c5d1f43012de766170210aa42b6422be6..364bafb47a0fa8fc2c41e2914c634a9b15bf7cc5 100644 (file)
--- a/docs/CONTRIBUTE.md
+++ b/docs/CONTRIBUTE.md
@@ -188,34 +188,62 @@ to the list or better yet: change it to a pull request.
 
 ### Commit messages
 
-A short guide to how to write commit messages in the curl project.
+A short guide to how to write git commit messages in the curl project.
 
     ---- start ----
     [area]: [short line describing the main effect]
            -- empty line --
-    [full description, no wider than 72 columns that describe as much as
+    [full description, no wider than 72 columns that describes as much as
     possible as to why this change is made, and possibly what things
-    it fixes and everything else that is related]
+    it fixes and everything else that is related, with unwieldy URLs replaced
+    with references like [0], [1], etc.]
            -- empty line --
-    [Closes/Fixes #1234 - if this closes or fixes a github issue]
-    [Bug: URL to source of the report or more related discussion]
-    [Reported-by: John Doe - credit the reporter]
-    [whatever-else-by: credit all helpers, finders, doers]
+    [[0] URL - Reference to a URL in the description, almost like Markdown;
+        the last numbered reference is followed by an -- empty line -- ]
+    [Follow-up to {shorthash} - if this fixes or continues a previous commit;
+        add a Ref: that commit's PR or issue if it's not a small, obvious fix;
+        followed by an -- empty line -- ]
+    [Bug: URL to the source of the report or more related discussion; use Fixes
+        for GitHub issues instead when that is appropriate]
+    [Approved-by: John Doe - credit someone who approved the PR; if you're
+        committing this for someone else using --author=... you don't need this
+        as you're implicitly approving it by committing]
+    [Authored-by: John Doe - credit the original author of the code; only use
+        this if you can't use "git commit --author=..."]
+    {Signed-off-by: John Doe - we don't use this, but don't bother removing it]
+    [whatever-else-by: credit all helpers, finders, doers; try to use one of
+        the following keywords if at all possible, for consistency:
+        Acked-by:, Assisted-by:, Co-authored-by:, Found-by:, Reported-by:,
+        Reviewed-by:, Suggested-by:, Tested-by:]
+    [Ref: #1234 - if this is related to a GitHub issue or PR, possibly one that
+                  has already been closed]
+    [Ref: URL to more information about the commit; use Bug: instead for
+        a reference to a bug on another bug tracker]
+    [Fixes #1234 - if this closes a GitHub issue; GitHub will actually
+        close the issue once this commit is merged]
+    [Closes #1234 - if this closes a GitHub PR; GitHub will actually
+        close the PR once this commit is merged]
     ---- stop ----
 
 The first line is a succinct description of the change:
 
  - use the imperative, present tense: "change" not "changed" nor "changes"
- - do not capitalize first letter
- - no dot (.) at the end
+ - do not capitalize the first letter
+ - no period (.) at the end
 
 The `[area]` in the first line can be `http2`, `cookies`, `openssl` or
 similar. There's no fixed list to select from but using the same "area" as
 other related changes could make sense.
 
-Do not forget to use commit --author="" if you commit someone else's work, and
+Do not forget to use commit --author=... if you commit someone else's work, and
 make sure that you have your own user and email setup correctly in git before
-you commit
+you commit.
+
+Add whichever header lines as appropriate, with one line per person if more
+than one person was involved. There's no need to credit yourself unless you are
+using --author=... which hides your identity. Don't include people's e-mail
+addresses in headers to avoid spam, unless they're already public from a
+previous commit; saying `{userid} on github` is OK.
 
 ### Write Access to git Repository