You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Julian Foad <ju...@apache.org> on 2018/09/13 09:01:25 UTC
Suggestion: linkify revnums and issues in the CHANGES file
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.
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 would suggest keeping the current file format as the original and posting the processed version somewhere. A static link in the original (text file) could point to the canonical URL of the HTML version. Just a trunk version would be sufficient initially, updated at least at every release and preferably more often.
--
- Julian
Re: Suggestion: linkify revnums and issues in the CHANGES file
Posted by Julian Foad <ju...@apache.org>.
Julian Foad wrote:
> Stefan Sperling wrote:
> > 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 [...]
>
> That's a good start (let's do it), [...]
I added a comment to the CHANGES file, based on that suggestion, in http://svn.apache.org/r1840799 .
--
- Julian
Re: Suggestion: linkify revnums and issues in the CHANGES file
Posted by Julian Foad <ju...@apache.org>.
Branko Čibej wrote:
> Stefan Sperling wrote:
> > How about we provide a linkified version of CHANGES in our
> > release notes HTML pages? [...] based on only the respective
> > release's section of the CHANGES file [...]. For instance, the page
> > http://subversion.apache.org/docs/release-notes/1.10.html would be
> > updated with 1.10.x CHANGES entries each time a 1.10.x release is made.
>
> +1. I have a bit of time tonight to have a go at the scripting.
That sounds like a very nice solution. Thanks!
--
- Julian
Re: Suggestion: linkify revnums and issues in the CHANGES file
Posted by Branko Čibej <br...@apache.org>.
On Thu, 13 Sep 2018, 22:23 Branko Čibej, <br...@apache.org> wrote:
> On 13.09.2018 13:08, Branko Čibej wrote:
> > On 13.09.2018 13:01, Stefan Sperling wrote:
> >> It should not be too hard to automate the process. The release.py
> >> script already has some commands which spit out HTML snippets for
> >> the news pages so it might as well be parsing CHANGES and produce
> >> HTML we can paste into the website.
> > +1. I have a bit of time tonight to have a go at the scripting.
>
>
> r1840861 is a very simple first attempt that only does regular
> expression replacement. In particular, here are some things it can't do:
>
> * Convert issue numbers that aren't decorated with a '#' — there are a
> number of places where in a list of issues only the first number
> starts with #, but others don't.
> * Detect revision numbers that don't start with an 'r'. In some places
> the 'r' is missing, but especially in early entries we write
> 'revision X' instead of 'rX'.
> * Understand fancy revision number range shorthands, e.g., 'r1704854,
> -88'.
> * Convert old, pre-ASF revision numbers to links in the ASF
> repository. This is a direct result of doing simple string
> replacements instead of trying to interpret the string contents.
>
> Some of these issues can be solved by editing the CHANGES file to add
> the missing 'r' and '#' decorations. Adding a regular expression that
> detects 'revision X' is simple. Automagically converting pre-ASF
> revision numbers will require a different approach to the conversion, at
> least for revision numbers.
>
Oh, the script also doesn't html-escape the rest of the text, but that
doesn't seem to matter for now.
Re: Suggestion: linkify revnums and issues in the CHANGES file
Posted by Branko Čibej <br...@apache.org>.
On 13.09.2018 13:08, Branko Čibej wrote:
> On 13.09.2018 13:01, Stefan Sperling wrote:
>> It should not be too hard to automate the process. The release.py
>> script already has some commands which spit out HTML snippets for
>> the news pages so it might as well be parsing CHANGES and produce
>> HTML we can paste into the website.
> +1. I have a bit of time tonight to have a go at the scripting.
r1840861 is a very simple first attempt that only does regular
expression replacement. In particular, here are some things it can't do:
* Convert issue numbers that aren't decorated with a '#' — there are a
number of places where in a list of issues only the first number
starts with #, but others don't.
* Detect revision numbers that don't start with an 'r'. In some places
the 'r' is missing, but especially in early entries we write
'revision X' instead of 'rX'.
* Understand fancy revision number range shorthands, e.g., 'r1704854,
-88'.
* Convert old, pre-ASF revision numbers to links in the ASF
repository. This is a direct result of doing simple string
replacements instead of trying to interpret the string contents.
Some of these issues can be solved by editing the CHANGES file to add
the missing 'r' and '#' decorations. Adding a regular expression that
detects 'revision X' is simple. Automagically converting pre-ASF
revision numbers will require a different approach to the conversion, at
least for revision numbers.
-- Brane
Re: Suggestion: linkify revnums and issues in the CHANGES file
Posted by Branko Čibej <br...@apache.org>.
On 13.09.2018 13:01, Stefan Sperling wrote:
> On Thu, Sep 13, 2018 at 11:50:57AM +0100, Julian Foad wrote:
>> Stefan Sperling wrote:
>>> I don't think many people follow these references when reading CHANGES.
>> [...]
>>> 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 [...]
>> That's a good start (let's do it), but it feels unprofessional and backward
>> to me to not provide linked information in a software project in this
>> century. It is one of many little things that together add up to a poor
>> usability, and I would like to improve the usability of the project as a
>> whole, and this is one way to do so.
> How about we provide a linkified version of CHANGES in our
> release notes HTML pages? We could add a 'Detailed Changelog' section,
> in addition to linking to the CHANGES file as these pages already do.
>
> The contents of this new section would be based on only the respective
> release's section of the CHANGES file as shipped in release tarballs,
> with links added. For instance, the page
> http://subversion.apache.org/docs/release-notes/1.10.html would be
> updated with 1.10.x CHANGES entries each time a 1.10.x release is made.
>
> It should not be too hard to automate the process. The release.py
> script already has some commands which spit out HTML snippets for
> the news pages so it might as well be parsing CHANGES and produce
> HTML we can paste into the website.
+1. I have a bit of time tonight to have a go at the scripting.
-- Brane
Re: Suggestion: linkify revnums and issues in the CHANGES file
Posted by Stefan Sperling <st...@elego.de>.
On Thu, Sep 13, 2018 at 11:50:57AM +0100, Julian Foad wrote:
> Stefan Sperling wrote:
> > I don't think many people follow these references when reading CHANGES.
> [...]
> > 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 [...]
>
> That's a good start (let's do it), but it feels unprofessional and backward
> to me to not provide linked information in a software project in this
> century. It is one of many little things that together add up to a poor
> usability, and I would like to improve the usability of the project as a
> whole, and this is one way to do so.
How about we provide a linkified version of CHANGES in our
release notes HTML pages? We could add a 'Detailed Changelog' section,
in addition to linking to the CHANGES file as these pages already do.
The contents of this new section would be based on only the respective
release's section of the CHANGES file as shipped in release tarballs,
with links added. For instance, the page
http://subversion.apache.org/docs/release-notes/1.10.html would be
updated with 1.10.x CHANGES entries each time a 1.10.x release is made.
It should not be too hard to automate the process. The release.py
script already has some commands which spit out HTML snippets for
the news pages so it might as well be parsing CHANGES and produce
HTML we can paste into the website.
Re: Suggestion: linkify revnums and issues in the CHANGES file
Posted by Julian Foad <ju...@apache.org>.
Stefan Sperling wrote:
> I don't think many people follow these references when reading CHANGES.
[...]
> 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 [...]
That's a good start (let's do it), but it feels unprofessional and backward to me to not provide linked information in a software project in this century. It is one of many little things that together add up to a poor usability, and I would like to improve the usability of the project as a whole, and this is one way to do so.
--
- Julian
Re: Suggestion: linkify revnums and issues in the CHANGES file
Posted by Stefan Sperling <st...@elego.de>.
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
Re: Suggestion: linkify revnums and issues in the CHANGES file
Posted by Stefan Sperling <st...@elego.de>.
On Thu, Sep 13, 2018 at 12:00:39PM +0200, Branko Čibej wrote:
> Given all the debate we've had about how to edit and merge the CHANGES
> file on trunk and release branches ... how about only having the change
> log in the wiki, with CHANGES containing only a pointer to the wiki page?
My impression is that shipping CHANGES in tarballs is rather
important for our downstream consumers.
Consumers of our source tarballs are generally system packagers who
need a quick overview of what has changed. Some of them also copy
parts of our changelog into files of their own, e.g. SUSE does this
and is able to display changelog entries to their users during
system upgrades. A plaintext file is very useful in those cases,
but a separate page has numerous drawbacks: Getting a non-marked-up
text representation is cumbersome, the service might not be reachable
at a given momtent for various reasons, the wiki text may change over
time while it is constant in a released version.
Re: Suggestion: linkify revnums and issues in the CHANGES file
Posted by Branko Čibej <br...@apache.org>.
On 13.09.2018 11:18, Johan Corveleyn wrote:
> On Thu, Sep 13, 2018 at 11:01 AM Julian Foad <ju...@apache.org> 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.
>>
>> 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 would suggest keeping the current file format as the original and posting the processed version somewhere. A static link in the original (text file) could point to the canonical URL of the HTML version. Just a trunk version would be sufficient initially, updated at least at every release and preferably more often.
>>
> I suggest to create a wiki variant (with hyperlinks) on our Confluence
> wiki, rather than just a HTML-ized version. That should be doable to
> automate, to go over the plain text version and replace #4767 into
> [#4767|https://.../SVN-4767] etc.
>
> (sorry, I'm not volunteering right now, it's just a suggestion -- I
> might find some time in a couple of weeks, but not immediately ... so
> if anyone else feels inclined ...)
Given all the debate we've had about how to edit and merge the CHANGES
file on trunk and release branches ... how about only having the change
log in the wiki, with CHANGES containing only a pointer to the wiki page?
-- Brane
Re: Suggestion: linkify revnums and issues in the CHANGES file
Posted by Johan Corveleyn <jc...@gmail.com>.
On Thu, Sep 13, 2018 at 11:01 AM Julian Foad <ju...@apache.org> 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.
>
> 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 would suggest keeping the current file format as the original and posting the processed version somewhere. A static link in the original (text file) could point to the canonical URL of the HTML version. Just a trunk version would be sufficient initially, updated at least at every release and preferably more often.
>
I suggest to create a wiki variant (with hyperlinks) on our Confluence
wiki, rather than just a HTML-ized version. That should be doable to
automate, to go over the plain text version and replace #4767 into
[#4767|https://.../SVN-4767] etc.
(sorry, I'm not volunteering right now, it's just a suggestion -- I
might find some time in a couple of weeks, but not immediately ... so
if anyone else feels inclined ...)
--
Johan
Re: Suggestion: linkify revnums and issues in the CHANGES file
Posted by Paul Hammant <pa...@hammant.org>.
Markdown seems ubiquitous nowadays. In its raw form it is human readable,
as well as being machine-parsable into HTML / PDF, etc.
Git's README is markdown (https://github.com/git/git/blob/master/README.md)
but the releases notes are still plain text (
https://raw.githubusercontent.com/git/git/master/Documentation/RelNotes/2.19.0.txt).
I realize those are two contradictory datapoints. Ho hum :-(
- Paul