Repository: mne-tools/mne-python

Issue:
MAINT: Improve changelog documentation process
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](https://github.com/github-changelog-generator/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


Discussion:
... 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.
can we first experiment with this on a smaller repo like mne-bids ?

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

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....
ok you know better. Let's try !

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

> 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
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.
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)
Tentative plan from discussion with @agramfort and @drammock :

1. Continue using `devel.rst` for 1.6 release (i.e., ~1 month)
3. 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.
@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](https://github.com/scientific-python/action-towncrier-changelog) which will help maintenance
3. [Customizable sections](https://towncrier.readthedocs.io/en/stable/tutorial.html#creating-news-fragments) will allow us to easily address #12233

Resolving patch:
diff --git a/doc/conf.py b/doc/conf.py
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -51,9 +51,8 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-curdir = os.path.dirname(__file__)
-sys.path.append(os.path.abspath(os.path.join(curdir, "..", "mne")))
-sys.path.append(os.path.abspath(os.path.join(curdir, "sphinxext")))
+curpath = Path(__file__).parent.resolve(strict=True)
+sys.path.append(str(curpath / "sphinxext"))
 
 
 # -- Project information -----------------------------------------------------
@@ -107,6 +106,7 @@
     "sphinx_gallery.gen_gallery",
     "sphinxcontrib.bibtex",
     "sphinxcontrib.youtube",
+    "sphinxcontrib.towncrier.ext",
     # homegrown
     "contrib_avatars",
     "gen_commands",
@@ -123,7 +123,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_includes"]
+exclude_patterns = ["_includes", "changes/devel"]
 
 # The suffix of source filenames.
 source_suffix = ".rst"
@@ -149,6 +149,10 @@
 copybutton_prompt_text = r">>> |\.\.\. |\$ "
 copybutton_prompt_is_regexp = True
 
+# -- sphinxcontrib-towncrier configuration -----------------------------------
+
+towncrier_draft_working_directory = str(curpath.parent)
+
 # -- Intersphinx configuration -----------------------------------------------
 
 intersphinx_mapping = {
@@ -804,7 +808,7 @@ def append_attr_meth_examples(app, what, name, obj, options, lines):
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-switcher_version_match = "dev" if release.endswith("dev0") else version
+switcher_version_match = "dev" if ".dev" in version else version
 html_theme_options = {
     "icon_links": [
         dict(


Test patch: