Maintaining changelog in git notes?

[Vadim Zeitlin]

Hello,

I think it's very useful to have a manually maintained change log in our
docs/changes.txt file (although, arguably, it should be renamed to
CHANGES.md in the root directory for better visibility), but it's painful
to keep it updated as any changes to it in different branches (including
the most common case of changing it in a branch and on master) result in
conflicts. Such conflicts are easy to resolve, of course, but it's still a
hassle and, worse, they prevent the CI builds from running as AppVeyor and
Travis must be able to merge the branch without conflicts in order to test
it.

So I'd like to avoid modifying docs/changes.txt between the releases.
However I'd still like to keep the information which goes into it somewhere
as it won't be simple to review hundreds, if not thousands, of the commits
since the previous release to create a useful changelog otherwise.

There are several possibilities here. One is to just use the subject line
of some commits, but it's not clear how to distinguish between the commits
that should be mentioned in the change log and the other ones. This would
also impose the 66 length limitation on the change log lines, which seems
too draconian as I don't see any reason not to use the full 78 characters
available for them there. And the formats are not totally the same, e.g.
the commit subjects shouldn't end with the period while the lines in our
change log should. And the latter also traditionally contain the
contributor name -- although I think we should drop this and just have a
list of people who have contributed to each release instead.

So another possibility would be to have a specially formatted paragraph
inside the commit message body instead, e.g. something like

Change:
- Fix frobnicator quuxocity.

Then it would be relatively simple to write a script that would extract all
these lines from the commit bodies and dumps them into the change log file
before the release. However this is not ideal neither: first, this makes
the commit messages ugly as the brief change description will mostly
duplicate the rest of the commit message (and personally I really
appreciate having readable commit messages as I spend quite some time
reading them). Second, the commit messages are immutable which is
problematic in at least the following 2 cases: when you forget to describe
the change when committing (and this does happen) or when the change is
reverted later as there is no way to revert the change log entry (at least
not without writing a much more complicated script).

Because of this I finally decided to try something difficult: I've
somewhat spoiled the surprise by mentioning them in the subject of this
email, but what if we stored the changes in git notes? Notes are a poorly
known (AFAIK) and, I guess, not much loved, Git feature and working with
them is not very convenient, but they seem to be perfect for this kind of
use, as they can be associated with any commit, at any time, including
after making it and including removing the note when the commit is reverted
later and don't spoil the main commit message. I freely admit that they
could also have some fatal problems, as I've never used notes in Git
before, so I have no idea what might happen. And seeing that nobody else
seems to store the changes as notes is not exactly encouraging. But OTOH
what do we lose by trying?

Anyhow, I've started experimenting with them and attached 2 notes in
"changelog" notes namespaces (i.e. refs/notes/changelog) to 2 commits so
far. If you run

$ git fetch origin refs/notes/changelog:refs/notes/changelog

you should get them from GitHub and you can verify that

$ git notes --ref=changelog list

outputs 2 lines currently and running

$ git notes --ref=changelog|cut -d' ' -f1|xargs git show

results in the following output:

wxMSW: Fix compilation in deprecated ANSI build mode.
All: Fix MIME type for wxFSFile obtained from wxHTTP.

which can then be easily massaged in the changelog-appropriate form.

If nobody has any objections to this, I'd like to encourage the others to
also record information that should be included in the next release change
log in this way, i.e. do

$ git notes --ref=changelog add -m 'Section: description' $SHA1

to attach the given note (which may, of course, be also entered
interactively in the editor instead of specifying it via the -m option) to
the specified commit (HEAD if omitted) and then

$ git push origin refs/notes/changelog

to make them available on GitHub.

Please note that if you use notes and git-rebase, you almost certainly
want to also do

$ git config --global notes.rewriteRef "refs/notes/*"

to ensure that notes are rewritten too when rewriting the associated
commit.

Of course, as all our other conventions, participation in this one will be
entirely voluntary, but I'd appreciate if we could avoid changing
docs/changes.txt as it's really annoying to have to deal with the conflicts
in it, especially when juggling a few PRs at once as I typically do.

Thanks in advance and please let me know if you have any questions or, on
the contrary, any further advice about git notes!

VZ

[Danny Scott]

This looks reasonable to me, but I don't make that many commits.

If a brief explanation and the git commands are added to http://wxwidgets.org/develop/code-repository/ in the "Integrating Changes into wxWidgets" section there's an excellent chance it won't be forgotten (as often :)

--

Danny Scott