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.