add changelog info section to PR template

[fbenke-pik]

Purpose of this PR

In order to generate a changelog for releases, we want to collect relevant info as part of the PRs. The PR template now has a section where devs can add a concise description of the changes in their PR to be included in the changelog of the next release. It is optional, as not all PRs contain relevant info for the changelog.

We will later use the info to create the changelog in a semi-automatic process using a script gathering the info from all PRs (text and link to PR).

Type of change

• New feature

Checklist:

• My code follows the coding etiquette
• I performed a self-review of my own code
• I explained my changes within the PR, particularly in hard-to-understand areas

[0UmfHxcvx5J7JoaOhFSs5mncnisTJJ6q]

👀

[orichters]

MAgPIE uses approach to have a changelog file that is manually filled.

Pros I can imagine:

• you always have an overview of what changed between the last release and now without running this script or digging through the PRs
• sometimes, changes are made over more than one PR, or a bugfix comes later. I think the result is less confusing if you can simply change the changelog to the current state, instead of somehow straighten it later
• I'm not sure how reliant such a script would be, given the PR mess. You might need to be very careful with writing the text such that the automated process works
• …

Cons I can imagine:

• merge conflicts on changelog
• maybe more difficult for new users to edit an additional file?
• …

[0UmfHxcvx5J7JoaOhFSs5mncnisTJJ6q]

Maybe first discuss what is supposed to end up in the change log, before deciding on how to create one?

[0UmfHxcvx5J7JoaOhFSs5mncnisTJJ6q]

Cons I can imagine:

• merge conflicts on changelog

That would require parallel changes to the changelog, i.e. two merge requests addressing some unversioned issue/bug, and altering the existing entry in the change log. I'll bring cake when that happens.

Also: https://keepachangelog.com/

[orichters]

That would require parallel changes to the changelog, i.e. two merge requests addressing some unversioned issue/bug, and altering the existing entry in the change log. I'll bring cake when that happens.

What does github if two PRs add a line at the same position (which is what I would expect an addition to a changelog to look like)? Shouldn't github raise a merge conflict then to find out which line should come first?

[0UmfHxcvx5J7JoaOhFSs5mncnisTJJ6q]

What does github if two PRs add a line at the same position (which is what I would expect an addition to a changelog to look like)? Shouldn't github raise a merge conflict then to find out which line should come first?

True, people will add their stuff all at the same position …

[orichters]

I'll bring cake when that happens.

Njam… 🍰

[0UmfHxcvx5J7JoaOhFSs5mncnisTJJ6q]

But I did work on a project (that thankfully is just finishing) using a changelog like that, and merge conflicts were never a problem. Either be smart about when to add to the change log (right before merging), or resolve the fairly simple conflicts.

[LaviniaBaumstark]

My most important arguments why we want to go for a partly automated process:
Users often will not adjust the change.log file in time because they forget it, they think, there will be further changes, they are busy, etc. At the same time I have the impression that developers are taking the PR templates very serious and I assume that adding there a sentence for the change.log if needed could work out. We can test it and if we will see that it is not working, we can adjust the process.
Regarding the option to always see the changes I would say that you can always run the script for getting the change.log (e.g. make changelog) if you need this info.

[0UmfHxcvx5J7JoaOhFSs5mncnisTJJ6q]

At the same time I have the impression that developers are taking the PR templates very serious

No they don't.

(Not pointing fingers, it's just the latest example.)

So, what is this request about? Is it whether everybody understands what is meant by

## Information for release changelog (optional):

(Leave empty if this PR does not concern changes to be mentioned in the changelog)

Bit trivial, no?

But there's no information on

• what is supposed to go into the change log, what isn't
• will the change log have specific sections (like "Additions", "Changes", "Fixes", …)
• is there a specific format required so support such sections

If the intention is to have people provide a one-liner to be copied into the change log, then why not simply add another checkbox "[ ] goes into the change log" and copy the request's title into the change log? I guess most people will copy the title there anyway.

[fbenke-pik]

Maybe first discuss what is supposed to end up in the change log, before deciding on how to create one?

In my opinion, a changelog should contain "notable changes" . I am not sure if this can be boiled down to a clear set of rules. I'd expect developers to use common sense when deciding if their changes should appear in a changelog.

So, what is this request about? Is it whether everybody understands what is meant by ..

The PR is about the whole process related to this adjustment of the template I described under "Purpose", not so much about the adjustment of the template itself

But there's no information on what is supposed to go into the change log, what isn't

See my first answer. I don't think it is necessary to have a concise definition, but would be interested in hearing yours.

But there's no information on will the change log have specific sections (like "Additions", "Changes", "Fixes", …)

If we go with this approach, there will be only a list of changes (so the one-liner under the newly introduced section) and a link to the merge PR. No sections. As RSE group, we think this is good enough for a start. But if the majority group prefers the MAgPIE approach with sections, then we can also set this up.

But there's no information on is there a specific format required so support such sections

..where devs can add a concise description of the changes, i.e. There is no specific format required for now. Just keep it short.

[fbenke-pik]

Closed in favour of #1363