Docs: Add guidance for CHANGELOG entries

[hoffie]

What is the current behaviour and why should it be changed?

We currently don't have clear guidance when to add changelog entries.

Describe possible approaches

• What's the goal for the CHANGELOG, who is the audience?
• Should internal changes (i.e. those which do not directly affect generated artifacts) be documented in the CHANGELOG? Options:
  1. Document all PRs.
  2. Document PRs which may be user-visible (i.e. including third-party library bumps, build logic changes)
  3. Document PRs which intended user-visible changes only (bug fixes, new features, performance changes).
• How should entries be written? (past tense)
• How are related PRs handled?
• Where should this guidance be stored? PR template?

Has this feature been discussed and generally agreed?

One of the previous discussions around this topic: #2778 (comment)

[hoffie]

On a related note: If we want to be very consistent about which PRs to list, we should be even more consistent about using PRs in almost all cases. We've had several changes to .github/* as direct commits to master instead of PRs. I think it's even more common on the website repo.

My personal stance is:

• For the CHANGELOG I'm leaning towards option (2).
• Always use PRs except for documented exceptions (= release process). PRs provide the necessary transparency. If something is urgent, we can always do an admin-merge, but at least it would cause proper notifications to everyone who is subscribed.

[pljones]

Agreed on "when" PRs: always except for the documented exceptions (release process).

I tend towards erring on the side of documenting all PRs, again with documented exceptions. However, I'm not able to come up with any such exceptions off the top of my head. I'd prefer to have the slog at release of grouping a bunch of related PRs, so guidance should be that related PRs have clearly related CHANGELOG entries (e.g. all mentioning the same issue).

For example, I think it's perfectly reasonable to include updating the version of aqt in our CHANGELOG.

[ann0see]

Current state:

The statement by corrados was

Each new feature or bug fix must be documented in the ChangeLog. If a new contributor/translator adds code to the Jamulus project, he/she should be added to the contributor/translator list in the About dialog of the Jamulus software.

#915 (comment)

@gilgongo also added some things about the website, I think?

[ann0see]

What's the goal for the CHANGELOG, who is the audience?

I can think of two goals:

1. Tell the average user about new features and explain their relevance. For further information link documentation for further information
2. Tell the average or tech savvy user about the state change of the whole Project

I think we need a visible difference between the commit history and the ChangeLog, so:

• The changelog should link all (potentially) user relevant PRs: New features, Build environment changes, any script someone could use
• We should not write the commit message in the ChangeLog since that doesn't add anything
• Internal stuff isn't that end-user relevant (introduction of auto dependency updates for example) and can be condensed into one sentence: CI: Introduced automated dependency updating via Dependabot and custom scripts (#PR1, #PR2,...)

How are related PRs handled?

Condense as many as possible into bigger projects?

Where should this guidance be stored? PR template?

CONTRIBUTING.md in long and PR template short.
I think I'm standing somewhere between 2 and 3.

How should entries be written? (past tense)

Short to medium sized sentence in past tense describing visible impact? So e.g. my O(n²) --> O(n) PR would be technical in the Commit history, but a just a "Performance enhancement" in the changelog.

Maybe https://keepachangelog.com/en/1.0.0/ can give us a hint (although it's very short and not our format)

[pljones]

(although it's very short and not our format)

We have long change intervals, though - that, in itself, is an anti-pattern...

[pljones]

And as nothing seems to be happening here for 3.9.1 (bug fix release), moving to 3.10.0.

[pljones]

Removing from 3.10.0 and moving to Triage as no progress is being made.