Bug 22890 - Add a chronological changelog
Summary: Add a chronological changelog
Status: Failed QA
Alias: None
Product: Koha
Classification: Unclassified
Component: About (show other bugs)
Version: Main
Hardware: All All
: P5 - low enhancement (vote)
Assignee: Martin Renvoize
QA Contact: Testopia
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2019-05-11 08:57 UTC by Martin Renvoize
Modified: 2022-05-10 15:31 UTC (History)
8 users (show)

See Also:
Change sponsored?: ---
Patch complexity: ---
Documentation contact:
Documentation submission:
Text to go in the release notes:
Version(s) released in:


Attachments
Bug 22890: Add CHANGELOG.md and display it in About page (845.49 KB, patch)
2020-03-22 18:01 UTC, Julian Maurice
Details | Diff | Splinter Review
Bug 22890: Add CHANGELOG.md and display it in About page (845.21 KB, patch)
2020-04-26 20:50 UTC, Victor Grousset/tuxayo
Details | Diff | Splinter Review
Bug 22890: Add CHANGELOG.md and display it in About page (845.27 KB, patch)
2020-04-26 20:53 UTC, Victor Grousset/tuxayo
Details | Diff | Splinter Review

Note You need to log in before you can comment on or make changes to this bug.
Description Martin Renvoize 2019-05-11 08:57:22 UTC
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.
Comment 1 Julian Maurice 2019-05-15 08:53:04 UTC
Maybe a bit out of scope, but I would like to suggest reading https://keepachangelog.com/en/1.0.0/

Keeping a changelog file updated in the sources (and requiring new patches to include a changelog entry) might be easier than updating and fetching all "Text to go in the release notes" bugzilla fields at release time. It will also be easier for those that use the master branch to know what was introduced recently.

Then displaying this file in Koha should be as easy as a "markdown2html" call.
Comment 2 Katrin Fischer 2019-05-15 09:04:43 UTC
I think keeping a manually edited text file would kind of contradict our use of bugzilla/git for generating the release notes :)

I think if we do that, it needs to be fully automated. Having access to the release notes from wihin Koha might be a good start. Right now it's on the web and included in the release, but not accessible for librarians.
Comment 3 Julian Maurice 2019-05-15 09:52:30 UTC
(In reply to Katrin Fischer from comment #2)
> I think keeping a manually edited text file would kind of contradict our use
> of bugzilla/git for generating the release notes :)

I agree. That's why I said it is maybe out of the scope of this bug ;)
I'm just mentioning that in case the people willing to work on this bug are not aware of this "convention", as it might have an influence on how they will do it.

I think it has several advantages over the current method and, as a developer, I *really* appreciate when a project has an up-to-date changelog at the root of the source repository.
Note that I am aware of misc/release_notes, but they are not up-to-date when using master, sometimes full of stuff that I don't care about (use Modern::Perl) and the important stuff is not emphasized enough (method removed/renamed)

Again, I only suggested to read the page keepachangelog.com, not to follow exactly what it's saying
Comment 4 Martin Renvoize 2019-05-16 09:36:07 UTC
Funny you should mention keepachangelog, I was hoping to follow such a format/convention, but try to populate it using bugzilla fed data.

I (and Jonathan D) am slowly working through adding more tooling to the release procedures to help us better track changes (starting with the contributors list, history and teams data). I'd envisage this being part of that work and it being partly the RM's responsibility to add such classifications etc to bugzilla should we need to for a decent changelog.
Comment 5 Katrin Fischer 2019-05-16 19:34:12 UTC
This has an interesting aspect - do we want to provide this for librarians, or for end developers? (new feature vs. renamed method)
Comment 6 Jonathan Druart 2019-11-28 15:34:15 UTC
I like the "tags" on https://keepachangelog.com/en/1.0.0/, like "Added", "Deprecated", etc.

It would be great to have some like "new modules", "new method", "new api route", "deprecated", "new/rm/mv sysprefs", "new table/column", etc.

So a single entry "feature foo" could have several tags.

We could have that at the end of the "Text to go in the release notes", like:

"""
This is a release note for feature foo that bring useful stuffs.
%%%%%%%%%%%%%% # a separator line
[Add pref]YetAnotherPref
[Add DB table]a_new_db_table
"""

The changelog could then be built using that and make the DB changes (or any other type of changes) eyeballed easily.
Comment 7 Julian Maurice 2020-02-05 16:53:22 UTC
(In reply to Jonathan Druart from comment #6)
> I like the "tags" on https://keepachangelog.com/en/1.0.0/, like "Added",
> "Deprecated", etc.
> 
> It would be great to have some like "new modules", "new method", "new api
> route", "deprecated", "new/rm/mv sysprefs", "new table/column", etc.
> 
> So a single entry "feature foo" could have several tags.
> 
> We could have that at the end of the "Text to go in the release notes", like:
> 
> """
> This is a release note for feature foo that bring useful stuffs.
> %%%%%%%%%%%%%% # a separator line
> [Add pref]YetAnotherPref
> [Add DB table]a_new_db_table
> """
> 
> The changelog could then be built using that and make the DB changes (or any
> other type of changes) eyeballed easily.

Why not add this directly in the patch ?
Following the keepachangelog convention we could have:

ChangeLog.md

  ### Added
  - This is a release note for feature foo that bring useful stuffs.

  ### Sysprefs
  - Add new syspref YetAnotherPref

  ### Technical/Dev
  - Add new database table a_new_db_table


I see several benefits over using the bugzilla field:
- Documentation of the change is close to the code. It can be part of the QA process to review that doc.
- No additional tooling needed. We can even remove some tools because we won't need to generate release notes at release time.
- Having to write in a specific format ([tag]description) that would be parsed by a script is error-prone and errors would be discovered only at release time.
- ChangeLog is always up to date in master, making it easy to see what changed since the latest stable version.
- It would be easy to see what changed between 2 commits, which can be really helpful when rebasing patches.

The downside is that it will cause git conflicts, so we should probably have to do something similar to updatedatabase (atomicupdate)

We can also consider having a DeveloperChangeLog.md to avoid polluting the main changelog too much with technical details.
Comment 8 Jonathan Druart 2020-02-06 10:42:32 UTC
(In reply to Julian Maurice from comment #7)
> The downside is that it will cause git conflicts, so we should probably have
> to do something similar to updatedatabase (atomicupdate)
> 
> We can also consider having a DeveloperChangeLog.md to avoid polluting the
> main changelog too much with technical details.

Developers can add their own ChangeLog entries in the commit message or the "Text to go in the release notes", then the RM move it to ChangeLog.md
Comment 9 Jonathan Druart 2020-02-06 11:22:17 UTC
Should we have:

* dev (.06, .12) versions in unreleased?

* 1 entry per "version" (ie. our DB versioning), or per important bug report, per action (Add/Remove/Move), or even per "entity" (pref, db, new feature) ?

* Some possible examples:

Example 1:
#Changelog
## [19.12.00.002] - 2019-12-16
### Added
- pref NewPref added by bug 12345
### Removed
- DB column removed by bug 23456

## [19.12.00.001] - 2019-12-09
### Removed
- Pref removed by bug 11233

## [19.11.00.000] - 2019-11-27


Example 2:
#Changelog
## [Unreleased]
### Added
- pref NewPref added by bug 12345
### Removed
- DB column removed by bug 23456
- Pref removed by bug 11233

## [19.12.00] - 2019-11-27


Example 3:
#Changelog
## [Unreleased]
### Bug 12345 [- with push date?]
- This does something great
- Added NewPref
### Bug 23456
- Removed DB column
### Bug 11233
- Removed Pref

## [19.12.00] - 2019-11-27

Example 4:
#Changelog
## [Unreleased]
### Prefs
- Added NewPref by bug 12345
- Removed Pref by bug 11233

### DB structure
- Removed DB column by bug 23456

## [19.12.00] - 2019-11-27
Comment 10 Julian Maurice 2020-02-06 11:35:12 UTC
(In reply to Jonathan Druart from comment #8) 
> Developers can add their own ChangeLog entries in the commit message
> or the "Text to go in the release notes", then the RM move it to ChangeLog.md

In my opinion, commit messages and changelogs have different goals.
Commit messages should contain a detailed description of a change, especially what cannot be found in the diff (things like why it is needed, why it has been implemented that way, alternatives that have been considered, benchmarks, ...).
Changelogs should contain a summary of what changed.

"Text to go in the release notes" is fine I guess, and not really different from what I had in mind (a .md file per bug in changelog.d/)

What is the most convenient for the release team ?
Comment 11 Julian Maurice 2020-02-06 11:53:08 UTC
(In reply to Jonathan Druart from comment #9)
> * Some possible examples:

I'd eliminate example 1 because DB versions are not released versions.
I'd also eliminate example 3 because as a changelog reader I'm more interested in "categories of changes" (security fixes, new features, breaking change, ...) than in "what this particular bug changed"

Examples 2 and 4 are very similar and only differ in the list of categories. I'd go with something like this:

### Added (new features)
### Changed (enhancements)
### Fixed (bugfixes)
### Security (security fixes)
### Sysprefs (new, renamed, deleted sysprefs)
### Dependencies (new, updated, deleted Perl dependencies)
### REST API (new, renamed, deleted API routes and parameters)
### Database structure (new, renamed, deleted tables and columns)
### Perl API (new, renamed, deleted Perl modules and subroutines)
Comment 12 Martin Renvoize 2020-02-07 09:03:21 UTC
I still think maintaining this inside Bugzilla and pulling it into a changelog.md file for each release is the way to go... I'd maintain it in a file with every commit/patchset if we were only supporting one definitive version/branch of Koha but as we're continually supporting at least 3 versions in parallel I think ensuring it's properly chronological would be difficult in commits.. 

An example would be with almost any bug.. it's is the rmaints decision whether the bug is a required backport and as such the RM doesn't know at the time of his/her push what version this bug is going to appear in.. as such they would put it under their version, and when the rmaints backported the rm would then need to forward port a second patch to get move the change down the changelog to get the chronology right again.

By maintaining this in bugzilla we already have scripts to add koha version into the relevant fields at the time of push and also have tools that pull out the release notes fields for release note built at release.. so we could have a clear way of getting the chronology correct at release time.

As for the format, the keepachangelog seems great to me.. I wouldn't be against having two distinct fields in bugzilla.. one for librarian facing release notes and one for developer-facing notes as they're often rather different use cases.
Comment 13 Martin Renvoize 2020-02-07 09:05:27 UTC
In fact, I'd go so far as to say it might be nice to filter out a fair bit of the existing data that goes into the release notes.. I don't think librarian end users actually need/want to see a record of every single 'bug' that's made it into a release.. especially at the moment whilst there's lots of architectural bugs going in that don't really affect end users.

By having the two distinct fields we could more easily direct the information to the right people.
Comment 14 Julian Maurice 2020-02-07 09:41:27 UTC
(In reply to Martin Renvoize from comment #12)
> I still think maintaining this inside Bugzilla and pulling it into a
> changelog.md file for each release is the way to go... I'd maintain it in a
> file with every commit/patchset if we were only supporting one definitive
> version/branch of Koha but as we're continually supporting at least 3
> versions in parallel I think ensuring it's properly chronological would be
> difficult in commits.. 
> 
> An example would be with almost any bug.. it's is the rmaints decision
> whether the bug is a required backport and as such the RM doesn't know at
> the time of his/her push what version this bug is going to appear in.. as
> such they would put it under their version, and when the rmaints backported
> the rm would then need to forward port a second patch to get move the change
> down the changelog to get the chronology right again.

I don't think the forward port would be needed. Each stable branch would have its own changelog.
For instance, if you are on 19.11.x Changelog would contain:

# Unreleased

- bugfix X
- ...

# 19.11.01

- bugfix Y
- ...

#19.11.00

<release notes of major version>

And on master you would have

# Unreleased

- bugfix X
- bugfix Y
- ...

# 19.11.00

<release notes of major version>


I think it would be confusing to have bugfixes referenced twice or more in the same file (once for master, once for stable, once for oldstable, ...). Stable branches live their own life and I think it's ok if only them contain the changes for minor releases.
Comment 15 Martin Renvoize 2020-02-07 09:50:28 UTC
I don't think I explained myself well.. you've actually basically highlighted my point. I don't want bugs to appear twice at all.. I'd want them to appear once and only once and at the earliest point that they were added to the codebase.

I'm thinking of upgrades from one mid-point release.. say a 17.05.04 to another mid-point release in the next major version, say 18.11.08.  The Changelog should simply list all changes between those two versions in order and you shouldn't have to refer to different files from the different branches.

Does that make more sense?
Comment 16 Julian Maurice 2020-02-07 10:08:14 UTC
(In reply to Martin Renvoize from comment #15)
> Does that make more sense?

Yep. After re-reading your original comment I see what I misunderstood. Sorry :)

But still... there is no "earliest point" for a particular bug. We have several different timelines.

Let's take an example:

- I install Koha 19.11.00 on release day
- I wait a few months, in the meantime bugfixes are backported to 19.11.x, some of which are also backported to 19.05.x.
- On the next 19.11.x release, changelog entries for bugs that have been pushed to 19.05.x are moved down to the corresponding 19.05.x release.
- Now I want to update and see what changed between 19.11.00 and 19.11.06. Problem: the changelog will not be complete because some entries are under 19.05.x section instead.
Comment 17 Julian Maurice 2020-02-07 10:17:35 UTC
(In reply to Martin Renvoize from comment #13)
> In fact, I'd go so far as to say it might be nice to filter out a fair bit
> of the existing data that goes into the release notes.. I don't think
> librarian end users actually need/want to see a record of every single 'bug'
> that's made it into a release.. especially at the moment whilst there's lots
> of architectural bugs going in that don't really affect end users.

I did not answer to that, but I totally agree with you.
I'm not sure if we should have several changelog/release notes for specific audience, but each different kind of users (end-users, sysadmins, developers, ...) should be able to find useful infos quickly
Comment 18 Julian Maurice 2020-03-22 18:01:49 UTC
Created attachment 101388 [details] [review]
Bug 22890: Add CHANGELOG.md and display it in About page

CHANGELOG.md was generated by the following command:

ls misc/release_notes/*.md \
    | sort --reverse -V \
    | xargs cat \
    | sed -e 's/^#/##/' -e '1 i\# Changelog\n' > CHANGELOG.md

Releases notes before 16.05 were not generated in markdown, so they are
not included in CHANGELOG.md

Markdown to HTML conversion is done in the browser, using Showdown
(http://showdownjs.com/)

I also tested Text::Markdown from CPAN
(https://metacpan.org/pod/Text::Markdown) but it was very slow.
Text::Markdown from https://daringfireball.net/projects/markdown/ was
faster but cannot be found on CPAN.
I also considered pandoc but it was a bit slow too and required
more additional dependencies.

Converting in the browser is slow too but has the benefit of allowing
the reader to have access to the raw changelog before it is correctly
rendered (so they can start reading it)
On the other side, converting on the server side we would be able to
put the resulting html in cache.
Suggestions welcome :)
Comment 19 Jonathan Druart 2020-03-23 10:07:58 UTC
Hello Julian,

I do not understand, I though we wanted something different from the release notes and more dev oriented, "what was pushed in the last weeks?". Where are the deprecated, new sysprefs, etc. we talked about earlier?

I do not see the difference with https://gitlab.com/koha-community/koha-release-notes.
Comment 20 Julian Maurice 2020-03-23 10:22:00 UTC
Hi,

Sorry for not making it clear: the patch is only a first step of displaying a CHANGELOG.md in Koha about page and I took the contents of release notes only as an example. What we want to put in CHANGELOG.md is still to be discussed.
Comment 21 Julian Maurice 2020-03-23 12:00:06 UTC
I created a new discussion on https://framavox.org/d/UkADlcT6/add-a-chronological-changelog to gather opinions. Feel free to add new polls, or new options to existing polls
Comment 22 Victor Grousset/tuxayo 2020-04-26 20:49:52 UTC
Patch doesn't apply.

<<<<<<< HEAD
use File::Slurp;
use List::MoreUtils qw/ any /;
||||||| constructed merge base
use List::MoreUtils qw/ any /;
=======
use List::MoreUtils qw/ any firstval /;
>>>>>>> Bug 22890: Add CHANGELOG.md and display it in About page


What the 3 parts conflict shows is that:
- File::Slurp was added in master. (compare )
- this bug add firstval from List::MoreUtils

So it's easy to solve. Just keep Slurp and long version of List::MoreUtils
Comment 23 Victor Grousset/tuxayo 2020-04-26 20:50:19 UTC
Created attachment 103723 [details] [review]
Bug 22890: Add CHANGELOG.md and display it in About page

CHANGELOG.md was generated by the following command:

ls misc/release_notes/*.md \
    | sort --reverse -V \
    | xargs cat \
    | sed -e 's/^#/##/' -e '1 i\# Changelog\n' > CHANGELOG.md

Releases notes before 16.05 were not generated in markdown, so they are
not included in CHANGELOG.md

Markdown to HTML conversion is done in the browser, using Showdown
(http://showdownjs.com/)

I also tested Text::Markdown from CPAN
(https://metacpan.org/pod/Text::Markdown) but it was very slow.
Text::Markdown from https://daringfireball.net/projects/markdown/ was
faster but cannot be found on CPAN.
I also considered pandoc but it was a bit slow too and required
more additional dependencies.

Converting in the browser is slow too but has the benefit of allowing
the reader to have access to the raw changelog before it is correctly
rendered (so they can start reading it)
On the other side, converting on the server side we would be able to
put the resulting html in cache.
Suggestions welcome :)
Comment 24 Victor Grousset/tuxayo 2020-04-26 20:53:30 UTC
Created attachment 103724 [details] [review]
Bug 22890: Add CHANGELOG.md and display it in About page

CHANGELOG.md was generated by the following command:

ls misc/release_notes/*.md \
    | sort --reverse -V \
    | xargs cat \
    | sed -e 's/^#/##/' -e '1 i\# Changelog\n' > CHANGELOG.md

Releases notes before 16.05 were not generated in markdown, so they are
not included in CHANGELOG.md

Markdown to HTML conversion is done in the browser, using Showdown
(http://showdownjs.com/)

I also tested Text::Markdown from CPAN
(https://metacpan.org/pod/Text::Markdown) but it was very slow.
Text::Markdown from https://daringfireball.net/projects/markdown/ was
faster but cannot be found on CPAN.
I also considered pandoc but it was a bit slow too and required
more additional dependencies.

Converting in the browser is slow too but has the benefit of allowing
the reader to have access to the raw changelog before it is correctly
rendered (so they can start reading it)
On the other side, converting on the server side we would be able to
put the resulting html in cache.
Suggestions welcome :)

Signed-off-by: Victor Grousset/tuxayo <victor@tuxayo.net>
Comment 25 Martin Renvoize 2020-06-01 12:40:01 UTC
Sorry.. this one slipped out of 20.05.. one project too many for me to multi-task on.

I'm still keen to work on this area and intend to get back to it this cycle... I have a bit of catching up on the conversation to do.
Comment 26 David Cook 2020-06-02 00:09:03 UTC
(In reply to Martin Renvoize from comment #13)
> In fact, I'd go so far as to say it might be nice to filter out a fair bit
> of the existing data that goes into the release notes.. I don't think
> librarian end users actually need/want to see a record of every single 'bug'
> that's made it into a release.. especially at the moment whilst there's lots
> of architectural bugs going in that don't really affect end users.
> 
> By having the two distinct fields we could more easily direct the
> information to the right people.

+1000000
Comment 27 David Cook 2020-06-02 00:16:13 UTC
(In reply to Martin Renvoize from comment #13)
> In fact, I'd go so far as to say it might be nice to filter out a fair bit
> of the existing data that goes into the release notes.. I don't think
> librarian end users actually need/want to see a record of every single 'bug'
> that's made it into a release.. especially at the moment whilst there's lots
> of architectural bugs going in that don't really affect end users.
> 
> By having the two distinct fields we could more easily direct the
> information to the right people.

I have librarians ask me what's new in a release, and at the moment I painstakingly read through the release notes to create a condensed user-friendly version that might actually be meaningful to them. 

The technical release notes are useful for developers for sure. I always learn something new when I read them, as it's very challenging to stay 100% current on every patch that gets pushed to every release.
Comment 28 Katrin Fischer 2020-07-05 11:09:16 UTC
It appears to work mostly ok, but there are some glitches:

- Formatting (indentation!) appears a little off. 
- We also need to make sure that HTML tags in the bug descriptions don't get parsed (see bug 23915 at the bottom of 20.05 change log)

But from the comments I am not sure if this is really ready for the QA step yet?
How to make sure this is updated with the releases?
Comment 29 Jonathan Druart 2020-11-11 08:57:49 UTC
(In reply to David Cook from comment #27)
> (In reply to Martin Renvoize from comment #13)
> > In fact, I'd go so far as to say it might be nice to filter out a fair bit
> > of the existing data that goes into the release notes.. I don't think
> > librarian end users actually need/want to see a record of every single 'bug'
> > that's made it into a release.. especially at the moment whilst there's lots
> > of architectural bugs going in that don't really affect end users.
> > 
> > By having the two distinct fields we could more easily direct the
> > information to the right people.
> 
> I have librarians ask me what's new in a release, and at the moment I
> painstakingly read through the release notes to create a condensed
> user-friendly version that might actually be meaningful to them. 

A bit of topic here, but:
What about yet another bz field to "highlight" enhancements (or even bugfixes) that are more important than others? We could then put them in bold? (could be a try for 20.11 if you think it may be useful).
Comment 30 Katrin Fischer 2020-11-11 21:29:24 UTC
 
> A bit of topic here, but:
> What about yet another bz field to "highlight" enhancements (or even
> bugfixes) that are more important than others? We could then put them in
> bold? (could be a try for 20.11 if you think it may be useful).

I think we can already use markdown(?) syntax for formatting. maybe a keyword would be enough?
Comment 31 Martin Renvoize 2020-11-17 09:41:38 UTC
I wonder about a keyword to denote 'technical' vs 'end user' release notes inclusion..