From 5da7f0cd6e567c1815377bc7f2759b0c2abcfb1a Mon Sep 17 00:00:00 2001 From: Christian Thaeter Date: Fri, 31 Aug 2012 04:47:01 +0200 Subject: [PATCH] RFC: Git Commit Message Format Formal description for the format of commit messages. --- doc/devel/rfc/GitCommitMessageFormat.txt | 167 ++++++++++++++++++ .../rfc_pending/GitCommitMessageFormat.txt | 1 + 2 files changed, 168 insertions(+) create mode 100644 doc/devel/rfc/GitCommitMessageFormat.txt create mode 120000 doc/devel/rfc_pending/GitCommitMessageFormat.txt diff --git a/doc/devel/rfc/GitCommitMessageFormat.txt b/doc/devel/rfc/GitCommitMessageFormat.txt new file mode 100644 index 000000000..2396940d3 --- /dev/null +++ b/doc/devel/rfc/GitCommitMessageFormat.txt @@ -0,0 +1,167 @@ +Git Commit Message Format +========================= + +// please don't remove the //word: comments + +[grid="all"] +`------------`----------------------- +*State* _Idea_ +*Date* _Fr 31 Aug 2012 03:54:14 CEST_ +*Proposed by* Christian Thaeter +------------------------------------- + +******************************************************************************** +.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. + + +.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 appobiate. This +Keywords are optional but recommended since automatic processing acts upon +them. Normal work doesn't have any of these keywords but just free form text. + +'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, Details like a + bugtracker number or other references shall not be part of the Header. + +'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. + +'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. + + +... any other suggestions? ... + + +.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. + + +Tasks +~~~~~ +// List what needs to be done to implement this Proposal: +// * first step ([green]#✔ done#) +// * second step [,yellow]#WIP# + + +Discussion +~~~~~~~~~~ + +Pros +^^^^ +// add a fact list/enumeration which make this suitable: +// * foo +// * bar ... + + + +Cons +^^^^ +// fact list of the known/considered bad implications: + + + +Alternatives +^^^^^^^^^^^^ +//alternatives: explain alternatives and tell why they are not viable: + + + +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 + + +//endof_comments: + +'''' +Back to link:/documentation/devel/rfc.html[Lumiera Design Process overview] diff --git a/doc/devel/rfc_pending/GitCommitMessageFormat.txt b/doc/devel/rfc_pending/GitCommitMessageFormat.txt new file mode 120000 index 000000000..1de41b3f6 --- /dev/null +++ b/doc/devel/rfc_pending/GitCommitMessageFormat.txt @@ -0,0 +1 @@ +../rfc/GitCommitMessageFormat.txt \ No newline at end of file