HDL_workflow: Add git commit format guide bug #1126#40

diff --git a/HDL_workflow.mdwn b/HDL_workflow.mdwn
index 0d42fe402992181e34983ad97bc6e5e394d965c2..12df9b5210c41a4a8bf3f716d2d24a6e897ec5b7 100644 (file)
--- a/HDL_workflow.mdwn
+++ b/HDL_workflow.mdwn
@@ -864,6 +864,44 @@ You can avoid damaging the repositories by following some simple procedures:
   that the commit has not been properly broken down into separate-purpose
   commits. ask for advice on-list on how to proceed.
 
+### *Git commit message format*
+
+* Based on [bug #1126#c40](https://bugs.libre-soc.org/show_bug.cgi?id=1126#c40)
+
+1. Every commit MUST start with a short title, up to 50 characters.
+2. The commit title MUST contain either subsystem, or a file path,
+or a subsystem/path, or a subsystem/subsubsystem combination, which got
+modified or introduced, and a short summary. These parts must be separated
+by the semicolon.
+3. A good rule is to imagine that the short message begins with
+"if this patch is applied, it will". For example, a good title is
+"X: update Y", not "updated Y in X".
+4. After the title, there must be an empty line, which documents the
+changes. The limit is 72 characters per line.
+5. The long description can be omitted if the short description provides
+enough information or if the commit itself is simple enough.
+
+Example:
+
+```
+subsystem/file.py: document usage
+
+Here goes the long description, which explains everything. First of all,
+we stick to limit of 72 characters. Then, perhaps, we'd like to explain
+the rationale in more details.
+```
+
+It is suggested to stick to common sense whenever choosing subsystem names
+or files or long descriptions.
+
+Primary concerns are:
+
+1. short titles
+2. short summaries
+3. wording for the first line
+
+The rest is up for the committers.
+
 ### Exceptions to small commit: atomic single purpose commit
 
 * if it is essential to commit large amounts of code, ensure that it