Add a chronological changelog
Julian Maurice
Public
Seen by 15
We have the history page and a contributors list, but we don't have a
nice chronological changelog featuring bugs/enhancements and their
release dates.
The release notes are nicely polished now, but it would be great to
have to record available within Koha itself to encourage librarians to
read it and adopt new features.
We can adopt allot of the tooling that's already there to produce the
release notes to allow simple maintenance of such a page.
-- https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=22890
This dicussion is to gather opinions on this changelog : what should be in it, what should not, which format, how it is maintained, ...
Poll Created Tue 24 Mar 2020 8:07AM
How CHANGELOG should be populated Closed Sun 31 May 2020 7:00AM
Options
Add changelog.d/bug-XXXXX.md
Every set of patches should include a markdown file in a changelog.d directory (can be another name) containing the text that should go into the main CHANGELOG.md.
When patches get pushed into master, RM should copy the contents of that file into CHANGELOG.md and remove the file
Modify CHANGELOG.md
Every set of patches should include a modification to CHANGELOG.md
Bugzilla field "Text to go in release notes" (continuous update)
Every bug should have the field "Text to go in release notes" filled
When patches get pushed into master, RM should copy the contents of that field into CHANGELOG.md
Bugzilla field "Text to go in release notes" (update at release)
Every bug should have the field "Text to go in release notes" filled
Just before release, RM should copy the contents of that field for all bugs pushed into CHANGELOG.md
Results
| Results | Option | Rank | % of points | Points | Mean |
|---|---|---|---|---|---|
| Add changelog.d/bug-XXXXX.md | 1 | 0% | 0 | 0 | |
| Modify CHANGELOG.md | 2 | 0% | 0 | 0 | |
| Bugzilla field "Text to go in release notes" (continuous update) | 3 | 0% | 0 | 0 | |
| Bugzilla field "Text to go in release notes" (update at release) | 4 | 0% | 0 | 0 | |
| Undecided | 0% | 0 | 0 |
0 of 0 people have participated (0%)
Julian Maurice Mon 1 Jun 2020 1:11PM
Thanks for the feedback Martin. I will close the discussion since it didn't get as much attention as I hoped, and it seems that the vote interface is a bit too complicated anyway. If you want to reopen the discussion somewhere else, please do :)
David Cook Mon 1 Jun 2020 11:12PM
I think having an "end user summary" and "technical highlights" is a great idea, since technical notes are often useless for end users.
But I don't know that raising the bar to entry for code contributions by requiring a Markdown file is a good idea though. It also seems very unconventional. I've never encountered that kind of thing in any open source system I've worked on.
The other advantage of using Bugzilla is that the author doesn't have to be the one who necessarily writes the "end user summary" or "technical highlights". I figure anyone on the release team can write the notes and if they don't know what to write, then they can block until the author writes something?
Martin · Mon 1 Jun 2020 12:51PM
I'm open to having a structure similar to the atomic updates... ie. the changelog.d approach above.. it might encourage more developers to actually describe their changesets clearly when they write them.
The reason I liked the Bugzilla approach is that it's easier to update and correct the notes later in the release process... but if we're consistently requiring good notes as part of changesets prior to push then I can see the first approach working.
I do think developers and end users are looking for different things in release notes/changelogs. I was pondering having three fields in Bugzilla.. One for 'end user summary', 'technical highlights' and finally a "skip for note" flag. Then you could use the combination of those to fill out the release notes at release time. Sometimes when a big change is split into a number of smaller bugs you really only want the collector bug mentioned in the notes.. sometimes a patchset warrants some words for end users and not developers, other times highlighting a change to developers is important and sometimes you want to highlight different things for the same bug depending on your audience. I'd love to be able to get that functionality out of any system we choose to adopt.