Release transformers-mlinter

Cuts a versioned release. The canonical prose reference is docs/release.md; this skill is the operational checklist. Publishing itself is done by CI — pushing the vX.Y.Z tag triggers .github/workflows/release.yml, which builds, tests, and publishes to PyPI via OIDC trusted publishing (no local upload).

Input

• <version>: the target release version X.Y.Z (e.g. 0.1.2). A pre-release uses X.Y.ZrcN.

Constraints

• Semantic versioning. Patch releases (Z bumps) reuse the existing vX.Y-release branch; a new minor/major starts a fresh vX.Y-release branch.
• Work from a clean checkout on main. Never publish uncommitted changes.
• Do NOT run twine upload locally — publishing is CI-only via the pushed tag.
• Always confirm with the user before pushing the tag (the tag push is the irreversible, publish-triggering step).

The version lives in one place

pyproject.toml [project].version is the single source of truth. At runtime mlinter/_version.py reads the version from the installed distribution metadata, falling back to pyproject.toml; nothing else hardcodes the release version. So a release bumps exactly one version field plus the CHANGELOG:

1. pyproject.toml — [project].version (the only version edit)
2. CHANGELOG.md — a new ## [X.Y.Z] - YYYY-MM-DD section (see step 2)

Do NOT reintroduce hardcoded version strings elsewhere. DEFAULT_BASE_VERSION in mlinter/_version.py is a static 0.0.0 sentinel and must stay unbumped; the docs/usage.md example suffix and the tests/test_mlinter.py version pins use fixed illustrative values (1.2.3+g1a2b3c4, 9.9.9) decoupled from the real release.

Workflow

1. Preflight. Confirm the branch is main, the tree is clean, and it is up to date (git status, git fetch && git status). Confirm the target <version> is greater than the latest tag (git tag).
2. Update CHANGELOG.md. Add a ## [X.Y.Z] - YYYY-MM-DD section (today's date) above the previous release, using ### Added (new TRF rules only, in rule-number order) / ### Improved (everything else that is not a bug fix) / ### Fixed. Keeping Added to rules alone is what makes it scannable — a release adds dozens. Summarize what landed since the last tag — git log vPREV..HEAD --oneline is the source. Each new TRFNNN rule and any change to file-discovery globs gets an entry.
3. Bump the version — set [project].version in pyproject.toml to <version>. That is the only version edit. For a release that added new TRFNNN rules, also add the corresponding public-API assertions in tests/test_mlinter.py (public_api.TRFNNN == "TRFNNN" and "TRFNNN" in public_api.__all__) — mirror the existing pattern.
4. Run local checks. All three must pass:

   make lint
   make test
   make typecheck

5. Build and validate the package.

   make build-release
   python -m twine check --strict dist/*

   Then smoke-test the wheel in a throwaway venv (adjust the version string):

   python -m venv /tmp/mlinter-release && source /tmp/mlinter-release/bin/activate
   pip install dist/*.whl
   cd /tmp && mlinter --version && python -m mlinter --version
   python -c "import mlinter; print(mlinter.__version__)"
   deactivate

   mlinter --version must print X.Y.Z (no +g... suffix from an installed wheel).
6. Commit the bump on main. Match the existing message style:

   git add pyproject.toml CHANGELOG.md
   git commit -m "preparing for X.Y.Z"
   git push origin main

   Add any other files the release genuinely touched (new rule modules, tests, etc.).
7. Update the release branch. For a new minor line:

   git switch -c vX.Y-release
   git push -u origin vX.Y-release

   For a patch on an existing line, fast-forward the branch from main:

   git switch vX.Y-release && git merge --ff-only main && git push origin vX.Y-release

   Pushing the branch runs the Release workflow's build+test job (no publish yet).
8. Tag and publish. Confirm with the user first, then from vX.Y-release:

   git tag vX.Y.Z -m "Release vX.Y.Z"
   git push origin vX.Y.Z

   The tag push triggers the build job again followed by the upload_package job, which runs in the pypi-release environment (may require reviewer approval) and publishes via pypa/gh-action-pypi-publish with OIDC. Watch the run with gh run watch or gh run list --workflow=release.yml.
9. Verify from PyPI once the publish job succeeds:

   python -m pip install -U "transformers-mlinter==X.Y.Z"
   mlinter --version

10. Open the next development version. With X.Y.Z published, move main off the released version so subsequent commits are not attributed to a version already on PyPI. Default to the next patch, X.Y.(Z+1), unless the user names a different target. Two edits:

    • pyproject.toml — set [project].version to the next version
    • CHANGELOG.md — add a bare ## [Unreleased] heading above the section just released, with no subsections; the next change adds its own ### Added / ### Improved / ### Fixed

    This lands on main through a branch, not a direct push:

    git switch main && git pull
    git switch -c start-NEXT
    # edit pyproject.toml and CHANGELOG.md
    git add pyproject.toml CHANGELOG.md
    git commit -m "Starting version NEXT"
    git push -u origin start-NEXT
    gh pr create --title "Starting version NEXT" --body "Post-release bump after X.Y.Z."
    gh pr merge --squash --delete-branch

    The squash keeps Starting version NEXT as the commit subject on main. Do not tag this commit and do not merge it into vX.Y-release — the release branch stays at the released version.

Notes

• No .dev0 suffix is used. Releasing is a single bump + tag; the step 10 post-release bump sets main to the next plain X.Y.Z.
• First-ever PyPI publish requires a pending trusted publisher configured on PyPI pointing at release.yml with environment pypi-release — see docs/release.md.
• Optional TestPyPI dry run is documented in docs/release.md and is manual.