MAINT: Use towncrier for release notes (mne-tools#12299)

.github/workflows/check_changelog.yml

@@ -0,0 +1,15 @@
+name: Changelog
+
+on:  # yamllint disable-line rule:truthy
+  pull_request:
+    types: [opened, synchronize, labeled, unlabeled]
+
+jobs:
+  changelog_checker:
+    name: Check towncrier entry in doc/changes/devel/
+    runs-on: ubuntu-latest
+    steps:
+      - uses: larsoner/action-towncrier-changelog@co  # revert to scientific-python @ 0.1.1 once bug is fixed
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BOT_USERNAME: changelog-bot

doc/changes/devel.rst

@@ -1,56 +1,5 @@
-.. NOTE: we use cross-references to highlight new functions and classes.
-   Please follow the examples below like :func:`mne.stats.f_mway_rm`, so the
-   whats_new page will have a link to the function/class documentation.
-
-.. NOTE: there are 3 separate sections for changes, based on type:
-   - "Enhancements" for new features
-   - "Bugs" for bug fixes
-   - "API changes" for backward-incompatible changes
-
-.. NOTE: changes from first-time contributors should be added to the TOP of
-   the relevant section (Enhancements / Bugs / API changes), and should look
-   like this (where xxxx is the pull request number):
-
-       - description of enhancement/bugfix/API change (:gh:`xxxx` by
-         :newcontrib:`Firstname Lastname`)
-
-   Also add a corresponding entry for yourself in doc/changes/names.inc
+.. See doc/development/contributing.rst for description of how to add entries.
 
 .. _current:
 
-Version 1.7.dev0 (development)
-------------------------------
-
-In this version, we started adding type hints (also known as "type annotations") to select parts of the codebase.
-This meta information will be used by development environments (IDEs) like VS Code and PyCharm automatically to provide
-better assistance such as tab completion or error detection even before running your code.
-
-So far, we've only added return type hints to :func:`mne.io.read_raw`, :func:`mne.read_epochs`, :func:`mne.read_evokeds` and
-all format-specific ``read_raw_*()`` and ``read_epochs_*()`` functions. Now your editors will know:
-these functions return evoked and raw data, respectively. We are planning add type hints to more functions after careful
-evaluation in the future.
-
-You don't need to do anything to benefit from these changes – your editor will pick them up automatically and provide the
-enhanced experience if it supports it!
-
-Enhancements
-~~~~~~~~~~~~
-- Speed up export to .edf in :func:`mne.export.export_raw` by using ``edfio`` instead of ``EDFlib-Python`` (:gh:`12218` by :newcontrib:`Florian Hofer`)
-- Inform the user about channel discrepancy between provided info, forward operator, and/or covariance matrices in :func:`mne.beamformer.make_lcmv` (:gh:`12238` by :newcontrib:`Nikolai Kapralov`)
-- We added type hints for the return values of raw, epochs, and evoked reading functions. Development environments like VS Code or PyCharm will now provide more help when using these functions in your code. (:gh:`12250`, :gh:`12297` by `Richard Höchenberger`_ and `Eric Larson`_)
-- Add ``method="polyphase"`` to :meth:`mne.io.Raw.resample` and related functions to allow resampling using :func:`scipy.signal.upfirdn` (:gh:`12268` by `Eric Larson`_)
-- The package build backend was switched from ``setuptools`` to ``hatchling``. This will only affect users who build and install MNE-Python from source. (:gh:`12269`, :gh:`12281` by `Richard Höchenberger`_)
-- :meth:`mne.Annotations.to_data_frame` can now output different formats for the ``onset`` column: seconds, milliseconds, datetime objects, and timedelta objects. (:gh:`12289` by `Daniel McCloy`_)
-
-Bugs
-~~~~
-- Allow :func:`mne.viz.plot_compare_evokeds` to plot eyetracking channels, and improve error handling (:gh:`12190` by `Scott Huberty`_)
-- Fix bug with accessing the last data sample using ``raw[:, -1]`` where an empty array was returned (:gh:`12248` by `Eric Larson`_)
-- Remove incorrect type hints in :func:`mne.io.read_raw_neuralynx` (:gh:`12236` by `Richard Höchenberger`_)
-- Fix bug where parent directory existence was not checked properly in :meth:`mne.io.Raw.save` (:gh:`12282` by `Eric Larson`_)
-- ``defusedxml`` is now an optional (rather than required) dependency and needed when reading EGI-MFF data, NEDF data, and BrainVision montages (:gh:`12264` by `Eric Larson`_)
-- Correctly handle temporal gaps in Neuralynx .ncs files via :func:`mne.io.read_raw_neuralynx` (:gh:`12279` by `Kristijan Armeni`_ and `Eric Larson`_)
-
-API changes
-~~~~~~~~~~~
-- The parameter for providing data to :func:`mne.time_frequency.tfr_array_morlet` and :func:`mne.time_frequency.tfr_array_multitaper` has been switched from ``epoch_data`` to ``data``. Only use the ``data`` parameter to avoid a warning (:gh:`12308` by `Thomas Binns`_)
+.. towncrier-draft-entries:: Version |release| (development)

doc/changes/devel/.gitignore

@@ -0,0 +1 @@
+!.gitignore

doc/changes/devel/12190.bugfix.rst

@@ -0,0 +1 @@
+Allow :func:`mne.viz.plot_compare_evokeds` to plot eyetracking channels, and improve error handling, y `Scott Huberty`_.

doc/changes/devel/12218.newfeature.rst

@@ -0,0 +1 @@
+Speed up export to .edf in :func:`mne.export.export_raw` by using ``edfio`` instead of ``EDFlib-Python``.

doc/changes/devel/12236.bugfix.rst

@@ -0,0 +1 @@
+Remove incorrect type hints in :func:`mne.io.read_raw_neuralynx`, by `Richard Höchenberger`_.

doc/changes/devel/12238.newfeature.rst

@@ -0,0 +1 @@
+Inform the user about channel discrepancy between provided info, forward operator, and/or covariance matrices in :func:`mne.beamformer.make_lcmv`, by :newcontrib:`Nikolai Kapralov`.

doc/changes/devel/12248.bugfix.rst

@@ -0,0 +1 @@
+Fix bug with accessing the last data sample using ``raw[:, -1]`` where an empty array was returned, by `Eric Larson`_.

doc/changes/devel/12250.newfeature.rst

@@ -0,0 +1 @@
+We added type hints for the return values of :func:`mne.read_evokeds` and :func:`mne.io.read_raw`. Development environments like VS Code or PyCharm will now provide more help when using these functions in your code. By `Richard Höchenberger`_ and `Eric Larson`_. (:gh:`12297`)

doc/changes/devel/12250.notable.rst

@@ -0,0 +1,11 @@
+In this version, we started adding type hints (also known as "type annotations") to select parts of the codebase.
+This meta information will be used by development environments (IDEs) like VS Code and PyCharm automatically to provide
+better assistance such as tab completion or error detection even before running your code.
+
+So far, we've only added return type hints to :func:`mne.io.read_raw`, :func:`mne.read_epochs`, :func:`mne.read_evokeds` and
+all format-specific ``read_raw_*()`` and ``read_epochs_*()`` functions. Now your editors will know:
+these functions return evoked and raw data, respectively. We are planning add type hints to more functions after careful
+evaluation in the future.
+
+You don't need to do anything to benefit from these changes – your editor will pick them up automatically and provide the
+enhanced experience if it supports it!

doc/changes/devel/12264.dependency.rst

@@ -0,0 +1 @@
+``defusedxml`` is now an optional (rather than required) dependency and needed when reading EGI-MFF data, NEDF data, and BrainVision montages, by `Eric Larson`_.

doc/changes/devel/12268.newfeature.rst

@@ -0,0 +1 @@
+Add ``method="polyphase"`` to :meth:`mne.io.Raw.resample` and related functions to allow resampling using :func:`scipy.signal.upfirdn`, by `Eric Larson`_.

doc/changes/devel/12269.newfeature.rst

@@ -0,0 +1 @@
+The package build backend was switched from ``setuptools`` to ``hatchling``. This will only affect users who build and install MNE-Python from source. By `Richard Höchenberger`_. (:gh:`12281`)

doc/changes/devel/12279.bugfix.rst

@@ -0,0 +1 @@
+Correctly handle temporal gaps in Neuralynx .ncs files via :func:`mne.io.read_raw_neuralynx`, by `Kristijan Armeni`_ and `Eric Larson`_.

doc/changes/devel/12282.bugfix.rst

@@ -0,0 +1 @@
+Fix bug where parent directory existence was not checked properly in :meth:`mne.io.Raw.save`, by `Eric Larson`_.

doc/changes/devel/12289.newfeature.rst

@@ -0,0 +1 @@
+:meth:`mne.Annotations.to_data_frame` can now output different formats for the ``onset`` column: seconds, milliseconds, datetime objects, and timedelta objects. By `Daniel McCloy`_.

doc/changes/devel/12299.other.rst

@@ -0,0 +1 @@
+Adopted towncrier_ for changelog entries, by `Eric Larson`_.

doc/changes/devel/12308.apichange.rst

@@ -0,0 +1 @@
+The parameter for providing data to :func:`mne.time_frequency.tfr_array_morlet` and :func:`mne.time_frequency.tfr_array_multitaper` has been switched from ``epoch_data`` to ``data``. Only use the ``data`` parameter to avoid a warning. Changes by `Thomas Binns`_.

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(

doc/development/contributing.rst

@@ -591,42 +591,54 @@ Describe your changes in the changelog
 --------------------------------------
 
 Include in your changeset a brief description of the change in the
-:ref:`changelog <whats_new>` (:file:`doc/changes/devel.rst`; this can be
-skipped for very minor changes like correcting typos in the documentation).
-
-There are different sections of the changelog for each release, and separate
-**subsections for bugfixes, new features, and changes to the public API.**
-Please be sure to add your entry to the appropriate subsection.
-
-The styling and positioning of the entry depends on whether you are a
-first-time contributor or have been mentioned in the changelog before.
-
-First-time contributors
-"""""""""""""""""""""""
-
-Welcome to MNE-Python! We're very happy to have you here. 🤗 And to ensure you
-get proper credit for your work, please add a changelog entry with the
-following pattern **at the top** of the respective subsection (bugs,
-enhancements, etc.):
-
-.. code-block:: rst
-
-
-  Bugs
-  ----
-
-  - Short description of the changes (:gh:`0000` by :newcontrib:`Firstname Lastname`)
-
-  - ...
-
-where ``0000`` must be replaced with the respective GitHub pull request (PR)
-number, and ``Firstname Lastname`` must be replaced with your full name.
-
-It is usually best to wait to add a line to the changelog until your PR is
-finalized, to avoid merge conflicts (since the changelog is updated with
-almost every PR).
-
-Lastly, make sure that your name is included in the list of authors in
+:ref:`changelog <whats_new>` using towncrier_ format, which aggregates small,
+properly-named ``.rst`` files to create a change log. This can be
+skipped for very minor changes like correcting typos in the documentation.
+
+There are six separate sections for changes, based on change type.
+To add a changelog entry to a given section, name it as
+:file:`doc/changes/devel/<PR-number>.<type>.rst`. The types are:
+
+notable
+    For overarching changes, e.g., adding type hints package-wide. These are rare.
+dependency
+    For changes to dependencies, e.g., adding a new dependency or changing
+    the minimum version of an existing dependency.
+bugfix
+    For bug fixes. Can change code behavior with no deprecation period.
+apichange
+    Code behavior changes that require a deprecation period.
+newfeature
+    For new features.
+other
+    For changes that don't fit into any of the above categories, e.g.,
+    internal refactorings.
+
+For example, for an enhancement PR with number 12345, the changelog entry should be
+added as a new file :file:`doc/changes/devel/12345.enhancement.rst`. The file should
+contain:
+
+1. A brief description of the change, typically in a single line of one or two
+   sentences.
+2. reST links to **public** API endpoints like functions (``:func:``),
+   classes (``:class``), and methods (``:meth:``). If changes are only internal
+   to private functions/attributes, mention internal refactoring rather than name
+   the private attributes changed.
+3. Author credit. If you are a new contributor (we're very happy to have you here! 🤗),
+   you should using the ``:newcontrib:`` reST role, whereas previous contributors should
+   use a standard reST link to their name. For example, a new contributor could write:
+
+   .. code-block:: rst
+
+      Short description of the changes, by :newcontrib:`Firstname Lastname`.
+
+   And an previous contributor could write:
+
+   .. code-block:: rst
+
+      Short description of the changes, by `Firstname Lastname`_.
+
+Make sure that your name is included in the list of authors in
 :file:`doc/changes/names.inc`, otherwise the documentation build will fail.
 To add an author name, append a line with the following pattern (note
 how the syntax is different from that used in the changelog):
@@ -638,27 +650,13 @@ how the syntax is different from that used in the changelog):
 Many contributors opt to link to their GitHub profile that way. Have a look
 at the existing entries in the file to get some inspiration.
 
-Recurring contributors
-""""""""""""""""""""""
-
-The changelog entry should follow the following patterns:
-
-.. code-block:: rst
-
-    - Short description of the changes from one contributor (:gh:`0000` by `Contributor Name`_)
-    - Short description of the changes from several contributors (:gh:`0000` by `Contributor Name`_, `Second Contributor`_, and `Third Contributor`_)
-
-where ``0000`` must be replaced with the respective GitHub pull request (PR)
-number. Mind the Oxford comma in the case of multiple contributors.
-
 Sometimes, changes that shall appear as a single changelog entry are spread out
-across multiple PRs. In this case, name all relevant PRs, separated by
-commas:
+across multiple PRs. In this case, edit the existing towncrier file for the relevant
+change, and append additional PR numbers in parentheticals with the ``:gh:`` role like:
 
 .. code-block:: rst
 
-    - Short description of the changes from one contributor in multiple PRs (:gh:`0000`, :gh:`1111` by `Contributor Name`_)
-    - Short description of the changes from several contributors in multiple PRs (:gh:`0000`, :gh:`1111` by `Contributor Name`_, `Second Contributor`_, and `Third Contributor`_)
+    Short description of the changes, by `Firstname Lastname`_. (:gh:`12346`)
 
 Test locally before opening pull requests (PRs)
 -----------------------------------------------

doc/links.inc

@@ -96,6 +96,7 @@
 .. _PIL: https://pypi.python.org/pypi/PIL
 .. _tqdm: https://tqdm.github.io/
 .. _pooch: https://www.fatiando.org/pooch/latest/
+.. _towncrier: https://towncrier.readthedocs.io/
 
 .. python editors
 

pyproject.toml

@@ -146,6 +146,7 @@ doc = [
     "pydata_sphinx_theme==0.13.3",
     "sphinx-gallery",
     "sphinxcontrib-bibtex>=2.5",
+    "sphinxcontrib-towncrier",
     "memory_profiler",
     "neo",
     "seaborn!=0.11.2",
@@ -291,6 +292,7 @@ ignore_directives = [
     "toctree",
     "rst-class",
     "tab-set",
+    "towncrier-draft-entries",
 ]
 ignore_messages = "^.*(Unknown target name|Undefined substitution referenced)[^`]*$"