On Fri, Jan 13, 2017 at 4:32 PM, Dima Pasechnik <dimp...@gmail.com> 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 <ekwa...@gmail.com> 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.
