[gimp] CODING_STYLE: add a "Commit messages" section.
- From: Jehan <jehanp src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gimp] CODING_STYLE: add a "Commit messages" section.
- Date: Wed, 20 Oct 2021 10:52:48 +0000 (UTC)
commit 5ed68ab45bcbfea07b70165b4aec22e6bc318752
Author: Jehan <jehan girinstud io>
Date: Wed Oct 20 12:51:31 2021 +0200
CODING_STYLE: add a "Commit messages" section.
Because it is important to have good commit messages for future
investigations of code.
CODING_STYLE.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 67 insertions(+)
---
diff --git a/CODING_STYLE.md b/CODING_STYLE.md
index d8cc609c84..a5ae88646a 100644
--- a/CODING_STYLE.md
+++ b/CODING_STYLE.md
@@ -12,6 +12,7 @@ allowed exceptions.
## Table of contents
- [General rules](#general-rules)
+- [Commit messages](#commit-messages)
- [Dealing with the old code](#dealing-with-the-old-code)
- [Indentation](#indentation)
- [Braces](#braces)
@@ -54,6 +55,72 @@ You might also find the `git-stripspace` utility helpful, which acts as a filter
to remove trailing whitespace as well as initial, final, and duplicate blank
lines.
+## Commit messages
+
+Commit messages should follow the following rules:
+
+- Always provide informative titles. No one-word commits saying nothing
+ like "bug fix", so that we can at least search through the git history
+ if needed. It can still be short messages for very simple fixes: for
+ instance "Fix typo" or "Fix small memory leak" are informative of the
+ type of fix.
+- Prefix the title with the codebase section (i.e. the root folder
+ usually) which was changed. For instance: `libgimpbase: fix memory
+ leak` immediately tells us it was a memory leak fix in the
+ `libgimpbase` library. If several sections are touched, list them with
+ comma-separation.
+- Alternatively, when the change is a response to a bug report, you may
+ prefix with `Issue #123:` (where `#123` is the report ID) instead.
+- If the changed code itself is not self-explanatory enough, you can add
+ longer change description (2 lines after the title) to explain more.
+ It is not mandatory, but it is never unwelcome because old code
+ exploration to understand why things were done (possibly years before
+ by people long gone) is a real thing we do all the time. So if it's
+ not obvious, explain us.
+- Explanations can also be made in the shape of links to a bug report
+ (ours, or a third-party project tracker, or some manual), even though
+ additional text explanations may still be useful (unfortunately URLs
+ may change or disappear). If the link is to our own bug tracker,
+ usually giving the ID is enough.
+- Same [as for code](#line-width), wrap your commit message to
+ reasonable line widths, such as 72 or 80 maximum so that other
+ contributors don't have to scroll horizontally on narrow
+ vizualisation. There may be exceptions, for instance when pasting some
+ error messages which may end up confusing when wrapped. But other than
+ this, wrap your text (most `git` client would have a feature to do it
+ for you).
+- If the title is too long because of the max-width settings, a common
+ format is to break it with '…' and to continue the title 2 lines below.
+ Then the description goes again 2 lines below.
+
+Here is an example of a well formatted fix in the `plug-ins/` section:
+
+```
+plug-ins: fix file-gih.
+
+We currently cannot call gimp_pdb_run_procedure() for procedures
+containing arrays because this C-type doesn't contain the size
+information (which is in a second parameter but since the rule is not
+hard-coded, our API can't know this).
+
+See issue #7369.
+```
+
+Here is another as a response to a bug report and a long title:
+
+```
+Issue #6695: Wrong tab after JPG export because of "Show preview"…
+
+… feature.
+
+Using the new gimp_display_present() function in file-jpeg to make sure
+the original display is back to the top.
+```
+
+If you want to see more good examples, this `git` command will list
+commits whose messages are generally well formatted:
+`git log --author="Jehan\|mitch\|Jacob Boerema"`
+
## Dealing with the old code
__The new GIMP code should adhere to the style explained below.__ The existing
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]