Releasing pvtlib¶
Each release is a git tag MAJOR.MINOR.PATCH without a prefix, for example 1.17.0, the same
files on PyPI, and a GitHub release that lists the changes and
carries those files. Releases are made by the workflow
release.yml, started by hand. Nothing is released by merging
or pushing.
Version numbers¶
Versions follow semantic versioning:
Part |
Increase when |
Example |
|---|---|---|
PATCH |
a fix that does not change the documented behaviour or any calculated result |
1.16.1 → 1.16.2 |
MINOR |
new functionality that existing code keeps working with |
1.16.1 → 1.17.0 |
MAJOR |
a change that breaks existing code or the documented behaviour |
1.16.1 → 2.0.0 |
Project rule: a change to calculated results - a new or corrected correlation, constant, unit handling or reference data - is at least MINOR, even when it is a correction, so it never arrives unnoticed in a patch update. Dropping support for a Python version is also at least MINOR. Describe the effect on results in the pull request; the release notes are generated from the pull request titles.
The version is not written anywhere in the code or in pyproject.toml.
setuptools-scm reads it from the git tags when the
package is built or installed, and writes it to pvtlib/_version.py (not committed).
pvtlib.__version__ reports it:
Installed from |
|
|---|---|
PyPI, or the tag |
|
a commit after |
a development version such as |
a source tree that was never installed |
|
Building or installing from a git checkout needs the tags: a shallow clone without them gets a
version such as 0.1.dev1+g1a2b3c4. An editable install (pip install -e .) records the version
when it is installed; after pulling new commits or tags, run pip install -e . again.
tests/test_version.py fails while the installed metadata and pvtlib.__version__ differ.
Making a release¶
Merge what should be in the release into
main, with the checks green.On GitHub, open Actions → Release → Run workflow, keep the branch
main, and choose which part of the version to increase (patch,minorormajor). The new version is the highest existingMAJOR.MINOR.PATCHtag with that part increased.The workflow runs on the commit
mainpointed at when it was started:prepare - stops unless the run is on
main; works out the version (tools/release_version.py) and stops if that tag already exists or PyPI already has that version.test - the complete test workflow,
tests.yml.build - tags the commit locally (the tag is not pushed), builds the sdist and the wheel once, checks that both carry the new version and pass
twine check --strict, installs each in a clean virtual environment and runs the test suite against the installed package (from a copy oftests/outside the checkout, with a check inside the pytest session thatpvtlibis imported from that environment). Exactly those files are kept, with their SHA-256 in a manifest.publish - waits for approval in the environment
pypi(the only approval in the run). It checks the files against the manifest and what PyPI already has, creates the tag at the tested commit, uploads the files to PyPI with Trusted Publishing (no token; PyPI also stores a signed attestation of where each file was built), and then checks that PyPI holds exactly those files with the same SHA-256.github-release - creates the GitHub release for the tag, with notes generated from the merged pull requests and the same files attached.
Edit the release notes on GitHub if the effect on calculated results needs explaining.
Nothing is rebuilt between testing and publishing. If anything fails before the publish job, or
in it before the tag is created, nothing is published and a new run can simply be started.
When a release run fails¶
Use Re-run failed jobs in the same run. Do not use Re-run all jobs; the
preparejob refuses to run in a later attempt, because it would work out a different version.A re-run accepts a tag or PyPI files left by an earlier attempt of the same run only if they match exactly: the tag must point at the same commit, and every file already on PyPI must have the SHA-256 in the manifest and an attestation from this repository’s
release.ymlin the environmentpypi. Missing files are then uploaded; existing GitHub release assets must match the manifest.Never start a new run for a version that already has files on PyPI. PyPI never accepts a file name twice, even after it is deleted, so a mistake in a published version is corrected with a new version.
Never move or delete a published tag.
The artifacts of a run are kept for 90 days, so a failed run must be completed within that time.
One-time repository setup¶
These are settings made once by a repository administrator.
Environment - Settings → Environments: create
pypi, add Required reviewers, and under Deployment branches and tags choose Selected branches and tags with onlymain. Without reviewers, the workflow does not wait for approval before tagging and publishing.Trusted publisher - on pypi.org, pvtlib → Manage → Publishing: add a GitHub trusted publisher with owner
equinor, repositorypvtlib, workflowrelease.ymland environmentpypi. No PyPI token is stored in the repository.Protect release tags (optional) - Settings → Rules → Rulesets → New tag ruleset, target
refs/tags/[0-9]*, with Restrict updates and Restrict deletions, so a published tag cannot be moved or removed. Do not enable Restrict creations unless the workflow is allowed to bypass it, as the workflow creates the tag.
Python versions¶
pvtlib supports the Python versions listed in requires-python and the classifiers in
pyproject.toml. The test workflow runs on all of them. When a Python version is dropped, pip on
that Python keeps installing the last release that supported it.