-
Notifications
You must be signed in to change notification settings - Fork 1.3k
How to make a major or minor release
- We no longer use an upper bound on the theme version, so make sure https://mne.tools/dev looks okay
- Go to our Contributor credit action, and manually
Run Workflow
if needed to trigger an update of the PR jsons.
- Fix other milestone issues and PRs.
- Check dev-docs build to make sure they look OK, and check CircleCI to make sure the most recent build was green. NOTE: If any PRs were merged since the most recent overnight run of
build-dev-docs
, you may need to run a[circle deploy]
to get the docs up-to-date with the desired state of the code at release time. - Manually update counts in
doc/documentation/cited.rst
- Squash all website commits since the last release:
# find the appropriate hash, should be the previous "Archive X-1.Y" commit $ git fetch origin $ git checkout main $ git reset --hard origin/main $ git clean -xdf $ git log | grep -B4 "Archive" | head -5 commit e9ec0b8f29b791a2a60764976d595923b24eb302 Author: Eric Larson <[email protected]> Date: Fri Apr 19 09:26:05 2024 -0400 Archive 1.6 $ git reset --soft e9ec0b8f29b791a2a60764976d595923b24eb302 $ git commit -am "X.Y Squash" $ cp -a stable X.W # the previous stable version $ git add X.W/* $ git commit -m "Archive X.W" $ git push origin -f main
-
Generate author list (note there is a version number in this command, be sure to update it):
git shortlog -s --group=author --group=trailer:co-authored-by HEAD...v1.6.0 | sed "s/^ *[0-9]* *\t*/* /"
Using the --group option in
git shortlog
is important to capture "co-authored-by", and requires git 2.29+ (if your git is older than that, there is an official git PPA for debian-like systems). -
Add missing authors. Add anyone missing from the author list (e.g., first-time contributors who did not (co)author any commits but contributed during review/iteration). NOTE: make sure things are clean / not in process before doing this:
git commit --allow-empty --author="First last <[email protected]>" -m "Empty commit for credit"
-
Ensure full names for all authors. If there are authors without full names, check if they already exist in
doc/changes/names.inc
; if so, update.mailmap
to map their full name to their alias. If they're not yet indoc/changes/names.inc
, use the--email
option in thegit shortlog
command above to get their email address and ping them to ask if they want to provide a full name and URL; when they do, update.mailmap
anddoc/changes/names.inc
. -
Deduplicate authors. Check the list for duplicate names (e.g., Alex Gramfort and Alexandre Gramfort) and deduplicate by adding more
.mailmap
entries. -
Use towncrier to turn stubs into a finalized page by running
towncrier
in the project root:towncrier build --yes --version 1.8.0
-
Add "authors" section to the bottom of
doc/changes/devel.rst
and removetowncrier
cruft. Rerun thegit shortlog
command above to generate the final list and remove[bot]
authors. Look at previous files (doc/changes/v1.7.rst
) for formatting example. Runmake codespell
and add any violating names toignore_words.txt
. -
Highlight new contributors. Move
:newcontrib:
entries to the top of each section, then manually add + symbols next to new contributors in theAuthors
list. Some users will not be associated with a given pull request / have a:newcontrib:
entry --git grep <name>
can tell you if it's their first time contributing. -
Add changelog shortcut. At the top of
doc/changes/devel.rst
add.. _changes_X_Y_Z:
. -
Rename changelog file.
git mv doc/changes/devel.rst doc/changes/vX.Y.rst
-
Update
doc/development/whats_new.rst
to point toX.Y.inc
instead ofdevel.rst
- In mne-python, update
doc/_static/versions.json
to add an entry and updated stable/devel. - Update the supported version table in
SECURITY.md
- Edit
tools/generate_codemeta.py
to update thecompound_surnames
variable (if needed, based on new contributors from the changelog). - Then run
python tools/generate_codemeta.py X.Y.Z
to update the codemeta metadata and CITATION.cff files for this release, and stage them:git add codemeta.json CITATION.cff
- If you have been committing along the way, squash your commits. Otherwise commit all changes made so far
- Push to
upstream main
(or merge in your "prep for release" PR)
- Use the GitHub feature "Releases" to make a new release. Use
vX.Y.Z
for all fields (version number, name, description), otherwise they get auto-populated with annoying things. The "target" of the release should bemain
. This should automatically push to PyPI, which should then automatically trigger a conda-forge update.
- Create and check out a new branch
maint/X.Y
based on currentupstream/main
/ tagvX.Y.Z
- Edit
.circleci/config.yml
to change names "build_docs_main" to "build_docs_stable", change the workflow name from "main" to "stable", change the branch filter frommain
to/maint\/.*/
(regex), and change the scheduled build time to 4 AM GMT (e.g., this commit, which also contains the following step as well). - Edit
pyproject.toml
to haveversion = "X.Y.Z" instead of "dynamic = ["version"]
. Push. - Check out the previous stable branch (
maint/X.Y-1
ormaint/X-1.Y
) and remove the "stable" workflow from.circleci/config.yml
. Commit and push this to the appropriatemaint/X-1.Y
branch with[ci skip]
in the commit message.
- Update conda-forge/mne-feedstock. This will eventually happen automatically (example here, but you can speed things up by opening a manual pull request. At a minimum, you must update
version
andsha256
inrecipe/meta.yaml
; other additions will depend on what has changed for the project (e.g., minimum dependency versions). You can get the sha sum fromsha256 dist/mne-X.Y.Z.tar.gz
or by looking at "view hashes" of the release on PyPI like here for 1.7.
Back on main
:
- Restore devel.rst
cp doc/changes/devel.rst.template doc/changes/devel.rst git add doc/changes/devel.rst
- Add
../changes/devel.rst
back into thetoctree::
indoc/development/whats_new.rst
- Commit and push to
main
- Update MNE Installers. Using
git grep "1\.7\.[0-9]" -- ':!*.svg' doc/
for example go through and change to1.8.0
. - Update documentation links to installers. Change button links
doc/install/installers.rst
to point to the new installer files. Make sure to update links for all 3 platforms. Push this change to bothmaint/X.Y
andmain
, with commit message[circle deploy]
.
- email [email protected]
- add a post in the Announcements category on Discourse. After posting, close it (so no replies allowed), then pin it globally.
- unpin the previous release announcement on Discourse.
- announce on Discord (optional)
- Find all the deprecations that are slated to be removed in the now-current dev version, and open a PR to remove them with something like
make -C tools/dev dep
, which willgit grep
deprecation andFutureWarning
-related things for you.
- Look at
pyproject.toml
and bump minimums to the package releases that existed ~2 years ago at the expected time of next release, e.g., by looking on PyPI release pages. - Bump the
mne==1.9.0
requirement in.pre-commit-config.yaml
- Check out the repo.
# make sure your ssh key + ssh config is configured for the remote repo, then: git clone ssh://git.debian.org/git/debian-med/python-mne.git cd python-mne uscan --verbose --force-download git import-orig --pristine-tar ../mne-python_XXX.orig.tar.gz dch -i # update changelog + eventually copyright is need files added
- [ ] *Remove previous builds if they exist.*
```bash
rm -r build
rm mne/html/bootstrap.min.js
rm debian/python-mne*
rm -r debian/python-mne
- Build the package.
git-buildpackage --git-verbose --git-ignore-new -uc -us --git-tag
- If the build fails: make modifications, commit the patch and try building again:
dpkg-source --commit
- Check conformity to debian build rules.
lintian -i python-mne*.changes cme fix dpkg-copyright # check formatting of copyright file
- Commit the release.
git push