[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Re: [PATCH] release.py: write-changelog function (POC)

From: Daniel Shahaf <d.s_at_daniel.shahaf.name>
Date: Thu, 14 Dec 2017 17:58:08 +0000

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

This is an archived mail posted to the Subversion Dev mailing list.