Create release notes page

[timhoffm]

... containing "what's new", "API changes" and "GitHub stats" by version
number.

[jklymak]

I think this is good if we don't already have this (I'm confused - we don't?) Would you consider flattening this? A changelog is often helpful when you want to see when a change was made, and that is often easier if you just open a single (very large) page and search the changes in chronological order.

[tacaswell]

I am 👍 on this being a page, but am +0 on the name. While it is an accurate description of what is on the page, it does not conform to my expectation of what a change log is.

[timhoffm]

The primary goal of this PR is to clean up our convoluted content stucture: Change-related docs were spread out over various places.

I'm not clinging to the name. Call it "Release notes" or "What's new" or whatever you like. I also think that a flat page would be easier to search. But that would take some more effort / need disscussions:

• Can we do with includes or do we have to have one giant single page?

• How do we organize the order what's new/API changes/github stats? Should github stats appear in the flattened list or should they be separate as they are quite verbose and duplicate to the other two. If separate, we should probably add a link from the single page. Should the github stats themselves be a single page or one per release?

• For flattening we might have to adapt the release process.

• Is it still reasonable to have the repo structures?

  • doc/api/next_api_changes/...
  • doc/api/prev_api_changes/...
  • doc/api/api_changes.rst
  • doc/users/next_whats_new/...
  • doc/users/prev_whats_new/...
  • doc/users/whats_new.rst

  To me API changes and whats_new are both variants of changes tied to releases. Having them in separate subfolders always confuses me.

I don't plan to go into this deeper for now.

[timhoffm]

@jklymak I disagree with the PR being in draft status. I consider collecting all change-related information under one page already a significant improvement. I'm happy to do minor changes like renaming if somebody suggests a better name. I won't get into the tedious business of flattening or restructuring the single documents.

The current state is is as good as I'm intending to make this. Thus I've marked this ready for review.

[jklymak]

I guess I misinterpreted "I don't plan to go deeper into this for now" as you were not planning to work on the PR further.

[QuLogic]

I don't understand where 'current' API changes go on release time, if not here?

[timhoffm]

On a release everything moves from next to the respective version section:

Instead of this

.. include:: prev_api_changes/api_changes_3.4.2.rst

you'll have in release_notes.rst

../api/prev_api_changes/api_changes_3.4.2.rst

API changes has changed it's position in the hierachry. It used to be top-levelish and contained the next changes as well as links to the previous changes. Now, it's only a sub topic Release notes -> Next -> API changes. I will rename it to Next API Changes to make that more clear.

[QuLogic]

Then the if dev bit shouldn't be in this file, but in the new release notes file? There should be no 'next changes' for tagged releases.

This would also needs updates to the release guide.

[timhoffm]

Yes, I've noticed the if dev part. I've made it structurally the same as "Next what's new" now.

I've added if dev around the "Release notes > Next" section. What I'm not 100% clear about is how conditional pages are handled. Due to the if dev we may get notes that the pages are next_api_changes is not in the toc tree when building the release.

Please check if the structure is now ok. I can have a look at the release guide later, but that doesn't make sense before the structure is settled.

[QuLogic]

I'd say Release Notes, over Changelog.

[jklymak]

I think this is an improvement...

[timhoffm]

checking consistency... /home/circleci/project/doc/api/next_api_changes.rst: WARNING: document isn't included in any toctree
/home/circleci/project/doc/users/github_stats.rst: WARNING: document isn't included in any toctree
/home/circleci/project/doc/users/next_whats_new.rst: WARNING: document isn't included in any toctree

I don't know why these messages appear. They are included in a toctree in release_notes.rst. Maybe this is because the respective toctree is contained in an .. ifconfig:: releaselevel == 'dev'.

Any help on how to handle conditional pages is welcome (we want the next* docs only in dev doc builds but not in release builds).

[timhoffm]

We may not be able to use .. ifconfig to manipulate the toc. From https://www.sphinx-doc.org/en/master/usage/extensions/ifconfig.html:

Warning

This directive is designed to control only content of document. It could not control sections, labels and so on.

Edit: Indeed this is not supported: sphinx-doc/sphinx#1717 (comment)

[jklymak]

@timhoffm is this still ready to go?

[timhoffm]

Yes, this is ready to go. I‘ll have to update the release guide. But I will do that only after this is finished so that I don‘t have to change the release guide multiple times.

[jklymak]

... added to the call.

[jklymak]

@QuLogic are you OK with this now given that @timhoffm says he will definitely update the contrib docs?