Ichthyostega
b556d2b770
Some sections of the Lumiera website document meeting minutes, discussion protocols and design proposals from the early days of the project; these pages were initially authored in the »Moin Moin Wiki« operated by Cehteh on pipapo.org at that time; this wiki backed the first publications of the »Cinelerra-3« initiative, which turned into the Lumiera project eventually. Some years later, those pages were transliterated into Asciidoc semi-automatically, resulting in a lot of broken markup and links. This is a long standing maintenance problem problem plaguing the Lumiera website, since those breakages cause a lot of warnings and flood the logs of any linkchecker run.
180 lines
5.8 KiB
Text
180 lines
5.8 KiB
Text
Git Commit Message Format
|
|
=========================
|
|
|
|
// please don't remove the //word: comments
|
|
|
|
[options="autowidth"]
|
|
|====================================
|
|
|*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 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>~
|
|
|
|
|
|
//endof_comments:
|
|
|
|
''''
|
|
Back to link:/x/DesignProcess.html[Lumiera Design Process overview]
|