These are the steps for making a new music21 release.
Run uv sync. This installs all the devtools the steps below need.
Install separately:
pandoc— brew install pandoc
-
Update
__version__inmusic21/_version.pyand the single test case inbase.py. -
Run
corpus.corpora.CoreCorpus().cacheMetadata(). For a major change that affects parsing, runcorpus.corpora.CoreCorpus().rebuildMetadataCache()instead (~2 min on an M4). Either of these may change a lot of tests incorpus,metadata, etc., so do not skip the next step. -
Run
uv run documentation/testDocumentation.py, then fix errors.- You cannot check whether fixed tests work while it is still running.
- This takes a while, runs single-core, and then almost always needs code patches, so allocate time (~2 min on an M4). Start working on the announcement while it runs.
- You cannot run steps 2 and 3 in parallel, since metadata changes often cause documentation changes.
- developerReference/musicxmlTest - 41b and 41c are currently failing and acceptable.
- usersGuide_22_graphing 3dbars sometimes returns 1, sometimes 2 Axes. It should just do one...
-
uv run music21/test/warningMultiprocessTest.pyfor the lowest and highest supported Python versions — fix all warnings. -
Run
from music21.test import treeYield, then:treeYield.find_all_non_hashable_m21objects()and check that the returned set is empty. (It prints a bunch of module names, but only the finalset()being empty matters.)- Then the same for
treeYield.find_all_non_default_instantiation_m21objects(). If that one isn't empty it is not a bug, and v11 will make some M21 objects require arguments (such as VoiceLeadingQuartet)
-
Commit and wait for results on GitHub Actions. (Normally not necessary — it's slower and mostly duplicates
multiprocessTest— but should be done before making a release.) -
uv run documentation/make.py clean(skip on minor version changes). You may need to create adocumentation/builddirectory first. -
uv run documentation/make.py linkcheck. Some persistent errors that actually work are listed inconf.pyunderlinkcheck_ignore. Note that since AI-Agent world, more and more links are being blocked from bot checking. -
uv run documentation/make.py-- build the documentation HTML files and supports. -
uv run documentation/upload.py— zipsdocumentation/build/htmland uploads it tomusic21.org/music21docs/. Requires MSAC's private key. Or MSAC has a program combine_sync/deploy.py that will do this automatically when he updates the site. -
Zip up
documentation/build/htmland get ready to upload/delete it (your desktop or wherever is fine). Rename tomusic21-X.Y.Z-docs.zip(skip for Alpha/Beta). -
From the music21 main folder (not a subfolder) run
uvx hatch build. This buildsdist/music21-X.Y.Z.tar.gzanddist/music21-X.Y.Z-py3-none-any.whl. -
Run
uv run scripts/buildNoCorpus.py: it builds the no-corpus version of music21. -
PR and commit to GitHub at this point w/ a commit comment of the new version, then don't change anything until the next step is done. Merge to main/master. (
.gitignoreavoids uploading the large files created indist/.) -
Switch back to the master/main branch (or whatever main version you are releasing).
-
Tag the commit:
git tag -a vX.Y.Z -m "music21 vX.Y.Z". Don't forget thevin the release tag. Sanity-check that the correct commit was tagged:git log. -
Push that tag:
git push origin vX.Y.Z. -
Create a new release on GitHub (using the tag just created) and upload the non-wheel files created here and the docs. Drag in this order:
.tar.gz(wait to finish),-docs.zip(wait), andno-corpus.tar.gz. Finish this before doing the next step, even though it looks like it could be done in parallel. -
Upload the tar.gz file to PyPI:
uvx twine upload music21-X.Y.Z.tar.gz. -
Do the same for the
.whlfile (but not for the no-corpus file).-
You will need a
~/.pypircfile:[distutils] index-servers = pypi [pypi] username:__token__ password:pypi-API_TOKEN
-
The "password" is the API token you just created — if you lose this file you also lose the API token and have to create it again. This is all very poorly documented. It is not the "Unique identifier" you see in the "API Tokens" tab on the "Your Account" page — super confusing.
-
-
Delete the two
.tar.gzfiles and the.whlfile indist/(and the docs). -
For starting a new major release, create a GitHub branch to preserve the old one for patches, etc., especially during beta releases.
-
Immediately increment the number in
_version.pyand run test on__version__in base.py to prepare for the next release. -
Announce on the blog and to the list.
History: these steps and scripts/buildNoCorpus.py were a single dist/dist.py
until May 2026, split out so they would stop living in the disposable dist/
directory.