Bump Version
Developmentbump-versionBump Version is an Agent Skill for development published in the cuthbertLab/music21 repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
When and how to bump music21's version number. Use this whenever a change warrants a new version — especially any change to a parsing format or parser (musicxml, abc, MIDI, noteworthy/NWC, humdrum, etc.), since those invalidate the pickled-stream cache — as well as new features and bug fixes. Covers which digit to change, the even/odd minor and beta-suffix conventions, the TWO files to edit, and the `Changed in`/`New in` docstring markers.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/cuthbertLab/music21/blob/HEAD/.agents/skills/bump-version/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/bump-version, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Bumping music21's version
The version lives in music21/_version.py as
__version__ = 'MAJOR.MINOR.PATCHsuffix' (e.g. '11.0.0b2'). The
__version_info__ tuple is derived from it automatically — only edit the
string.
Two files to change, always together
music21/_version.py— the__version__string.music21/base.py— the single version doctest:
This test exists specifically to force you to remember the bump. If you change>>> music21.VERSION_STR '11.0.0b2'_version.pywithout it, the doctest fails.
Verify both with:
uv run pytest --doctest-modules music21/base.py music21/_version.py
(or uv run python -c "import music21; print(music21.VERSION_STR)").
When to bump
- Parsing-format / parser changes (most common reason). Any change to how a format is read or written — musicxml, abc, MIDI, noteworthy/NWC, humdrum, etc. — should bump the version, even a refactor, because the version is baked into the pickled-stream cache (cached parsed files). Bumping invalidates stale pickles so users don't get results from the old parser. This is the rule in AGENTS.md ("Changes to parsing formats … need to update the patch version").
- New feature → bump (see digit rules below); mark it in docstrings with
* New in vX: …. - Bug fix → bump the patch; if it changes public behavior, mark
* Changed in vX: …. - Pure internal refactor with no behavioral/pickle impact → usually no bump.
Which part to change
music21 follows semver-ish rules (see the _version.py docstring for the full
rationale):
- MAJOR (X) — breaks old features. Rare.
- MINOR (Y) — new features. Even Y = alpha/beta, odd Y = release.
X.0(e.g.11.0) are development releases that can still change untilX.1. - PATCH (Z) — bug fixes and parsing/pickle-invalidating changes.
- beta suffix (
bN) — successive pre-release builds of the sameMAJOR.MINOR.PATCH. To cut another beta without otherwise changing the number, increment it:11.0.0b1→11.0.0b2. (This is what a parser change during a…b1cycle does.)
Changed in / New in docstring markers
When a bump accompanies a public-interface change, annotate the affected method/class docstring:
* Changed in vX: one-line explanation.* New in vX: one-line explanation.
Pick X from the AGENTS.md rule: if the current version is MAJOR.0…, use
Changed in vMAJOR; if it's MAJOR.[even], use the next odd minor (e.g. at
10.2, write Changed in 10.3); if it's already odd, use the following odd
number. (Humans remove the AI-assisted note on review; leave the version marker.)
Checklist
- Edit
__version__inmusic21/_version.py. - Edit the
VERSION_STRdoctest inmusic21/base.pyto match. - Add/update
Changed in/New inmarkers on any changed public API. uv run pytest --doctest-modules music21/base.py music21/_version.py.