Releasing MultimodalSRM¶

Package publication is deliberately blocked while model-integration.json says awaiting-model-import. Do not upload a placeholder package to claim the name. The repository can be public while the implementation is being prepared.

One-time Trusted Publisher registration¶

Configure a pending publisher in each account's publishing settings. The two package indices have separate accounts and configuration.

Create the matching GitHub environments. The workflow uses OIDC with id-token: write only in publishing jobs; no long-lived API token is needed. Publisher registration is an account-side prerequisite and is not accomplished by committing the workflow. A pending publisher does not reserve the project name. See PyPI's pending publisher guide and publishing guide.

Release candidate¶

1. Complete the model handoff, required suites, clean installed-artifact checks and documentation.
2. Set the single version in src/multimodalsrm/_version.py, for example 0.1.0rc1, and close out the changelog. The version must not be a development or local build.
3. Commit reviewed changes, let fast PR CI pass and create the matching Git tag, for example v0.1.0rc1. You can also run Full test suite manually on a branch before tagging; it does not publish.
4. Manually run Release with that tag. Manual runs publish only to TestPyPI after resolving the tag to one commit and running full-tests.yml: the complete Linux/macOS model matrix and installed wheel/sdist checks. Fast PR CI never replaces this release gate.
5. Install the exact candidate from TestPyPI in a clean environment and exercise its workflows. Resolve dependencies from PyPI separately; avoid allowing TestPyPI to supply arbitrary runtime dependencies. Record the version, artifact hashes and results.

Changelog¶

CHANGELOG.md at the repository root follows Keep a Changelog. Merged work accumulates under ## [Unreleased], so it never claims to have shipped in a version that is already published.

To close it out for a release:

1. Rename ## [Unreleased] to ## [<version>] — <YYYY-MM-DD> and open a fresh, empty ## [Unreleased] above it.
2. Update the link definitions at the bottom of the file: point [Unreleased] at compare/v<version>...HEAD and add a [<version>] entry for the release tag.

3. Regenerate the documentation page:

   python scripts/sync_changelog.py
   

4. Commit both CHANGELOG.md and docs/changelog.md.

docs/changelog.md is generated, never edited by hand. tests/infrastructure/test_changelog.py fails if it drifts from the root file, if a released section lacks a date, or if [Unreleased] is missing, so a forgotten sync fails fast PR CI rather than publishing a stale page.

Production¶

Publish a GitHub Release for the intended version tag. The Release workflow resolves the tagged commit, checks source readiness/version agreement, builds the distributions once, runs the full suite against those artifacts and uploads those same artifacts to PyPI only after the full workflow succeeds. A main-branch push alone never publishes. Prerelease GitHub Releases can publish genuine prerelease versions to PyPI; reserve manual runs for TestPyPI rehearsal.

Successful registration or CI does not prove an upload succeeded. Verify the published project version and clean installation after the first real deployment. A development version must be replaced by a reviewed release version before an upload can pass the version gate.

Failures¶

• Model integration incomplete: complete the handoff; do not bypass the gate.
• Version/tag mismatch: correct the versioned commit and use a new appropriate tag; never overwrite a published version.
• Missing publisher: check the exact repository owner, workflow filename and environment in the correct index's account settings.
• Existing distribution: investigate prior upload status. Versioned distributions must not be silently replaced.

GitHub action references are pinned to reviewed commits. Dependabot proposes action updates monthly. Bayesian runtime dependency updates require their own numerical/diagnostic qualification rather than automatic version bumps.