From 0ffded54ddfb651f1f0fc71cddbcdf129d324946 Mon Sep 17 00:00:00 2001
From: Martin Roth <gaumless@gmail.com>
Date: Mon, 29 May 2023 21:52:11 -0600
Subject: [PATCH] Documentation: Write down coreboot's git commit message rules

This mostly lists things that long-time coreboot contributors already
do. Some of these rules were captured on the wiki. Others were adopted
from other git commit message guideline documents long ago.

Signed-off-by: Martin Roth <gaumless@gmail.com>
Change-Id: Ic2ba681193e302318934cc2f7f30659eac73d099
Reviewed-on: https://review.coreboot.org/c/coreboot/+/75495
Reviewed-by: Matt DeVillier <matt.devillier@gmail.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Subrata Banik <subratabanik@google.com>
---
 .../contributing/git_commit_messages.md       | 78 +++++++++++++++++++
 Documentation/contributing/index.md           |  1 +
 2 files changed, 79 insertions(+)
 create mode 100644 Documentation/contributing/git_commit_messages.md

diff --git a/Documentation/contributing/git_commit_messages.md b/Documentation/contributing/git_commit_messages.md
new file mode 100644
index 0000000000..4addf4cfe3
--- /dev/null
+++ b/Documentation/contributing/git_commit_messages.md
@@ -0,0 +1,78 @@
+# Git Commit messages
+
+There are a number of different recommendations for git commit
+messages, so this is another one.
+
+It's expected that coreboot contributors already generally understand
+the idea of writing good git commit messages, so this is not trying
+to go over everything again. There are other tutorials that cover that.
+
+- [Linux Kernel tip tree Handbook](https://www.kernel.org/doc/html/latest/process/maintainer-tip.html#patch-subject)
+- [How to write a Git Commit Message](https://cbea.ms/git-commit/)
+
+## Line length
+
+- The subject line should be <= 65 characters, with an absolute maximum
+  of 75 characters
+- Prose in the commit message should be <= 75 characters
+- If reflowing prose to 75 characters can reduce the length of the
+  commit message by 2 or more lines, please reflow it. Using the entire
+  75 characters on a line when reasonable is recommended, but not
+  required.
+- Non-prose text in the body in the commit message does not need to be
+  wrapped at 75 characters. Examples: URLs, compiler output, or poetry.
+
+## Both Subject & body
+
+- Use the present tense. (The for loop exits too early, so ...", not
+ "The for loop exited too early, so ...").
+- When using acronyms, make sure they're explained in the commit
+  message itself or in the [acronyms list](https://doc.coreboot.org/acronyms.html).
+
+## Commit message Subject Line
+
+- Start the subject line with a prefix denoting the area of the change.
+  Often part of the path can be used by that. Looking through existing
+  commit messages summaries with `git log --oneline ...` gives a good
+  idea. Because this prefix takes space used by the rest of the subject,
+  it should be kept short while still uniquely describing the area.
+  - Don't include `src/`
+  - Use abbreviations where possible:
+    - mb: mainboard
+    - vc: vendorcode
+- Don't end the subject line with a period.
+- Use the imperative mood. ("Fix whitespace", not "whitespace fixes").
+
+## Commit Message Body
+
+- Make sure the problem being solved by the commit is described. While
+  it may be obvious to the committer, it may not be obvious to others.
+- Reference other commits with either CB:XXXXX or a 10 character hash
+  and the subject.
+- When using a URL in a commit message, use archive.org when possible.
+  URLs often get changed or go stale, so this keeps them stable.
+- Make sure that all changes in a patch are addressed in the commit
+  message.
+- A TEST= tag is highly recommended, but not required. This lets people
+  know whether you tested it by booting the board or just by compiling.
+- All but the most trivial of patches should generally have a body.
+- A BUG= tag can be added when the author wants to indicate that the
+  patch is or is not related to a bug. This can be either in coreboot's
+  issue tracker, or a private issue tracker.
+    - `BUG=b:####` is used by the Google internal issue tracker.
+    - `BUG=chromium:####` indicates the Chromium public tracker at
+      https://issues.chromium.org/
+    - `BUG=CID ####` can be used to indicate coverity error fixes.
+    - `BUG=https://...` can be used to link directly to a public
+      tracker.
+- The BRANCH= tag is used in cases where a patch needs to be added to a
+  specific downstream branch. This is never required by the coreboot
+  project.
+
+## Footers
+
+- The Signed-off-by line is required (Jenkins forces this).
+- The Change ID is required (Gerrit forces this.)
+- When adding a patch that has already gone through another git or
+  gerrit, the footers from those previous commits may be added, but
+  keep the list reasonable.
diff --git a/Documentation/contributing/index.md b/Documentation/contributing/index.md
index 38a67c069d..1f9e9e5e91 100644
--- a/Documentation/contributing/index.md
+++ b/Documentation/contributing/index.md
@@ -5,6 +5,7 @@
 
 Coding Style <coding_style.md>
 Gerrit Guidelines <gerrit_guidelines.md>
+Commit Message Guidelines <git_commit_messages.md>
 Project Ideas <project_ideas.md>
 Documentation Ideas <documentation_ideas.md>
 Google Summer of Code <gsoc.md>