| State | Final |
| 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 threats 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>
Back to Lumiera Design Process overview