MAINT: Improve changelog documentation process

[larsoner]

To aid in releases and PRs, it would be nice not to have to do so much changelog management. In particular, it would be great if:

1. We didn't have to tell people to add anything to doc/changes/latest.inc
2. A changelog could be (at least nearly) automatically generated

Ideas:

• In sphinx-gallery we use github-changelog-generator in between releases. You label PRs (before or after merge!) to get them correctly categorized as enhancement/bug. I think you can even change the PR title after the merge to then have that text used in the changelog entry.

Clearly this list is incomplete :) @drammock or others feel free to add other ideas up here after commenting about them below

[larsoner]

... and as part of this, we should abandon any further updates to names.inc. We can keep it for posterity / our old logs, but for the future we should use some automated tool to get the change -> GH user link, which then gets us their name (contributors should keep their GH profile up to date, if they don't, then they just get their handle as their name, which I think is okay) and we just link to their GH profile -- where they can keep and update their own URLs.

[agramfort]

can we first experiment with this on a smaller repo like mne-bids ?

…

Message ID: ***@***.***>

[larsoner]

At least github-changelog-generator we've already used in SG for years now. But yes if we want to try something else then we could experiment elsewhere in principle.

But in practice I think you try the tool and see if it produces some usable RST or not, so it would be easy to evaluate in a PR I think....

[agramfort]

ok you know better. Let's try !

…

Message ID: ***@***.***>

[sappelhoff]

I think you can even change the PR title after the merge to then have that text used in the changelog entry.

yes, and you can also define a certain GitHub label to explicitly exclude a PR / issue from the changelog, see e.g.:

https://github.com/bids-standard/bids-specification/blob/5d749397c50d33a498c629c279171667f439fae7/.circleci/config.yml#L123

[larsoner]

FWIW I just went through the process with sphinx-gallery and this is the result:

https://sphinx-gallery.github.io/stable/changes.html#v0-12-0

label->section mapping is configurable. It still involves a few steps but in general it's faster and I think I'd prefer it to what we have now.

Ahead of our next release I could try running it on our repo for 1.4 and we could see the result. I don't think it would take too much time for me to mock it up at least.

[drammock]

another candidates:

• https://github.com/executablebooks/github-activity (I think this is what pydata-sphinx-theme uses? I've never actually done a release of the theme)
• https://github.com/twisted/towncrier (astropy/sunpy use this)

[larsoner]

Tentative plan from discussion with @agramfort and @drammock :

1. Continue using devel.rst for 1.6 release (i.e., ~1 month)
2. Use github_changelog_generator for the 1.7 release, meaning we no longer change devel.rst with every change

In the next month, I can try github_changelog_generator to see what it would have produced for 1.6 so we can iterate on that process ahead of time to make sure it's tractable.

[larsoner]

@drammock thinking about this again, I'm starting to think towncrier might make sense:

1. Used by astropy etc. so we're not alone or blazing a new trail
2. There is an action to make sure there is a fragment which will help maintenance
3. Customizable sections will allow us to easily address DOC: Update changelog sections #12233