Modify the way that we talk about changes to end-users

[Zeitsperre]

The way that we advertise our changes could use some streamlining; Our unwritten rules at this point have been:

• Every pull request should have an entry in the CHANGELOG.rst
• API changes (function replacements) should be listed within the entry.
• The summary of changes should point to the issue and pull request that identifies the issue and proposes the fix.
• The change categories we (tend to) use are:
  • "Announcements": Notices directly affecting end-users and their environments.
  • "New indicators": New algorithms/methods/indicators.
  • "New features and enhancements": Non-indicator features of interest.
  • "Breaking changes": API and convention changes, updates to libraries.
  • "Bug fixes": Fixes to unintended/undefined behaviours.
  • "Internal changes": Developer-facing changes, changes to the internal structure of modules/functions
  • "CI changes": continuous integration, tox-related changes, etc.

The current approach is quite verbose and end-users might be overwhelmed. This has lead to issues where new functionality is entirely missed by users.

A few ideas:

• Split internal developer/maintainer-intended changes into their own CHANGELOG
• Add a new "What's new" page to the documentation (NEWS.rst) that would allow us to go more into detail on how recent advancements can be effectively used.
• Create a simple blog + RSS feed and publish updates as needed (can also leverage existing Mastodon/Fediverse account).

[huard]

What about a "Highlights" section in the changelog ?

[Zeitsperre]

What about a "Highlights" section in the changelog ?

That's also an option, for sure. There is value in a comprehensive CHANGELOG being visible in the Releases page on GH, but I wouldn't want a Highlights section there, given that that metadata is pushed to places like Zenodo. Not sure how best to present that info.