Release Checklist

Use this checklist before publishing a v4 release.

Required Checks

Run the default and full test routes:

python3 build.py test
python3 build.py test full

Run package checks:

cargo package --manifest-path sedsnet_macros/Cargo.toml --no-verify
cargo package --no-verify
maturin build

Or run the crate release helper. It defaults to a dry-run and will not upload crates unless --publish is passed:

python3 publish_crates.py
python3 publish_crates.py --publish

CI release jobs use:

python3 publish_crates.py
python3 publish_crates.py --skip-tests --skip-package --publish \
  --ignore-publish-errors

The first command runs the full test route and package dry-runs. Crate publishing and all wheel and sdist jobs wait for those checks to pass. The publish job then reuses the helper without repeating the completed tests and package checks, times out a stuck crates.io upload, and treats upload-side failures as non-fatal. GitHub PyPI trusted publishing uses the pypi environment claim; configure PyPI's trusted publisher to match the repository, release.yml workflow, tag refs, and that environment.

The same helper has explicit PyPI opt-ins:

python3 publish_crates.py --pypi
python3 publish_crates.py --publish-pypi
python3 publish_crates.py --skip-crates --publish-pypi

For local Linux wheel builds without depending on CI, use Docker:

python3 publish_crates.py --skip-crates --skip-tests --docker-wheels --docker-sdist
python3 publish_crates.py --skip-crates --skip-tests --docker-all-wheels --docker-sdist
python3 publish_crates.py --skip-crates --skip-tests --docker-wheels \
  --docker-target x86_64-unknown-linux-gnu \
  --docker-target aarch64-unknown-linux-gnu

The Docker path writes artifacts to dist/ by default. Linux wheels use the maturin manylinux image. Windows wheels default to x86_64-pc-windows-msvc and use rust:bookworm with LLVM/xwin setup because the generic maturin image does not include the MSVC-compatible tools needed by native C dependencies such as zstd-sys. macOS wheels use the same osxcross Docker images as SmartCopy when those images are reachable. On a macOS host, the helper falls back to local maturin macOS builds if the osxcross image cannot be pulled.

Before building or uploading PyPI artifacts, the helper removes older sedsnet wheel and sdist versions from the selected artifact directory. The GitHub release workflow runs the same cleanup after combining its platform artifacts, preventing old versions from producing skip-existing warnings.

• registry.gitlab.rylanswebsite.com/rylan-meilutis/macos-cargo-image/x86_64-apple-darwin:x86_64-apple-darwin
• registry.gitlab.rylanswebsite.com/rylan-meilutis/macos-cargo-image/aarch64-apple-darwin:aarch64-apple-darwin

For PyPI uploads, set MATURIN_PYPI_TOKEN or use the ignored local release config. Install maturin for builds and Twine for uploads if they are not already available:

python3 -m pip install maturin twine

For local PyPI publishing without exporting the token every shell session, run:

python3 build.py maturin-login

That command validates the PyPI token before saving it to .sedsnet-release.toml. The file is ignored by git and read automatically by publish_crates.py --publish-pypi. If no environment token or saved config exists, publish_crates.py --publish-pypi starts the login flow before upload. When --wheel-out already contains wheels or source distributions, --publish-pypi recursively uploads every artifact found there instead of building only the local platform. Uploads fail if any file already exists so a partial or duplicated release is visible; pass --pypi-skip-existing explicitly only when intentionally retrying a release.

CI Releases

Pushing a tag matching v* starts the GitHub release workflow:

• publishes sedsnet_macros and then SEDSnet to crates.io using CARGO_REGISTRY_TOKEN
• builds PyPI wheels for Linux, macOS, and Windows
• builds an sdist
• publishes all Python artifacts to PyPI using trusted publishing

GitHub PyPI publishing expects the project to be configured as a PyPI trusted publisher for the release workflow.

The GitLab pipeline also has tag-gated release jobs for Linux-only self-hosted runners:

• crates.io publishing uses CARGO_REGISTRY_TOKEN
• Linux wheels and sdist build inside Docker images
• Windows win_amd64 cross wheels build in Docker by default
• macOS cross wheels build in Docker by default using the SmartCopy osxcross images
• PyPI publishing uses MATURIN_PYPI_TOKEN

Release upload jobs tolerate already-published crate or PyPI versions. The pipeline should fail for test failures or release artifact build failures, not for rerunning an upload after artifacts have already reached crates.io or PyPI.

If the macOS cross images are unavailable to a GitLab instance, disable the macos-cross-wheels job or replace MACOS_IMAGE with an equivalent osxcross image.

SEDSnet depends on sedsnet_macros through a versioned path dependency. Publish order matters:

1. Publish sedsnet_macros.
2. Wait for crates.io to index it.
3. Package and publish SEDSnet.

The main crate package check fails with no matching package named sedsnet_macros found until the macro crate is published and indexed.

Documentation

Crates.io uses the top-level README.md. Keep it accurate and include links to:

• docs.rs API documentation
• the project wiki or docs/wiki/Home.md
• CHANGELOG.md

For each release, add an entry to CHANGELOG.md, update the README's Recent changelog milestones, and update docs/wiki/Changelogs.md and any affected usage/reference pages. Keep the README introduction version-independent: do not add a “Current stable release” paragraph. Release versions belong in the changelog, milestones, and pinned build examples. Verify pinned CMake examples in README, Build-and-Configure, and Usage-C-Cpp together. Run python3 -m unittest discover -s tests -p test_ci_release_contracts.py to check these release-documentation requirements.

The wiki source lives in docs/wiki. If external wiki repos are used, sync with:

python3 docs/sync_wiki.py

Version Metadata

For every main-crate release, update or verify these files together:

• Cargo.toml
• README.md
• CHANGELOG.md
• docs/wiki/Changelogs.md

Update sedsnet_macros/Cargo.toml only when the macro crate itself changed and needs a new published version. The main crate can continue depending on an already-published macro-crate version.

pyproject.toml declares dynamic = ["version"]; maturin and the release script read the Python package version from the root Cargo package version.

Verify publication

A green workflow is not proof that packages were uploaded: upload jobs can tolerate errors. Check the exact version on crates.io and PyPI and inspect upload logs before announcing publication. If an upload failed, correct authentication or publisher settings and retry the missing artifacts; do not move an existing release tag.

Final Sanity

Before tagging:

git diff --check
git status --short

The working tree should be clean after the release commit.