Ichthyostega
051cb31e28
The RfC documents were written to complement discussions of the Lumiera developers; yet since the time where ''Ichthyo'' is working basically alone on the project, this kind of discussions have ceased. During the following years, some ideas promoted by the existing RfC documents became rather detached from the actual state of development in the code base. Many of the existing RfC documents require some commentary to place them into context, and some of the decisions taken in the early stage of the project should be **re-assessed**. This includes the decision to reject some proposals, which initially might have seemed desirable, yet could not be reconciled with the understanding of the matter and topic in question, as was gained through the ongoing analysis and development.
225 lines
8 KiB
Text
225 lines
8 KiB
Text
Git Commit Message Format
|
|
=========================
|
|
|
|
// please don't remove the //word: comments
|
|
|
|
[options="autowidth"]
|
|
|====================================
|
|
|*State* | _Dropped_
|
|
|*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
|
|
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.
|
|
|
|
|
|
.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 approved (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>~
|
|
|
|
|
|
NOTE: This RfC is now superseded by using the _Git-flow branching scheme._
|
|
|
|
.State -> Dropped
|
|
|
|
With the recent move to link:{ldoc}/technical/code/GitBranching.html[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'
|
|
|
|
//endof_comments:
|
|
|
|
''''
|
|
Back to link:/x/DesignProcess.html[Lumiera Design Process overview]
|