No highlights in the release notes

[Kwankyu Lee]

Hi,

The most powerful ever, a new beta, Sage 8.0.beta8, was just released. But as always, it is rather dull to look through the "release note". It would be good that there are "highlights" selected from the many ticket descriptions.

An author of a ticket might want to advertise the ticket by adding a few lines of refined sentences delivering more information about what the ticket is about and how great it is. If there is a special field in the ticket page of trac for the advertisement, then the author, if he or she wishes, can fill the field during the period after positive review before closing. The advertisements are then displayed in the release note, perhaps as grouped by their contribution component (like number field, documentation, etc).

All this of course should be automatic - no burden to the release manager.

As always, I have no idea of technical difficulties to implement this feature. If many of you wish, then someone might step up for the task...

Ps. I am aware that Volker proposed (and gave up) an idea for a similar purpose before.

[Sébastien Labbé]

For some time, Minh was writing highlighted release notes. Here is the last one I found of him (already 8 years ago):

https://mvngu.wordpress.com/2009/08/22/sage-4-1-1-released/

[Sébastien Labbé]

and some people helped him:

"Rob Beezer, Nathann Cohen, John Cremona, Simon King, Sébastien Labbé, and Jens Rasch contributed to writing this release tour."

[Kwankyu Lee]

On Thursday, May 25, 2017 at 10:46:22 PM UTC+2, Sébastien Labbé wrote:

For some time, Minh was writing highlighted release notes. Here is the last one I found of him (already 8 years ago):

https://mvngu.wordpress.com/2009/08/22/sage-4-1-1-released/

Wow, that is a great historic example of highlighted release notes! Thank you for sharing. Perhaps we could learn something from the example.

To continue the heritage, the authors should be supported and encouraged by the system to make writing a short note for highlights not a burden but a voluntary work motivated by desires to show off his or her work.

The release manager may have the right to crown the highlights with his own selection of the best highlights in the head of the release note. Thus we introduce a competition in highlights writing :-)

[Jori Mäntysalo]

How many developer does something to highlight **in a particular
release**?

As an example, I could put something like this for 8.0:

- Finite lattices now have function to compute congruence, and several
congruence-related functions like quotient lattice, lattice of congruences
and checks if a lattice is regular, uniform or isoform.

But in reality part of that is already on 7.6.

--
Jori Mäntysalo

[Kwankyu Lee]

On Friday, May 26, 2017 at 7:10:43 AM UTC+2, Jori Mäntysalo wrote:

How many developer does something to highlight **in a particular
release**?

I don't know. But who knows before we ask developers? 

 

As an example, I could put something like this for 8.0:

- Finite lattices now have function to compute congruence, and several
congruence-related functions like quotient lattice, lattice of congruences
and checks if a lattice is regular, uniform or isoform.

This is a nice example (if you remove the "part of that is already on 7.6."). Actually I think 2-3 sentences note should be enough. But the appropriate length would of course depend on the ticket. 

[Jori Mäntysalo]

On Fri, 26 May 2017, Kwankyu Lee wrote:

> As an example, I could put something like this for 8.0:
>
> - Finite lattices now have function to compute congruence, and several
> congruence-related functions like quotient lattice, lattice of congruences
> and checks if a lattice is regular, uniform or isoform.

> This is a nice example (if you remove the "part of that is already on
> 7.6."). Actually I think 2-3 sentences note should be enough. But the
> appropriate length would of course depend on the ticket. 

This was done in ~10 bigger ticket and another ~10 with small
modifications. As an example see https://trac.sagemath.org/ticket/21861

Hence the ticket system would be wrong place for this. For something like
this we should have a wiki page. It should have short guidelines, mostly
"Keep it simple and short!!!". It should concentrate on user viewpoint: It
may be that a backend function for version 8.1 takes much work and a
interface function for version 8.2 is quite trivial; then the developer
should say nothing in the highlights of 8.1.

--
Jori Mäntysalo

[Erik Bray]

I don't think the ticket system is necessarily the wrong place. It
would be trivial to add a field to the ticket to accept a changelog
entry (on Astropy hardly a feature / bug fix is allowed to be merged
without a decent changelog entry).

The one exception is something that is fixed between releases during
development--i.e. a change that does not represent a fix since the
last release.

For big changes consisting of multiple tickets there should generally
be a meta-ticket to organize things anyways, and that's where the
release notes should go.

[Simon King]

Hi!

On 2017-05-26, Kwankyu Lee <ekwa...@gmail.com> wrote:
> To continue the heritage, the authors should be supported and encouraged by
> the system to make writing a short note for highlights not a burden but a
> voluntary work motivated by desires to show off his or her work.

Perhaps it would be possible to have, in addition to the compulsory AUTHOR
and REVIEWER fields, in sage-trac a new optional field HIGHLIGHTS, that the
author can fill with some text if (s)he believes the ticket is worth it
and if the reviewer doesn't object.

Is it possible to add such a field in Trac without too much hassle?

Cheers,
Simon

[Simon King]

Hi Jori,

On 2017-05-26, Jori =?ISO-8859-1?Q?M=E4ntysalo?= <Jori.Ma...@uta.fi> wrote:
> This was done in ~10 bigger ticket and another ~10 with small
> modifications. As an example see https://trac.sagemath.org/ticket/21861
>
> Hence the ticket system would be wrong place for this. For something like
> this we should have a wiki page.

How do you come to that conclusion? New features are provided in trac tickets,
and thus trac is exactly the right place to highlight what a ticket
provides.

And how would you keep a wiki in sync with the tickets that are really
merged in a release? The ticket author would usually write the highlight
when (s)he is done writing the code, but it may be that it is merged
only much later.

> It should concentrate on user viewpoint: It
> may be that a backend function for version 8.1 takes much work and a
> interface function for version 8.2 is quite trivial; then the developer
> should say nothing in the highlights of 8.1.

How should the developer know what version he is supposed to write the
highlights for?

Best regards,
Simon

[Jori Mäntysalo]

On Fri, 26 May 2017, Simon King wrote:

>> This was done in ~10 bigger ticket and another ~10 with small
>> modifications. As an example see https://trac.sagemath.org/ticket/21861
>>
>> Hence the ticket system would be wrong place for this. For something like
>> this we should have a wiki page.
>
> How do you come to that conclusion? New features are provided in trac tickets,
> and thus trac is exactly the right place to highlight what a ticket
> provides.

I think that most tickets are not highlights, and those that are, are
usually made of smaller tickets. (As big enhancements are hard to review.)

> And how would you keep a wiki in sync with the tickets that are really
> merged in a release? The ticket author would usually write the highlight
> when (s)he is done writing the code, but it may be that it is merged
> only much later.

Mostly it should be done on rc-phase. But of course when you see your
ticket closed, you can think if you now have got something ready for
highlights.

--
Jori Mäntysalo

[Kwankyu Lee]

Perhaps it would be possible to have, in addition to the compulsory AUTHOR
and REVIEWER fields, in sage-trac a new optional field HIGHLIGHTS, that the
author can fill with some text if (s)he believes the ticket is worth it

The text should be refined, unlike the others that we usually write in a hurry.

 

and if the reviewer doesn't object.

The reviewer may actually be the author  of the text, or  a coauthor/editor

 

Is it possible to add such a field in Trac without too much hassle? 

And would it be possible that the release manager can collect them without too much hassle?  

[John Cremona]

I think it is a good idea to have highlights in the release notes,
otherwise we may give the impression that all we do is fix bugs
(sometimes). There must be many Sage users who do not bother to
upgrade every time, possibly basing that decision on whether anything
interestng strikes them in the release notes.

The person with the best overview of what's in a new release is the
release manager. He/she already does a lot, but could be the one to
ask authors of important tickets to write something at the point of
merging them.