Update versioning scheme#99
Conversation
Updated version bump workflow to include 'dev' option and handle dev versioning logic.
teutoburg
added
enhancement
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #99 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 2 2
Lines 7 7
=========================================
Hits 7 7 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Added a verification step to ensure the release tag matches the package version before publishing to PyPI.
This was created by Claude Fable 5 to provide a reference for the version scheme changes.
This workflow automates the process of preparing a release by bumping the package version, creating a draft GitHub release, and then bumping the version to the next development version.
|
|
||
| ## 9. Situation: backport to a released series | ||
| Only needed once a breaking change has landed on `main` (otherwise: just release `main` as the next minor). | ||
| Fixes land on `main` **first**, then get cherry-picked out — never developed only on the maintenance branch. |
There was a problem hiding this comment.
You could also create the branch for the fix from an earlier commit (e.g. the commit that broke something), then you might be able to merge the fix into both main and the release branch directly (without having to cherry-pick).
| `git branch v2.x v2.1.0 && git push origin v2.x` (branching from a later `main` commit would smuggle unreleased feature work into a "critical patch") | ||
| - [ ] Verify CI workflow triggers cover the branch (add `"v*.x"` to the `branches:` lists if not already glob-covered) | ||
| - [ ] Repoint data-download fallbacks from `main` to `v2.x` (e.g. the pooch fallback-branch constant), so source installs from the branch fetch series-matching data | ||
| - [ ] Note the support window for the old series in README/docs |
There was a problem hiding this comment.
I'm struggling a bit with the 'verbosity' of the document. Such a check-list is perhaps a good way to make it more concrete, but this is the only one in the document.
Maybe you could organize the document around the different 'situations', and what to do in those situations with a checklist. That is, have a checklist also for the other situations.
There was a problem hiding this comment.
The verbosity here is easily explained by the fact that I didn't write this myself. I should have disclosed the use of AI as I usually do in the PR description. I'm all in favor of rewriting it 👍
hugobuddel
left a comment
hugobuddel
left a comment
There was a problem hiding this comment.
I like it!
Playing the devils advocate a bit / taking this one step further: can we just ditch the entire version in the code and rely only on the git tag? That is, the 'current version' only exists as a git tag, and the version of the installed package is derived from the git checkout. So the version is either a tag or a commit hash. That would do away with all the dev versions (or well, implicit ones, people could still tag them). I feel that that is where most projects are going nowadays.
You'd need to refer to the git history to figure out exactly what version is what, but that is perhaps not such a hassle I think.
You'd need to do something smart with the Changelog though, to get the correct version numbers in there. But I think that is manageable.
| When no rule does what you need, an explicit version is always a legitimate escape hatch. | ||
|
|
||
| ## 2. Poetry rule matrix (empirical, Poetry 2.3.0) | ||
| What `poetry version <rule>` produces from each phase our scheme visits: |
There was a problem hiding this comment.
This matrix is perhaps a detail that could be more useful at the end of the document. The result is more important than the path (well, not really, but it is good to start with the result).
| - Version numbers change **only on `main`** (or a maintenance branch, §9), and in the normal case **only via CI** (bot commits). | ||
| Never bump versions on feature branches — this is what makes overlapping branches conflict-free. | ||
| - The repo is **always on a `.devN` version** between tags. | ||
| Every tag is immediately followed by a dev-bump commit; the tagged version string never lingers. |
There was a problem hiding this comment.
Yeah that's nice, have the tagged version never linger.
There was a problem hiding this comment.
We technically already had that feature automated, it always bumped to the next prerelease after publishing a tagged version. But now with dev versions instead.
I think what you're describing is often called a "dynamic version [number]" elsewhere. My main issue with it is that I like having a version number written down somewhere (i.e. in the toml file). But I can also see benefits of a dynamic version, so maybe that's just my own inertia. Nevertheless, I think we can keep the version number in the toml for now. We introduced the prerelease scheme some 3 yr ago and only now had an actual need to change things (slightly). So maybe in another 3 yr we might move to dynamic versions, who knows 🙂 Either way, you approved it, so I assume it's "good enough" for now. |
|
Yeah I understand that feeling. So this is good. |
2 participants
TLDR
We've been using prerelease version numbers (
a0etc.) in place of dev version numbers for the last 3 yr. This PR fixes that and also introduces an updated release workflow.Why?
Our use of prerelease numbers was not only conceptually questionable, but confuses e.g.
pooch(rightfully so, nothing wrong with that package, everything wrong with our version numbers).What??
See the markdown doc added as part of this PR, which also serves as general documentation on our version numbering going forward. Hence in a separate doc and not the PR body.