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

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

From: Johan Corveleyn <jcorvel_at_gmail.com>
Date: Mon, 4 Dec 2017 12:16:37 +0100

As promised on IRC last Friday, here is a POC implementation of the
"generate changelog from commit messages" functionality, added to
release.py (I'm not very experienced in Python; I mainly depend on
google, SO, copy-paste, ... so don't focus on coding style etc).

This patch is intended to enable further discussion of this idea
(which was already discussed on this list 4 years ago [1]).

The idea is that we agree on some structured syntax for adding
(optionally) a changelog text to commit messages, to make it easier
for RMs to generate the text for CHANGES (and push the responsibility
for writing a good CHANGES entry first and foremost to the original
committer; and keep the relevant info coupled with the commit). RMs
can use the output of write-changelog as a draft, they can still edit
it, summarize items, shuffle things around, ... But it gives them a
rough version to start from.

Proposal for changelog syntax in commit messages (as implemented in this patch):
Changelog lines are lines with the following format:
  '['<visibility>:<section>']' <message>
where <visibility> = U (User-visible) or D (Developer-visible)
      <section> =
                  (section is treated case-insensitively)
      <message> = the actual text for CHANGES

  [U:major] Better interactive conflict resolution for tree conflicts
  [U:minor] ra_serf: Adjustments for serf versions with HTTP/2 support
  [U:client] Fix 'svn diff URL_at_REV WC' wrongly looks up URL_at_HEAD (issue #4597)
  [U:client-server] Fix bug with canonicalizing Window-specific
drive-relative URL
  [D:api] New svn_ra_list() API function
  [D:bindings] JavaHL: Allow access to constructors of a couple JavaHL classes

Q: Shorter prefix syntax ([U:C], [U:CS], [U:MJ], ...) to keep lines
short, or longer (and put message on next line) to make it more
human-readable? While making it easily rememberable for devs so they
don't have to look it up all the time when they just want to commit

Q: What to do with merged revisions? Use 'log -g', or make sure
relevant changelog entry is part of the commit message of the merge? I
vote for the latter, it's simpler and has less surprises. In case of
feature branches, a generic "Add feature foo" message on the
reintegrate commit usually suffices. In case of backports perhaps our
backport script can scrape the relevant changelog entries from the
revisions-to-be-merged and add them to the commit message of the

To get a rough idea: since we don't have any commit messages
containing such lines in our history, I've added a --pocfirstlines
option, which just takes the first line of every log message (ignoring
lines with 'STATUS', 'CHANGES', 'bump', or starting with '*'), putting
them in the "User -> General" section.

Here is the usage output:
$ ./release.py write-changelog -h
usage: release.py write-changelog [-h] [--pocfirstlines] branch previous

positional arguments:
  branch The branch (or tag or trunk), relative to ^/subversion/, of
                   which to generate the changelog, when compared to
  previous The "previous" branch or tag, relative to ^/subversion/, to
                   compare "branch" against.

optional arguments:
  -h, --help show this help message and exit
  --pocfirstlines Proof of concept: just take the first line of each relevant
                   commit messages (except if it contains 'STATUS', 'CHANGES'
                   or 'bump' or starts with '*'), and put it in User:General.

Example output:
$ ./release.py write-changelog --pocfirstlines branches/1.9.x tags/1.9.7
 User-visible changes:
  - General:
    * Merge r1804691 and r1804692 from trunk: (r1804698)
  - Client-side bugfixes:
  - Server-side bugfixes:
  - Bindings bugfixes:

 Developer-visible changes:
  - General:
  - API changes:

$ ./release.py write-changelog --pocfirstlines branches/1.8.x tags/1.8.19
 User-visible changes:
  - General:
    * Merge r1804691 from trunk: (r1804723)
    * On the 1.8.x branch: Merge r1804692 from trunk. (r1804737)
  - Client-side bugfixes:
  - Server-side bugfixes:
  - Bindings bugfixes:

 Developer-visible changes:
  - General:
  - API changes:

$ ./release.py write-changelog --pocfirstlines trunk tags/1.9.7
 User-visible changes:
  - General:
    * A bug fix and minor tweaks in 'svnmover'. (r1715781)
    * A cosmetic tweak: add a final comma to lists of tests in a few
test files (r1706965)
    * A few FSFS-only tests apply to FSX just as well. So, run them
for (r1667524)
    * A follow-up to r1715354. (r1715358)
    * A minor code cleanup in FSFS. (r1740722)
    * A minor tweak in 'svnmover'. (r1717793)
    * A small step towards making 'svnmover merge' operate into a new
temporary (r1717957)
    * Abbreviate the potentially rather long list of revisions shown
for tree (r1736063)
    * Actually use some helpful error messaging that we bother to
create in (r1683161)
    * Add "merge_" prefix to the names of conflict resolver merge test
sandboxes. (r1749457)
    * Add '--include' and '--exclude' options to 'svnadmin dump'. (r1811992)
    * Add '--search' option support to 'svnbench null-list'. (r1767202)
    * Add 'http-compression=auto' mode on the client, now used by
default. (r1803899)


[1] https://lists.apache.org/thread.html/c80dd19a7bbafc4f535382b3f361f76ba6535ab3d447a8b988594bfc@1377814810@%3Cdev.subversion.apache.org%3E


Received on 2017-12-04 12:17:10 CET

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