Skip to content

Commit

Permalink
MAINT: Use towncrier for release notes (mne-tools#12299)
Browse files Browse the repository at this point in the history
  • Loading branch information
larsoner authored and snwnde committed Mar 20, 2024
1 parent 7027e03 commit 646f4d6
Show file tree
Hide file tree
Showing 23 changed files with 106 additions and 145 deletions.
15 changes: 15 additions & 0 deletions .github/workflows/check_changelog.yml
Original file line number Diff line number Diff line change
@@ -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
55 changes: 2 additions & 53 deletions doc/changes/devel.rst
Original file line number Diff line number Diff line change
@@ -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)
34 changes: 0 additions & 34 deletions doc/changes/devel.rst.template

This file was deleted.

1 change: 1 addition & 0 deletions doc/changes/devel/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
!.gitignore
1 change: 1 addition & 0 deletions doc/changes/devel/12190.bugfix.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Allow :func:`mne.viz.plot_compare_evokeds` to plot eyetracking channels, and improve error handling, y `Scott Huberty`_.
1 change: 1 addition & 0 deletions doc/changes/devel/12218.newfeature.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Speed up export to .edf in :func:`mne.export.export_raw` by using ``edfio`` instead of ``EDFlib-Python``.
1 change: 1 addition & 0 deletions doc/changes/devel/12236.bugfix.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Remove incorrect type hints in :func:`mne.io.read_raw_neuralynx`, by `Richard Höchenberger`_.
1 change: 1 addition & 0 deletions doc/changes/devel/12238.newfeature.rst
Original file line number Diff line number Diff line change
@@ -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`.
1 change: 1 addition & 0 deletions doc/changes/devel/12248.bugfix.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Fix bug with accessing the last data sample using ``raw[:, -1]`` where an empty array was returned, by `Eric Larson`_.
1 change: 1 addition & 0 deletions doc/changes/devel/12250.newfeature.rst
Original file line number Diff line number Diff line change
@@ -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`)
11 changes: 11 additions & 0 deletions doc/changes/devel/12250.notable.rst
Original file line number Diff line number Diff line change
@@ -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!
1 change: 1 addition & 0 deletions doc/changes/devel/12264.dependency.rst
Original file line number Diff line number Diff line change
@@ -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`_.
1 change: 1 addition & 0 deletions doc/changes/devel/12268.newfeature.rst
Original file line number Diff line number Diff line change
@@ -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`_.
1 change: 1 addition & 0 deletions doc/changes/devel/12269.newfeature.rst
Original file line number Diff line number Diff line change
@@ -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`)
1 change: 1 addition & 0 deletions doc/changes/devel/12279.bugfix.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Correctly handle temporal gaps in Neuralynx .ncs files via :func:`mne.io.read_raw_neuralynx`, by `Kristijan Armeni`_ and `Eric Larson`_.
1 change: 1 addition & 0 deletions doc/changes/devel/12282.bugfix.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Fix bug where parent directory existence was not checked properly in :meth:`mne.io.Raw.save`, by `Eric Larson`_.
1 change: 1 addition & 0 deletions doc/changes/devel/12289.newfeature.rst
Original file line number Diff line number Diff line change
@@ -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`_.
1 change: 1 addition & 0 deletions doc/changes/devel/12299.other.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Adopted towncrier_ for changelog entries, by `Eric Larson`_.
1 change: 1 addition & 0 deletions doc/changes/devel/12308.apichange.rst
Original file line number Diff line number Diff line change
@@ -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`_.
14 changes: 9 additions & 5 deletions doc/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 -----------------------------------------------------
Expand Down Expand Up @@ -107,6 +106,7 @@
"sphinx_gallery.gen_gallery",
"sphinxcontrib.bibtex",
"sphinxcontrib.youtube",
"sphinxcontrib.towncrier.ext",
# homegrown
"contrib_avatars",
"gen_commands",
Expand All @@ -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"
Expand All @@ -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 = {
Expand Down Expand Up @@ -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(
Expand Down
104 changes: 51 additions & 53 deletions doc/development/contributing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand All @@ -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)
-----------------------------------------------
Expand Down
1 change: 1 addition & 0 deletions doc/links.inc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -291,6 +292,7 @@ ignore_directives = [
"toctree",
"rst-class",
"tab-set",
"towncrier-draft-entries",
]
ignore_messages = "^.*(Unknown target name|Undefined substitution referenced)[^`]*$"

Expand Down

0 comments on commit 646f4d6

Please sign in to comment.