Release notes

[jholveck]

This is not intended to be merged as a Markdown file. It's just in that form for easier review and discussion for now. Once we've got the content settled, we can reformat this into reStructuredText for the docs.

Based on #471.

Closes #471.

[BoboTiG]

I do not see what can be changed to make it better.

[BoboTiG]

It's now possible to include markdown files in the documentation, that will lower our work with such a PR.
Example: https://github.com/BoboTiG/python-mss/blob/main/docs/source/changelog.rst (and we now have the full project history in the docs: https://python-mss.readthedocs.io/latest/changelog.html)

---

Now, I am not sure how to present this file in the documentation, where to put it, under what name? Maybe do you have a clearer idea than me?

At the beginning I wanted to add it under "History" with the title "Next". But maybe this file should be kept for a while (even maybe forever) so it should have its own section 🤔

[jholveck]

Hmm, that's an interesting question. I mean, it's nominally the release notes for 10.2.0, but it's mostly deprecations in anticipation of 11.0.

Most projects seem to put their release notes like this in the docs, and include deprecations there. Examples:

• https://pillow.readthedocs.io/en/stable/releasenotes/12.1.0.html
• https://numpy.org/doc/stable/release/2.4.0-notes.html

[BoboTiG]

It means the new changelog page should better be a list of links to specific version pages (like done for Numpy and Pillow).

I'll see how it can be automated.

[jholveck]

Have you thought about how you want to handle the new changelog page? Do you need me to investigate that?

[BoboTiG]

Actually, we could simply include a "release-notes.md" above the changelog and it would be good.

Since we'll publish versioned documentation, then this new page will always be aligned with the selected version.

[BoboTiG]

I think a last step would be to include this in the documentation, right above the "changelog" in the index.

[jholveck]

Documentation Version Proposal

Here’s my thoughts about a way we could do release notes / history. Halldor and I have talked about this, and also discussed it with some colleagues. Everybody has different opinions, although this seems to be a kind of middle ground. The choice is yours, of course; it was your vision that got MSS to where it is today.

This is just a proposal, meant as a starting point for discussion. Anything I suggest here is up for debate.

Most of this is inspired by the philosophy at https://keepachangelog.com/en/1.1.0/ , but has a few differences. That website emphasizes the need to document each release’s noteworthy changes as a human-friendly, coherent, description, not a list of commits. That’s also what I’m emphasizing here. The main difference is that I’m proposing keeping these documents as an organized part of the Sphinx docs, rather than as a single top-level file.

User Presentation

What does the user see?

I’ve included comparisons to a few other Python projects.

Version selector

Each minor release has an entry in the readthedocs.io version dropdown, corresponding to the last patch release of that minor. I don’t think there’s a point in cluttering the dropdown with patch releases, since those don’t have API changes.

Others I spoke with suggested only putting one element for each major release. That would also work, but it’s still significant for users to know what minor release added a feature, so they can use that as a minimum.

• Python: Uses per-minor-release dropdown.
• NumPy: Uses per-minor-release dropdown.
• Pillow: Only has “stable” and “latest”. History is only available in the “Release Notes” and “Deprecations and Removals” docs chapters.
• Requests: Only has “stable” and “latest”. History is only available in the “Release History” chapter.

Inline “changed in” notes

Docstrings use the Sphinx version-added, version-changed, and version-deprecated directives. This lets users quickly note version-specific differences without needing to switch versions in the dropdown.

In some cases, version-removed may be used (such as for some removed kwargs), but in general, removed features aren’t listed in future versions of the documentation. They are, of course, still visible in old versions of the docs, accessible in the version dropdown.

• Python: Included for some features. Not mentioned by the style guide, but is encouraged in the Python project ReST reference
• NumPy: Included for some features. Examples: broadcast_shapes, some flags on unique. Inline prose in some cases.
• Pillow: Included for many features.
• Requests: Seems to be absent.

Release history

There is a dedicated “Release History” section of the docs. This is separated into one HTML page per release, as well as a “Versioning” page at the top with the versioning policy.

Importantly, this is for end users! The changes should be in a format that an end user can quickly read, and get all the information they need to decide if they need to upgrade, if they need to change their code, if there are new features to take advantage of, and so forth.

For minor or major releases, there should be a human-friendly description of the changes. These are divided into categories:

• Added for new features.
• Changed for changes in existing functionality.
• Deprecated for soon-to-be removed features.
• Removed for now removed features.
• Fixed for any bug fixes.
• Security in case of vulnerabilities.

For patch releases, it’s sufficient to have just a short list of changes, similar to the way that CHANGELOG.md has historically been presented.

References to GitHub Pull Requests or Issues are rendered as HTML links; we may add a custom Sphinx Role for this. (Roles can also be used with MyST.)

A list of contributors is included for each release.

It’s not necessary to retroactively change previous releases; those can be just used as they currently exist in CHANGELOG.md.

• Python: Has very long What’s New documents for each minor version, since these usually incorporates a lot of changes. Also has a specific changelog for each prerelease and patch release. This is much more extensive than MSS needs.
• NumPy: Release notes have prose descriptions for each major or minor release. All releases (major, minor, or patch) have lists of contributors, and a list of PRs merged. This is probably the closest to the model that I’m proposing.
• Pillow: Release notes include prose descriptions of changes, although in a more list-like form than NumPy. PRs are not listed.
• Requests: Release notes have a list-like form of changes. But it’s not really very useful. That said, they are grouped similarly to the description above.

Developer view

What do developers do?

File structure

Since Sphinx makes one HTML page per source file, and we want each version to be on its own HTML page, each version needs its own source file (be it Markdown or reStructured Text).

Within docs/source/release-history, we have one file for each release: v10.1.0.md (or .rst), v10.0.0.md, v9.0.2.md, etc.

There is also a file unreleased.md. This is a file holding the release notes for the upcoming version. At the time that its version number has been decided on, or even at the time of release, this is renamed: v10.2.0.md. After each release, a new unreleased.md file is started.

Contents of unreleased.md

At the beginning of a new release cycle, when we’re not yet sure what the new release will contain, this can just be a list of changes, like in today’s CHANGELOG.md.

However, as the nature of the upcoming release starts to become more clear, this should be changed to be a more prose style, similar to the release notes that are in this PR.

In other words, early in the release cycle, this should be put into the form described in the “Release history” section above. That allows us to be editing the release notes as we make changes, instead of trying to write release notes just before release, after we’ve forgotten parts of the context and such.

CHANGELOG.md and CHANGES.md

I see no need to retain either of these.

User-visible changes, which are the purpose of CHANGELOG.md, will be met by the release history files as described above.

Internal / technical changes, which are the purpose of CHANGES.md, are visible elsewhere: PRs, commit logs, etc. In the time I’ve been part of the MSS project, we haven’t really kept CHANGES.md up to date. I don’t see that it’s helpful, and suggest that we just eliminate it.

If we prefer, we could keep unreleased changes in CHANGELOG.md (or maybe UPCOMING.md or something) at the top of the git tree, instead of in docs/source/release-history/unreleased.md. That might be more a more visible reminder for us to keep it up-to-date.

But the point is, while there should be a file that has all the changes we’re going to incorporate in the next release, we may want to divide the separate releases into separate documentation pages, instead of using a combined file.

[BoboTiG]

Within docs/source/release-history, we have one file for each release: v10.1.0.md (or .rst), v10.0.0.md, v9.0.2.md, etc.

👍 (.md)

CHANGELOG.md and CHANGES.md

I see no need to retain either of these.

👍

I like the direction we're heading in.