Release note auto-generation RFC

[Volker Braun]

There is a somewhat painless approach to generating human-readable release notes using https://github.com/hawkowl/towncrier. As far as the ticket author is concerned, if you think that your ticket #12435 is of wider interest and should be announced then all you'd have to do is add a file

echo "Added the last twin prime" > newsfragments/12435.feature

Note that the fragment filename starts with the ticket number, so it won't conflict with other news fragments. Then, when making a new release, I concatenate the fragments into NEWS.rst as, for example, in https://github.com/hawkowl/towncrier/blob/master/NEWS.rst

[Simon King]

Hi Volker,

On 2017-01-11, Volker Braun <vbrau...@gmail.com> wrote:
> There is a somewhat painless approach to generating human-readable release
> notes using https://github.com/hawkowl/towncrier. As far as the ticket
> author is concerned, if you think that your ticket #12435 is of wider

> interest and should be announced then all you'd have to do is add a file...

To where? Certainly not to the Sage src tree.

Cheers,
Simon

[Volker Braun]

Yes, to the Sage src tree. That is, we would add a newsfragments directory somewhere under $SAGE_ROOT.

[Ralf Stephan]

If you want the name "Sage" (vs. "sage") it must be under src/Sage

like in https://trac.sagemath.org/ticket/22176

[Julien Puydt]

Hi,

I have to point out that this isn't auto-generated since a specific
command has to be entered.

I also notice that towncrier has pretty rough single-level structuring
(feature, bugfix, doc, removal, misc), which might be a bit limitative
for a large project like sagemath.

Wouldn't some directive like "If you think ticket #314159 is of wider
interest, all you have to do is to fill in the Changes-7.6.rst file"
make it possible to both drop this new tool and allow a richer
structure? Said Changes-<version>.rst could start as a copy from a
Changes-template.rst with a prepared structured, which the release
manager would prune at the last moment to remove empty sections.

Snark on #sagemath

[Kwankyu Lee]

Wouldn't some directive like "If you think ticket #314159 is of wider
interest, all you have to do is to fill in the Changes-7.6.rst file"
make it possible to both drop this new tool and allow a richer
structure? Said Changes-<version>.rst could start as a copy from a
Changes-template.rst with a prepared structured, which the release
manager would prune at the last moment to remove empty sections. 

I guess the idea is to have one "news fragment" file for one merged ticket instead of a single file that contains all news.

[Julien Puydt]

And my point is that this tool doesn't bring anything substantial : if
you have to get out of your way to add something to the news, then at
least do so for something nice and complete. In my opinion the
categories provided by towncrier make it a tiny convenience for a small
project and uninteresting for a large project.

Now, if towncrier made it possible to name the fragment files something
like 314159.features.algebraic-geometry.elliptic-curves and generated a
more structured changelog from that, that would be more convincing.
[Using a dictionary somewhere to turn the various filename chunks into
something human-readable and falling back to changing '-' to space and
capitalizing the first word, say].

Snark on #sagemath

[TB]

On 12/01/17 10:41, 'Julien Puydt' via sage-devel wrote:
> I have to point out that this isn't auto-generated since a specific
> command has to be entered.
>
> I also notice that towncrier has pretty rough single-level structuring
> (feature, bugfix, doc, removal, misc), which might be a bit limitative
> for a large project like sagemath.
>
> Wouldn't some directive like "If you think ticket #314159 is of wider
> interest, all you have to do is to fill in the Changes-7.6.rst file"
> make it possible to both drop this new tool and allow a richer
> structure? Said Changes-<version>.rst could start as a copy from a
> Changes-template.rst with a prepared structured, which the release
> manager would prune at the last moment to remove empty sections.
>
> Snark on #sagemath
>

What do you think about Debian packages' changelog format?
As a non-expert, I see one can easily add new entries with dch, and
there are tools which know how to parse the changelog file.

Regards,
TB

[Simon King]

On 2017-01-12, Volker Braun <vbrau...@gmail.com> wrote:
> Yes, to the Sage src tree. That is, we would add a newsfragments directory
> somewhere under $SAGE_ROOT.

Seriously???

[Ralf Stephan]

How else would the ticket authors associate a self-written blurb with

the respective branch? It must be committed via git. On release the

RM collects them all and removes the files.

Oh, and editing a NEWS file will produce merge conflicts. That's why

single files.

 

[Johan S. H. Rosenkilde]

I support the idea of providing users (and developers) with a NEWS file.
My first reaction to your suggestion with towncrier is to ask why it is
necessary to manually add news for a subset of tickets, instead of
auto-generating a NEWS file from all closed tickets.

Many tickets will be bug fixes or technical stuff, not very pleasant or
relevant to a user. But what if the "types" we have on tickets were more
meaningful, perhaps these could serve to divide such a NEWS file into
headings, e.g.

== New Features ==

24454: Added the last twin prime
....

== Enhancements ==

28042: A faster implementation of Q[x] factorisation
...

== Bug-fixes ==

25233: Fixed a crash when plotting.
...


Best,
Johan

[Dima Pasechnik]

Wouldn't it be better to relate news to closed/merged trac tickets?

This might need an extra trac feature allowing for tagging tickets for priority in the sense

of how much value a ticket adds.

(critical/blocker/major hierarchy is something different)

Then NEWS would come from harvesting ticket's summaries and arranging them 

w.r.t.  the value-adding priority.

This would be indeed almost painless, as opposed to extra files somewhere etc etc.

(This might even fit within some of ODK deliverables :-))

Dima

[Volker Braun]

The whole point of NEWS would be to have coarser granularity than individual tickets. E.g. 7.4 -> 7.5 is over 300 tickets, and a 300-item list is never a good answer to the question "whats new in this release". I would envision a list of, say, 10-20 highlights to have associated news fragments.

[Matthias Koeppe]

One could perhaps use metatickets on trac for that.

[Dima Pasechnik]

On Thursday, January 12, 2017 at 6:01:55 PM UTC, Volker Braun wrote:

The whole point of NEWS would be to have coarser granularity than individual tickets. E.g. 7.4 -> 7.5 is over 300 tickets, and a 300-item list is never a good answer to the question "whats new in this release". I would envision a list of, say, 10-20 highlights to have associated news fragments.

yes, right, so you'd tag these "interesting for NEWS" tickets on trac, using some kind of trac plugin.

[Kwankyu Lee]

On Thursday, January 12, 2017 at 8:10:54 PM UTC+1, Dima Pasechnik wrote:

On Thursday, January 12, 2017 at 6:01:55 PM UTC, Volker Braun wrote:

The whole point of NEWS would be to have coarser granularity than individual tickets. E.g. 7.4 -> 7.5 is over 300 tickets, and a 300-item list is never a good answer to the question "whats new in this release". I would envision a list of, say, 10-20 highlights to have associated news fragments.

yes, right, so you'd tag these "interesting for NEWS" tickets on trac, using some kind of trac plugin.

I guess Volker's idea is that the author of the ticket decides if his/her ticket is worth to be highlighted and provide a well-phrased blurb for general users.

[Erik Bray]

Yes, I support this. The idea is to have a high-level view that end
users can digest as to what changed as it impacts them. This
certainly *should* include bug fixes, but we're talking especially
runtime bugs that are fixed from one release to another (as opposed to
bugs that only occur during development and which appear and are
subsequently fixed only during development). Sometimes also build
bugs are worth reporting if, for example, building on a particular
platform is fixed between two releases. And of course new features,
etc.

If you autogenerate such a list just from ticket summaries or worse,
from the git changelog, it's not very digestible in that way. I'm
glad adding such a changelog is on the agenda.

[Dima Pasechnik]

at least you're autogenerating from something that is visible and reviewed.

Reviewed these extra pieces, as Volker proposes, to be written is an extra burden.

 

[Erik Bray]

You're basically saying that writing good documentation is an extra
burden. And of course that's true. But that's not an argument
against it.

Really we're talking about one or two sentence summaries of what was
changed. Often it can be the same as, or paraphrased from a commit
message or issue description.

Another possible alternative that I've seen used before is to use
special formatting in commit messages (especially for merge commits)
that can be parsed out for generating a changelog. This is fine too,
but just changes where the text is written, not the fact that it needs
to be written. It also still requires something to check that it is
correctly formatted for the parser.

[Dima Pasechnik]

it's not really documentation, it is more of advertising!

some kind of write-once read-never thing, many people won't be bothered.

[Kwankyu Lee]

On Friday, January 13, 2017 at 4:54:57 PM UTC+1, Dima Pasechnik wrote:

it's not really documentation, it is more of advertising!

some kind of write-once read-never thing, many people won't be bothered.

I also do not read change log for every release, but when my code is affected by some changes of the software, the official change log is my resort. I am thinking of release notes of Django project.

[Jori Mäntysalo]

On Fri, 13 Jan 2017, Erik Bray wrote:

> Yes, I support this. The idea is to have a high-level view that end
> users can digest as to what changed as it impacts them. This

> certainly *should* include bug fixes - -

What tickets should not be on the list? I think that most bugs should not
be listed in the high-level view.

If #1 adds foo() to graphs and #2 adds bar(), then the list should have
something like "Graph enchancements: foo() and bar()." Which ticket should
contain that information?

Hard question is this.

--
Jori Mäntysalo

[Matthias Koeppe]

On Friday, January 13, 2017 at 11:38:50 AM UTC-8, Jori Mäntysalo wrote:

If #1 adds foo() to graphs and #2 adds bar(), then the list should have
something like "Graph enchancements: foo() and bar()." Which ticket should
contain that information?

Meta-ticket #3 "Graph enhancements in Sage 7.6", which depends on and merges #1 and #2.

[Volker Braun]

On Friday, January 13, 2017 at 8:38:50 PM UTC+1, Jori Mäntysalo wrote:

If #1 adds foo() to graphs and #2 adds bar(), then the list should have
something like "Graph enchancements: foo() and bar()." Which ticket should
contain that information?

Ticket #2 could delete newsfragment/1.feature to aggregate the information in newsfragment/2.feature. This is one of the advantages of decoupling news from individual commits: the news is not immutable and can be edited before the release.

[Dima Pasechnik]

The dead journalists turn in their graves upon hearing about "mutable news"... ;-)

Cynically speaking, this will make a great tool for obtaining funding ---

one just needs to publish enough news, there is no need to turn up working code any more...

OK, I shut up now. Sorry for the flame.

Dima

 

[Dima Pasechnik]

One way or another, without human interference the news built this way will be skewed in some way.

We need a way to prioritise tickets in a way that would preclude bias.

The most natural would be polling of tickets for news-priority, and then aggregating the result of the poll

in a good way (there are results on how to fight bias this way, I am told).

Otherwise our news will go the way FB's news went. :-)

   

[William Stein]

Dima -- Are you (1) volunteering to build such a system, and just
asking for feedback, or (2) asking somebody else to do this?

Just curious, since it's not clear... If (1), what resources do you need/have?

-- William

>
>
> --
> You received this message because you are subscribed to the Google Groups
> "sage-devel" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to sage-devel+...@googlegroups.com.
> To post to this group, send email to sage-...@googlegroups.com.
> Visit this group at https://groups.google.com/group/sage-devel.
> For more options, visit https://groups.google.com/d/optout.



--
William (http://wstein.org)

[Dima Pasechnik]

On Sunday, January 15, 2017 at 6:58:38 PM UTC, William wrote:

On Sun, Jan 15, 2017 at 5:18 AM, Dima Pasechnik <dim...@gmail.com> wrote:
> On Wednesday, January 11, 2017 at 11:09:53 PM UTC, Volker Braun wrote:
>>
>> There is a somewhat painless approach to generating human-readable release
>> notes using https://github.com/hawkowl/towncrier. As far as the ticket
>> author is concerned, if you think that your ticket #12435 is of wider
>> interest and should be announced then all you'd have to do is add a file
>>
>> echo "Added the last twin prime" > newsfragments/12435.feature
>>
>> Note that the fragment filename starts with the ticket number, so it won't
>> conflict with other news fragments. Then, when making a new release, I
>> concatenate the fragments into NEWS.rst as, for example, in
>> https://github.com/hawkowl/towncrier/blob/master/NEWS.rst
>
>
> One way or another, without human interference the news built this way will
> be skewed in some way.
> We need a way to prioritise tickets in a way that would preclude bias.
> The most natural would be polling of tickets for news-priority, and then
> aggregating the result of the poll
> in a good way (there are results on how to fight bias this way, I am told).
> Otherwise our news will go the way FB's news went. :-)

Dima -- Are you (1) volunteering to build such a system, and just
asking for feedback, or (2) asking somebody else to do this?

Just curious, since it's not clear...   If (1), what resources do you need/have?

There is a deliverable in OpenDreamKit workpackage 7 where such a thing would fit.

The expertise to choose a suitable aggregation rule for the poll results is in house 

(literally - my wife does research on this sort of stuff, computational social choice :-)).

One has to decide how many tickets we want to highlight for a release. 30? 50?

 

Dima

[Erik Bray]

Except when they have a problem (and often even when they don't, such
as to check whether they can expect any problems with their code when
upgrading to a newer version--for example this is a place to announce
deprecations and API changes). I find it infuriating when projects
don't supply such a change log (especially if I do have a problem).
It's almost as infuriating when they don't timestamps in their
changelogs and there's no way to know when a version was released,
which is sometimes useful information.

[David Roe]

I don't think anyone's arguing that a changelog is a bad idea. The question is just whether it's easier to make from fragments in the repository or from a new field on trac. Personally I think trac, though being able to edit fragments from previous tickets is appealing. Either way, there should be a way to see the in-progress auto-generated changelog. 

--
You received this message because you are subscribed to the Google Groups "sage-devel" group.

To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscribe@googlegroups.com.

[kcrisman]

The expertise to choose a suitable aggregation rule for the poll results is in house 

(literally - my wife does research on this sort of stuff, computational social choice :-)).

True!  But she also knows there ain't no suitable rule for all definitions of suitable ... luckily it really shouldn't matter here, I would be surprised if there is a lot of buy-in for advertising the changes beyond ones that are obviously big e.g. including sage-matroids or significant upgrade to a dependency to fix a lot of bugs or something.   

Honestly, if you just give an optional trac line that unambiguously says something like "optional - release note advertisement" (better wording needed) then people who care will put something there. If it becomes a problem to just take this info from there because of too much or bad quality, then you could move to a poll.  But who will even bother showing up to vote on the poll?  You'll have "bias" either way, the natural one of self-selection.  I really don't think a ton of people are going to be saying "fixed one-character typo" is significant enough for release notes when they do it.  (Whether fixing lots of little bugs should show up is a different matter, but one that any ticket-by-ticket auto-generated thing won't solve.)

[Simon King]

On 2017-01-16, David Roe <roe...@gmail.com> wrote:
> I don't think anyone's arguing that a changelog is a bad idea. The question
> is just whether it's easier to make from fragments in the repository or
> from a new field on trac. Personally I think trac,

+1.

I know that some people believe it is old fashioned, but I still think
that the basic development unit is not a git commit but a merged trac
ticket. Thus, it seems to me that trac is the logical place to document
development.

Best regards,
Simon

[Thierry]

+1.

>
> Best regards,
> Simon

>
> --
> You received this message because you are subscribed to the Google Groups "sage-devel" group.

> To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+...@googlegroups.com.

[Erik Bray]

On Tue, Jan 17, 2017 at 1:48 PM, Thierry
<sage-goo...@lma.metelu.net> wrote:
> On Tue, Jan 17, 2017 at 12:35:48PM +0000, Simon King wrote:
>> On 2017-01-16, David Roe <roe...@gmail.com> wrote:
>> > I don't think anyone's arguing that a changelog is a bad idea. The question
>> > is just whether it's easier to make from fragments in the repository or
>> > from a new field on trac. Personally I think trac,
>>
>> +1.
>>
>> I know that some people believe it is old fashioned, but I still think
>> that the basic development unit is not a git commit but a merged trac
>> ticket. Thus, it seems to me that trac is the logical place to document
>> development.
>
> +1.

I have no problem with that (on some level even prefer it). Just as
long as it gets used!

If there's a field specifically in the Trac ticket for this, then it
would be easy to auto-generate a changelog using all the fields in the
ticket. It would help if "milestone" were actually tied to a release
too.