Bug 22890

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.

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.

(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

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.

This has an interesting aspect - do we want to provide this for librarians, or for end developers? (new feature vs. renamed method)

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.

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

(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

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

(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 ?

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

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.

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.

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

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?

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

(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

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

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.

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.

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

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

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

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>

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.

(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

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

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?

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

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

I wonder about a keyword to denote 'technical' vs 'end user' release notes inclusion..

This got very much sidetracked by the debate around the audience the log is intended for.. I really just wanted to see a simple feature log available from the UI in the about page somewhere and I believe this old patch achieved most of that.

Whilst I agree it would be great to have a dev focused set of notes too some time.. I'm removing myself as assignee as I don't have time to follow-up here.