Re: [sage-devel] Re: Release note auto-generation RFC

[Erik Bray]

On Tue, Jan 17, 2017 at 1:48 PM, Thierry
 wrote:
> On Tue, Jan 17, 2017 at 12:35:48PM +, Simon King wrote:
>> On 2017-01-16, David Roe  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.

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Release note auto-generation RFC

[Thierry]

On Tue, Jan 17, 2017 at 12:35:48PM +, Simon King wrote:
> On 2017-01-16, David Roe  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.

> 
> 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+unsubscr...@googlegroups.com.
> To post to this group, send email to sage-devel@googlegroups.com.
> Visit this group at https://groups.google.com/group/sage-devel.
> For more options, visit https://groups.google.com/d/optout.

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Release note auto-generation RFC

[Simon King]

On 2017-01-16, David Roe  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

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Release note auto-generation RFC

[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.)

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Release note auto-generation RFC

[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.

On Jan 16, 2017 08:23, "Erik Bray"  wrote:

> On Fri, Jan 13, 2017 at 4:54 PM, Dima Pasechnik  wrote:
> >
> >
> > On Friday, January 13, 2017 at 3:41:23 PM UTC, Erik Bray wrote:
> >>
> >> On Fri, Jan 13, 2017 at 4:32 PM, Dima Pasechnik 
> wrote:
> >> >
> >> >
> >> > On Friday, January 13, 2017 at 11:15:49 AM UTC, Erik Bray wrote:
> >> >>
> >> >> On Thu, Jan 12, 2017 at 9:48 PM, Kwankyu Lee 
> wrote:
> >> >> >
> >> >> >
> >> >> > 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.
> >> >>
> >> >> 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.
> >> >
> >> >
> >> > 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.
> >>
> >> 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.
> >
> >
> > it's not really documentation, it is more of advertising!
> >
> > some kind of write-once read-never thing, many people won't be bothered.
>
> 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.
>
> --
> 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+unsubscr...@googlegroups.com.
> To post to this group, send email to sage-devel@googlegroups.com.
> Visit this group at https://groups.google.com/group/sage-devel.
> For more options, visit https://groups.google.com/d/optout.
>

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Release note auto-generation RFC

[Erik Bray]

On Fri, Jan 13, 2017 at 4:54 PM, Dima Pasechnik  wrote:
>
>
> On Friday, January 13, 2017 at 3:41:23 PM UTC, Erik Bray wrote:
>>
>> On Fri, Jan 13, 2017 at 4:32 PM, Dima Pasechnik  wrote:
>> >
>> >
>> > On Friday, January 13, 2017 at 11:15:49 AM UTC, Erik Bray wrote:
>> >>
>> >> On Thu, Jan 12, 2017 at 9:48 PM, Kwankyu Lee  wrote:
>> >> >
>> >> >
>> >> > 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.
>> >>
>> >> 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.
>> >
>> >
>> > 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.
>>
>> 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.
>
>
> it's not really documentation, it is more of advertising!
>
> some kind of write-once read-never thing, many people won't be bothered.

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.

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Release note auto-generation RFC

[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  > 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

>
>  -- 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) 
>

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Release note auto-generation RFC

[William Stein]

On Sun, Jan 15, 2017 at 5:18 AM, Dima Pasechnik  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?

 -- 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+unsubscr...@googlegroups.com.
> To post to this group, send email to sage-devel@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)

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Release note auto-generation RFC

[Dima Pasechnik]

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. :-)
   

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Release note auto-generation RFC

[Dima Pasechnik]

On Friday, January 13, 2017 at 10:05:56 PM UTC, Volker Braun wrote:
>
> 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.
>

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
 

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Release note auto-generation RFC

[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.

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Release note auto-generation RFC

[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.

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Release note auto-generation RFC

[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

Re: [sage-devel] Re: Release note auto-generation RFC

[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.

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Release note auto-generation RFC

[Dima Pasechnik]

On Friday, January 13, 2017 at 3:41:23 PM UTC, Erik Bray wrote:
>
> On Fri, Jan 13, 2017 at 4:32 PM, Dima Pasechnik  > wrote: 
> > 
> > 
> > On Friday, January 13, 2017 at 11:15:49 AM UTC, Erik Bray wrote: 
> >> 
> >> On Thu, Jan 12, 2017 at 9:48 PM, Kwankyu Lee  
> wrote: 
> >> > 
> >> > 
> >> > 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. 
> >> 
> >> 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. 
> > 
> > 
> > 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. 
>
> 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. 
>

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

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

>
> 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. 
>

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Release note auto-generation RFC

[Erik Bray]

On Fri, Jan 13, 2017 at 4:32 PM, Dima Pasechnik  wrote:
>
>
> On Friday, January 13, 2017 at 11:15:49 AM UTC, Erik Bray wrote:
>>
>> On Thu, Jan 12, 2017 at 9:48 PM, Kwankyu Lee  wrote:
>> >
>> >
>> > 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.
>>
>> 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.
>
>
> 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.

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.

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Release note auto-generation RFC

[Dima Pasechnik]

On Friday, January 13, 2017 at 11:15:49 AM UTC, Erik Bray wrote:
>
> On Thu, Jan 12, 2017 at 9:48 PM, Kwankyu Lee  > wrote: 
> > 
> > 
> > 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. 
>
> 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. 
>

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.

 

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

Re: [sage-devel] Re: Release note auto-generation RFC

[Erik Bray]

On Thu, Jan 12, 2017 at 9:48 PM, Kwankyu Lee  wrote:
>
>
> 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.

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.

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Release note auto-generation RFC

[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.

>

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Release note auto-generation RFC

[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.
 

>
>
>
>
> On Thursday, January 12, 2017 at 5:14:23 PM UTC+1, Dima Pasechnik wrote:
>>
>> 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
>>
>>
>>
>> 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
>>>
>>

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Release note auto-generation RFC

[Matthias Koeppe]

One could perhaps use metatickets on trac for that.

On Thursday, January 12, 2017 at 10:01:55 AM UTC-8, 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.
>
>>

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Release note auto-generation RFC

[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.




On Thursday, January 12, 2017 at 5:14:23 PM UTC+1, Dima Pasechnik wrote:
>
> 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
>
>
>
> 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
>>
>

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Release note auto-generation RFC

[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



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
>

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Release note auto-generation RFC

[Ralf Stephan]

On Thursday, January 12, 2017 at 1:48:28 PM UTC+1, Simon King wrote:
>
> On 2017-01-12, Volker Braun  wrote: 
> > Yes, to the Sage src tree. That is, we would add a newsfragments 
> directory 
> > somewhere under $SAGE_ROOT. 
>
> Seriously??? 
>

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.
 

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Release note auto-generation RFC

[Simon King]

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

Seriously???

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Release note auto-generation RFC

[Ralf Stephan]

If you want the name "Sage" (vs. "sage") it must be under src/Sage
like in https://trac.sagemath.org/ticket/22176

-- 
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Release note auto-generation RFC

[Volker Braun]

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


On Thursday, January 12, 2017 at 8:15:48 AM UTC+1, Simon King wrote:
>
> Hi Volker, 
>
> On 2017-01-11, 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... 
>
> To where? Certainly not to the Sage src tree. 
>
> Cheers, 
> 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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.

[sage-devel] Re: Release note auto-generation RFC

[Simon King]

Hi Volker,

On 2017-01-11, 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...

To where? Certainly not to the Sage src tree.

Cheers,
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+unsubscr...@googlegroups.com.
To post to this group, send email to sage-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/sage-devel.
For more options, visit https://groups.google.com/d/optout.