Git Commit Message Format
=========================

// please don't remove the //word: comments

[grid="all"]
`------------`-----------------------
*State*         _Final_
*Date*          _Fr 31 Aug 2012 03:54:14 CEST_
*Proposed by*   Christian Thaeter <ct@pipapo.org>
-------------------------------------

********************************************************************************
.Abstract
This RFC describes the format of commit messages, based on already used
practice.
********************************************************************************

Description
-----------
//description: add a detailed 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.


.General

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.


.Header

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


.List of Defined headers:

'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


.Body

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
---------
//rationale: Give a concise summary why it should be done *this* way:

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.


//Conclusion
//----------
//conclusion: When approbate (this proposal becomes a Final)
//            write some conclusions about its process:




Comments
--------
//comments: append below

.State -> Final
//add reason

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>~


//endof_comments:

''''
Back to link:/documentation/devel/rfc.html[Lumiera Design Process overview]
