On Thu, Sep 13, 2018 at 10:01:25AM +0100, Julian Foad wrote:
> It seems to me rather poor that readers of our CHANGES file have to manually follow references to revision numbers and issue numbers. Examples:
> [[[
> - Server-side bugfixes:
> * svnadmin dump shouldn't canonicalize svn:date (issue #4767)
> * 'svnadmin verify --keep-going --quiet' shows an error summary (r1837790)
> ]]]
>
> I have shortcuts defined in my browser for going to a revision or an issue by number, but must users don't, so I feel it is pretty unfriendly to them.
>
I don't think many people follow these references when reading CHANGES.
For descriptions of new features the release notes are a better reference
for users than committed revision diffs and issue tracker entries.
So users would likely only follow these references if they are curious
about the nature of a particular bug which was fixed. Which is natural
to do for us developers, but users most often don't care about that
level of detail so this won't happen very often.
I'm not saying these references were not important; they provide a great
deal of value to [potential] contributors and curious users.
> As the file format is pretty regular, would anyone care to contemplate
> post-processing it into HTML with the revision numbers and issue numbers as
> hyperlinks?
I believe a short note at the top of the file which explains how to
resolve these references would be sufficient. Something like this maybe:
To view a revision listed in change log entries below, visit:
https://svn.apache.org/rXXXX where XXXX is a revision number,
e.g. https://svn.apache.org/r1837790
To view an issue listed in change log entries below, visit:
https://issues.apache.org/jira/browse/SVN-XXXX where XXXX is an
issue number, e.g. https://issues.apache.org/jira/browse/SVN-4767
Received on 2018-09-13 12:37:39 CEST