Background
Invenio commit log messages have standardised format described in:
- https://github.com/inveniosoftware/invenio/blob/master/CONTRIBUTING.rst (recommendation 6)
- http://invenio-software.org/wiki/Tools/Git/Workflow#R2.Remarksoncommitlogmessages
Besides better QA, better readability, easier future bisecting, etc,
this permits also to prepare release notes in an automated manner.
This works OK for small incremental update releases with 100+
commits:
- https://raw.githubusercontent.com/inveniosoftware/invenio/v1.1.4/RELEASE-NOTES
but it does not work so well for large feature releases consisting of 1000+
commits, as the recent v1.2.0 and v2.0.0 releases:
- https://raw.githubusercontent.com/inveniosoftware/invenio/v1.2.0/RELEASE-NOTES
- https://raw.githubusercontent.com/inveniosoftware/invenio/v2.0.0/RELEASE-NOTES
The problems include:
- Shortness of messages. The commit message headline is limited to
some 50 characters, which is good for being concise, however this is
often not sufficient to express given change with reasonable
clarity to the end users.
- Nature of changes. We have started to use "NOTE" in the commit logs
to attract attention to important (compatibility) changes, however
this is not enough to inform the user about the nature of the
change. "Is it a new feature? A bug fix? Or just some internal
refactoring that I don't have to care about?"
- One feature branch may consist of many commits, while for the
reporting we may only need one item. Some of the commits may be
better "silenced" in the high-level end-user report.
Proposal
Let's introduce richer structural markup in our commit log messages
that would address these drawbacks so that we could generate nicer,
more informative progress reports in between releases, and release
notes later.
Sphinx can serve as an example of what I have in mind:
- http://sphinx.readthedocs.org/en/latest/changes.html#release-1-2-3-released-sep-1-2014
There are basically two approaches how to address this: (1) via commit
log messages; (2) via tickets (issues, pull requests).
Option 1: use richer structure in commit messages
We could use more leading labels besides NOTE, for example:
foo: better support for xyzzy and zyxxy
* FEATURE Foo now supports xyzzy in all the user facing web pages.
* FIX Corrects interface to Zyxxy...
* INCOMPATIBLE Removes foo...
Reviewed-by: John Doe
(Side note: instead of textual labels, we could use a subset of
standard emojis that GitHub
supports, say :bug:
instead of FIX
, bringing additional eye
candy to our commit logs.)
The richer commit log message structure could be checked by and
enforced via kwalitee
tool that every programmer should run before
making pull requests anyway.
Advantage: git repository has all the information about our
software; this "preserves history"; it is usable offline; it is
independent of the ticketing system we use; it is close to
acked-by/reviewed-by directives.
Disadvantage: once committed, the information cannot be changed;
the integrators should pay extra attention and should promote
forward-thinking about formulating user-visible changes.
Option 2: use ticket tracker
Everything we are dealing with has an issue on GitHub, and we triage
our issues with labels and milestones for release planning and
priorities:
- https://forum.invenio-software.org/t/triaging-issues-labels-milestones/58
Hence, instead of enriching the commit log message, we could store
release note like information in GitHub issues. E.g. github issues
title could be used for item reporting, and could be made more verbose
that the commit log message headline.
Since our NOTE label contain verbose text to be displayed to users,
we'd have to store such a structured information an extra comments,
for example structured in YAML style:
notes:
feature:
- Foo now supports xyzzy in all the user facing web pages.
fix:
- Corrects interface to Zyxxy...
incompatible_change:
- Removes foo...
Advantage: messages can be easily edited after commit is done; "user
insignificant commits" can be grouped in one single issue/PR/branch;
usage of issues drives us to use tickets for everything, improving
visibility/milestone/planning.
Disadvantage: bound to concrete ticketing system; offline usage is
impossible; it is easy to "destroy history"; the notes are stored
outside of acked-by/tested-by/reviewed-by information (unless we
refactor this one too); extra information storage via issue comment
looks kind of ugly.
Option 3: use git notes
We could use other techniques, such as git notes, where integrators
can store the further information about commits. However, we've
discussed that before
and found the usage of git notes not that attractive.
WDYT?
Which of these directions do you prefer?
Label set
Whatever technique we'll happen to prefer, we should muse in parallel
about the suitable label set to use.
For example:
| label | meaning |
| --- | --- |
| FEATURE | commits adds a new feature |
| IMPROVEMENT | commit improves an existing feature |
| REMOVAL | commit removes some feature |
| FIX | commit fixes a bug |
| DOCUMENTATION | no code, just docs |
| REFACTORING | no user-facing changes |
| COMPATIBILITY | compatibility remarks, dropping Python-2.6 |
| NOTE | general note |
Branch: master