[OSB] Streamline the approach to documenting changes between releases

[tsmbland]

You are currently using multiple approaches for documenting the changes between releases

• a CHANGELOG.md file
• release notes in the GitHub releases page
• you also have CHANGES.txt, which looks unused and outdated, and I assume can be deleted

There are several things to note:

Firstly, I would recommend, at the very least, linking the release notes from somewhere in the documentation to make them more easily accessible for users. Better yet, commit these notes to the repository as a markdown file, and have a dedicated release notes section in the documentation, which you will add to whenever a new release is made. Take a look at what we've done here, for example. Other tools like pandas do something similar.

Secondly, once the release notes are committed to the repository, I would caution against also having a changelog file. If you're documenting changes in multiple places, not only is this more work for you, but it can also potentially lead to inconsistencies and confusion with people not sure where they should be looking. If you think it's necessary to have both (e.g. with the changelog tailored for developers and the release notes tailored for users), then this could still work, but I would advise that the documentation shows the release notes, and not the changelog, as these are more tailored towards users.

In summary, if it was me, I would do the following:

• add the release notes to the repository as markdown files (one per release)
• create retrospective release notes for past releases, if you like
• include these in the documentation (see how we do this in MUSE
• remove the changelog

[tsmbland]

One approach I like is to have user-friendly release notes which are light on technical details, and add links to github issues and pull requests where technical details are discussed in more detail. This way, the release notes can be a useful resource for developers, without being confusing to users. See the pandas documentation, for example, and also the work I've done on MUSE.

If you want an easy way to add these links, take a look at this