Versioning and releases
gleplot follows Semantic Versioning 2.0. Releases are
cut by Python Semantic Release
from conventional commit messages on
main, while the maintainer has the Release workflow enabled.
Stability
6.0 is gleplot’s first stable release. From 6.0 on, a public name or a default changes only in a major release, and so does the GLE a script emits when that output was correct. A minor adds capability, and a patch changes emitted GLE only to correct output that was wrong.
Gathering a major
To gather breaking changes into one major, the maintainer pauses releases by
disabling the Release workflow. While it is paused, commits still land on
main with their usual types, breaking (!) changes included, and nothing is
published. Re-enabling the workflow does not run it: the maintainer then runs
it by hand (Actions → Release → Run workflow, auto), and that run cuts
one release from every commit since the last tag, a single major if any of
them is breaking.
Commit messages
<type>(<optional scope>): <subject>
<optional body>
<optional footer>
Type |
Version bump |
|---|---|
|
minor |
|
patch |
|
major |
|
none |
Examples:
git commit -m "feat: add support for histogram plots"
git commit -m "fix(writer): handle edge case in scale auto"
git commit -m "docs: update installation instructions"
A breaking change:
feat!: remove deprecated plot_old() function
BREAKING CHANGE: plot_old() has been removed. Use plot() instead.
The bump rules live in pyproject.toml under
[tool.semantic_release.commit_parser_options].
How a release happens
A push to
mainruns the Tests workflow. Pull requests never cut a release.When Tests succeed, that commit is still the tip of
main, and the maintainer has not paused releases, the Release workflow (.github/workflows/release.yml) looks at the commits since the last tag.If they warrant a bump, python-semantic-release updates the version, prepends release notes to
docs/CHANGELOG.md, builds the sdist and wheel, pushes the release commit andvX.Y.Ztag, and creates a GitHub Release with the artifacts attached.If the repository variable
PYPI_PUBLISHistrue, a separate job uploads to PyPI through Trusted Publishing; see Publishing to PyPI.
The version is stored in two places, which the release keeps in sync:
project.version in pyproject.toml and __version__ in
src/gleplot/__init__.py. Do not edit either by hand.
Previewing and forcing a release
Preview what the next release would be, without writing anything:
pip install -e ".[dev]"
semantic-release version --noop
To release by hand, go to Actions → Release → Run workflow and choose
auto or force major, minor or patch.
Maintainers can also release locally, which is rarely needed:
semantic-release version
git push origin main --follow-tags
Publishing to PyPI
Each release attaches the sdist and wheel to its GitHub Release. Upload to PyPI is off until a maintainer enables it:
Register the gleplot project on PyPI. The workflow uploads to PyPI only, not TestPyPI.
Add a Trusted Publisher on PyPI for this repository, workflow file
release.yml, environmentpypi.Create a GitHub Environment named
pypi(approval rules are recommended).Set the repository variable
PYPI_PUBLISHtotrue.
The Publish to PyPI job authenticates through OIDC
(pypa/gh-action-pypi-publish), so no long-lived API token is stored in the
repository.
To check a build locally:
pip install build twine
python -m build
twine check dist/*
If the Release workflow does nothing
Releases are paused: the maintainer has disabled the workflow to gather a major (see Gathering a major).
No commit since the last tag has a bumping type.
docs:,test:,ci:and the like never release on their own.A newer commit reached
mainbefore Tests finished; that commit’s run cuts the release instead.Tests failed.