Skip to content

RELEASE.md

Latest commit

 

History

History
154 lines (118 loc) · 7.35 KB

RELEASE.md

File metadata and controls

154 lines (118 loc) · 7.35 KB
Raw

Releasing PyNetDesign

This project uses setuptools_scm, so the package version is derived from Git tags. Use strict semantic version tags of the form vX.Y.Z (for example v1.0.1). Any commit that is not exactly on a tag resolves to a development version such as 1.0.1.dev3+g1a2b3c4.

Versioning rules

  • Tags must match vMAJOR.MINOR.PATCH exactly. Pre-release and metadata suffixes are rejected by CI.
  • A release tag must point at a commit contained in main. Tags created on other branches are rejected during validation.
  • Development happens on dev; dev is merged into main through a pull request, and the tag is placed on the resulting merge commit on main.

Standard release flow

  1. Make sure dev is green and up to date with main.

  2. Update CHANGELOG.md: move the relevant ## [Unreleased] entries into a new ## [vX.Y.Z] - YYYY-MM-DD section and add the comparison links at the bottom.

  3. Update .zenodo.json: set version to the new release and refresh description with the release highlights.

  4. Open and merge the dev → main pull request.

  5. Tag the merge commit on main and push the tag:

    git checkout main
git pull
git tag -a vX.Y.Z -m "PyNetDesign vX.Y.Z"
git push origin vX.Y.Z

    Pushing the tag also publishes the documentation of the release; see Documentation.

  6. Verify the version resolves correctly before publishing:

    git describe --tags          # -> vX.Y.Z
python -m build              # -> dist/pynetdesign-X.Y.Z.tar.gz

  7. Publish the GitHub Release for that tag, using the new CHANGELOG.md section as the release body.

  8. Merge main back into dev so that dev contains the tag in its history and setuptools_scm resolves a sensible development version there.

Continuous integration

Workflow Trigger What it does
pytest.yml push / PR on main, dev Runs pytest pytests/ on Python 3.9-3.12
validate-zenodo.yml push / PR on main, dev; reusable Validates .zenodo.json against the Zenodo schema
validate-tag.yml reusable only Enforces strict semver and that the tag is contained in main
release-on-published.yml GitHub Release published Validates the tag, validates the Zenodo metadata, then builds and checks the distributions
docs.yml push on main, dev; workflow_dispatch Builds the HTML and PDF documentation; runs on main deploy it to GitHub Pages and check the version the live site serves
push-tag.yml push of a v* tag Validates the tag, then starts a docs.yml run on main that builds and deploys the documentation of the tag

release-on-published.yml also accepts a workflow_dispatch with a tag input, so a release can be re-validated without republishing it.

Notes:

  • Zenodo metadata validation must pass before the package build starts.
  • Tag validation is shared through validate-tag.yml, so the same rules apply to every workflow that acts on a tag.
  • PyNetDesign is not published to PyPI. Installation is from source; see README.md.

Documentation

The documentation is published to GitHub Pages at https://danikiev.github.io/PyNetDesign/. Only docs.yml runs on main deploy it: a push to main publishes a development version, and pushing a release tag starts a run on main that builds the tag and publishes it. Every deployment ends by reading the version back from the live site, and fails if it differs.

A release is deployed by a run on main, not by a run on the tag, because GitHub Pages ignores a deployment made from a tag when main has already deployed the same commit, and still reports it as successful (actions/deploy-pages#383). The release tag always sits on a merge commit that main deployed when it was merged.

Deploying the docs manually

Use this when the live site shows the wrong version, for example when the Check the deployed version step of a Docs run failed, or to republish a release:

  1. On GitHub, open Actions → Docs → Run workflow.
  2. Keep Use workflow from at main. Runs on any other branch or on a tag build the documentation but do not deploy it.
  3. Set ref to the release tag, for example refs/tags/v1.1.0, or leave it empty to publish the current main.
  4. Click Run workflow. The run builds the documentation from ref, checks that the documentation of a tag carries its version, deploys it and checks the live site.

The same from a terminal, with the GitHub CLI:

gh workflow run docs.yml --ref main -f ref=refs/tags/v1.1.0

To see which version the live site serves (the query string bypasses the CDN cache):

curl -s "https://danikiev.github.io/PyNetDesign/_static/documentation_options.js?$(date +%s)" | grep VERSION

Zenodo

The repository is archived on Zenodo through the GitHub integration.

One-time integration setup

  1. Sign in to https://zenodo.org (test the flow on https://sandbox.zenodo.org first if you prefer).
  2. In Zenodo's GitHub settings, enable the PyNetDesign repository.
  3. Confirm the repository has a valid .zenodo.json — validate-zenodo.yml checks this on every push.

Important: v1.0.0 was deposited manually before the GitHub integration existed. The integration was therefore enabled only after the v1.0.0 GitHub release was published, so that Zenodo would not mint a second, duplicate DOI for that version. The first integration-created deposit is v1.0.1, which starts a new concept DOI.

Per-release checklist

  1. Before tagging — update .zenodo.json (version, description, keywords, creators, related_identifiers as needed) and make sure LICENSE and README.md are consistent with the release notes.
  2. Create the release — push the vX.Y.Z tag, then publish the GitHub Release with the highlights from CHANGELOG.md.
  3. Validate the deposition — confirm Zenodo auto-created a new versioned deposition from the GitHub release, and check the title, version, creators, ORCID, license and description in the Zenodo UI. Verify the source archive is attached.
  4. Communicate the DOIs — copy the version DOI and the concept DOI into the release notes, README.md and docs/source/citing.rst. The concept DOI always resolves to the latest version; the version DOI pins one release.
  5. Post-release verification — open the DOI link, check that the citation metadata resolves, and confirm the new version appears under the concept record.

Linking the pre-integration record

Because the manual v1.0.0 deposit and the integration-created records are separate Zenodo lineages, they must be cross-linked by hand in both directions:

  • Forward, in the repository: .zenodo.json carries a related_identifiers entry with relation isNewVersionOf pointing at 10.5281/zenodo.14945917. Zenodo honours this on every deposit, so it persists across releases.
  • Backward, on Zenodo: open record 14945917, choose Edit, add a related identifier with relation isPreviousVersionOf pointing at the new version DOI, and publish. This is a metadata-only edit and preserves the existing DOI.