Johan Corveleyn wrote on Mon, Dec 04, 2017 at 12:16:37 +0100:
> As promised on IRC last Friday, here is a POC implementation of the
> "generate changelog from commit messages" functionality,
We had some more discussion about this on IRC last Monday¹; I'll try to
summarize.
Goal: reduce the workload of generating CHANGES before a (primarily minor)
release, via tags in log messages.
Open question #1: Whether this should be a whitelist or a blacklist (i.e.,
whether the script takes all log messages except those that opt out, or vice
versa).
Open question #2: With a whitelist approach, should we have a way to indicate
"This commit does not need to be added to CHANGES" explicitly (as opposed to
implicitly through the lack of any CHANGES magic syntax).
Open question #3: Should we generate the CHANGES line from the first line of
the commit message, or from a separate line (analogous to "Patch by:" lines).
Open question #4: What should the syntax be exactly.
Personally, my answers are^W^W proposal is:
- Use a whitelist approach. To ensure everything noteworthy gets mentioned, we
look for missing CHANGES taglines in log messages as part of our ordinary
post-commit review of commits@ traffic. The rationale here is not to encumber
trivial commits with the need to explicitly opt-out.
- We invent some convention (possibly, but not necessarily, a parseable one) to
explicitly indicate "This commit shouldn't be added to CHANGES", in order to
avoid people wondering whether the omission of a CHANGES tagline was
deliberate or an oversight. (I believe this aligns with Stefan Hett's
$WORK's experience with this convention.)
Thus, every significant commit should have either a CHANGES tagline or
CHANGES opt-out tag; and if a significant commit has neither, then we ask
about that in a post-commit review and, if needed, propedit the log message
to add a CHANGES tagline.
- The CHANGES tagline can be either a separate line in the log message, or the
first line of the log message. The rationale here is that the target
audiences are different, so sometimes the descriptions should be different,
but when the descriptions happen to be identical, avoid duplicated effort by
the log message author. For example:
[[[
svnsync: Make everything better. U[client]
* subversion/svnsync/svnsync.c
⋮
]]]
[[[
ra_svn: Fix a 30 years old bug in the protocol version number comparison
logic.
U[client and server]: ra_svn: Restore interoperability with 1.42.x, broken by 1.42.3.
* subversion/libsvn_ra_svn/greeting.c
⋮
]]]
- For the syntax, U[client] for "User-visible changes"/"Client-side bugfixes"
and similar syntaxes for the other CHANGES groups. The parser will look for
U[…] and D[…] where the ellipses stand for zero or more words. We'll
probably come up with a standardish set of abbreviations here, reflecting the
categorisation of items in CHANGES. The syntax for "explicitly not for
CHANGES" can then be the words "Not for CHANGES." as a standard formula (like
"No functional change." is a standard formula) or some parseable thing (e.g.,
"U[no]").
Whenever the CHANGES tagline is not the first line of the log message, we
might find it useful to give it some constant prefix, e.g.,
.
[[[
ra_svn: Fix a 30 years old bug in the protocol version number comparison
logic.
c: U[client and server]: ra_svn: Restore interoperability with 1.42.x, broken by 1.42.3.
]]]
.
for easier / unambiguous parsing.
WDYT?
Cheers,
Daniel
P.S. I'm going to include CHANGES information in my future commits, because
that will make our job writing CHANGES easier. After all, CHANGES text is
better written by the author of the commit than by the RM, isn't it?
¹ http://colabti.org/irclogger/irclogger_log/svn-dev?date=2017-12-11#l157
Received on 2017-12-14 18:58:16 CET