State |
Dropped |
Date |
Fr 31 Aug 2012 03:54:14 CEST |
Proposed by |
Christian Thaeter <ct@pipapo.org> |
Description
Git commit messages are almost free form text, the only exception is that Git treats the first line in a commit message specially to form the header one sees in various outputs.
Since we aim to automate some processing we refine the format for commit messages sightly more.
Commit Messages will be shown in space limited areas (lists on webpages, emails, tooltips). Unlike source code where we are quite lax about line lengths commit messages should not exceed 80 characters per line.
The first line is treated as Header as described below, followed by an empty line and then the Body of the commit message. The Body is optional but recommended.
This formalized keywords for headers are optional, if in doubt then don’t use any. But if one uses them, then use only one defined here since automatic processing only knows about these.
The Header is free form text explaining the purpose of the commit in a few words. It may start with one uppercased keyword and a colon if appropriate directly followed by some (optional, defined elsewhere) metadata. This Keywords are optional but recommended since automatic processing acts upon them. Normal commits don’t need these keywords and are just free form text.
To be exact, here is a regex matching valid Headers:
^[[:upper:]]+:[[:punct:]]?[[:alnum:][:punct:]]*Legal headers are for example:
DONE: some feature
FIX:#1234 Segv when starting
RELEASE:1.0 Party- WIP:
-
Work in Progress, commits marked as this may be incomplete and fail in various ways. For example automatic git-bisecting will skip them. WIP should take precedence, if for example one needs multiple commits to fix a bug, then only the final commit is tagged as FIX: and the leading commits are WIP:
- FIX:
-
Bugfix. The Text should explain what error got fixed. A reference to a bug number is not optional and not needed.
- RFC:
-
This commit adds or modifies a RFC but doesn’t touch the codebase (tests/examples are permitted).
- DOC:
-
This commit only alters documentation but no code.
- STASH:
-
When git-stash is not enough (for example one wants to move unfinished changes changes to another repository or commit as backup and amend things later). Normally such commits should not remain in a published repository and not become merged.
- DRAFT:
-
Much like WIP: but will not break compilation and is sane to use. For example mockups, documentation and skeleton code for new facilities may use this.
- DONE:
-
Final commit/merge when some noteworthy part is done. The idea here is that finished things could be easily filtered out for our quarterly reports.
- TODO:
-
This commit adds a documentation, comments or tests about something to be done. Same rules as NoBug’s TODO apply.
- FIXME:
-
This commit adds a documentation, comments or tests about something to be fixed. Aka a known bug which can not be fixed instantly for some reason. Same rules as NoBug’s FIXME apply.
- PLANNED:
-
This commit adds a documentation, comments or tests about something planned. Same rules as NoBug’s PLANNED apply.
- ALPHA:
-
Notifies the CI system that this commit defines an ALPHA release, the CI may take this and build an package accordingly
- BETA:
-
Notifies the CI system that this commit defines an BETA release, the CI may take this and build an package accordingly
- RELEASE:
-
Notifies the CI system that this commit defines an production release, the CI may take this and build an package accordingly
Note: This list will be updated as need arises
Adding a body is optional but recommended but for the most simple changes. A body, if present should separate from the header by one empty line.
It is suggested not to make any lines longer than 80 characters and use asciidoc formatting. In most cases this means just free form text and maybe use of bulleted list.
Care should be taken to write clean understandable commit messages. In some extent they may repeat the comments and documentation from the committed code in a short form. Think that anyone else reading only the commit message should understand whats going on.
Rationale
This RFC is based on existing practice, we almost done it this way. some minor glitches are present in the project history (no colon after keywords, lowercase keywords). Automatic processing becomes simpler when we formalize these things in an unambigous way. Commits failing this definitions might confuse the toolchain (builddrone) but this failures shall not be critical.
Comments
We decided on the sept. 2012 devel meeting to finlize this RFC.
- Christian Thaeter
-
Do 13 Sep 2012 03:57:23 CEST <ct@pipapo.org>
|
This RfC is now superseded by using the Git-flow branching scheme. |
With the recent move to Git-flow we acknowledge now — by employing a branch model — that the project history is built and conducted consciously, by us. In the current stage, it is not the goal of this project to churn out a stream of commits, using an automated production line to push some metrics high.
Since any automation comes at a cost and incurs burdens and limitations, it should be employed to solve actual problems, but should not be introduced prematurely:
-
we spend most of our time with finding suitable solutions, not with coding them up. When a part is completed, some time can be spent to document it and to consolidate the history. Thus, leaving formalised WIP and STASH marks is besides the point.
-
releases and even bugfixes require forethought, analysis, verification and reflection. The extra time required to set a git tag manually, or even to perform a merge, is negligible in comparison, and does not justify the weight of automation.
-
documentation is written in the context of solving actual problems; it is pointless to spot “documentation commits” by some markers, because their relevance is already obvious from a meaningful context.
-
Git bisect is an essential tool when working with a code base which you do not understand. With a well-crafted yet ambitious system the situation is quite different: in such a system, the change which caused the breakage is obvious and easy to spot — while the actual challenge is to understand why difficulties arose — not to mention the amount of work required to develop a path of escape from a real dilemma.
This RfC highlights some general considerations however, which remain valid anyway: to provide a short commit summary in the first line, and then, after an empty line, to provide a description for anything that is non-obvious, possibly with cross-references to tickets, URLs pointing to external sources and anything that might provide meaningful context for someone looking at this change years later. And, commit messages should be line-wrapped.
- Ichthyostega
-
2025-09-16
Back to Lumiera Design Process overview