Hello!
For sake of making future releases easier, can we please:
- keep ChangeLog up to date
- ensure ChangeLog content is in vague sync with commit messages (not
exact, as it would defeat the purpose, but at least approximate)
- make sure our commit messages are cleaner
Examples with minor edits for formatting follow. Note that this looks
to be a problem across the board with all committers, nobody in
particular:
====
git commit message:
"Fix crash in gdomap when an invalid hostname is given for the -M option"
changelog message:
"* Tools/domap.c:
Fix crash in donames() when getaddrinfo returns an error"
I find the first one much more useful for a newsfile; but the second
one is useful implementation detail. I would argue both should be in
both changelog and commit message. But this is still fine and
understandable.
====
git commit messages:
"Fix wrong \U sequence for leter `i` and short weekdays."
"Update ChangeLog for last commit to Ukrainian language."
"Merge pull request #35 from trunkmaster/master: Updates for Ukrainian language"
changelog message:
"* Resources/Lanuages/Ukrainian:
Fix wrong \U sequence for letter 'i' and short weekdays."
Knowing in commit message that the change was done to the Ukrainian
language would be useful. Sure, I can pass --stat to git log -r
${PREVRELEASE}..master --reverse, but a clearer message (especially
the first line, the one usually up to 70ch) would be better.
Especially since --stat actually makes the whole log way harder to read.
====
git commit message:
"Correct implementation of method."
"Correct method names."
changelog message:
nothing on April 9, but there is a more detailed message on April 12
-- presumably this is because this is a merged larger chain of
messages?
This is generally fine if I could be sure ChangeLog is reliable and
consistently up to date. I'm reviewing logs as I am actually not sure
this is the case. Then, a message that says "fixed method" and nothing
else isn't helpful. File changed is Source/NSString.m, so I suspect
the longer message about character sets actually applies, but still...
Clearly I can and will be happy to release as-is and I will try to
keep release notes useful to anyone that may want to peek at them.
However, continued vigilance *when* making a commit -- it means not
only people stay up to date *at the time of making a commit*, but also
helps whomever happens to be cutting the release 15 months later.
Please, write the commit messages as if people view the commits
standalone. Please, write them as if someone is reading through them
without context over a year later.
Am I myself writing commit messages and changelog entries right? No
idea; I can only share with you the experience while cutting a
release. For entertainment purposes, take 1-2min and try to consider
how you'd write release notes from the output of this:
PREVRELEASE=$(git describe --abbrev=0) # should be: base-1_26_0
git log -r ${PREVRELEASE}..master --reverse
git diff -r ${PREVRELEASE}..master ChangeLog
:-)
