diff --git a/AGENTS.md b/AGENTS.md index 9df9b0b5..d49d4381 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -72,8 +72,15 @@ uv run sphinx-build -b html docs dist/docs # code with the pipe's, so a failing run reads as a passing one. The # classified summary it prints is the source for the release notes' behavior # claims, including the count of changed names that are Latin-only. -# 2. Bump VERSION in nameparser/_version.py (and the `version:` field in CITATION.cff to match) -# For a pre-release, set PRE_RELEASE = 'rc1' (etc.) — __version__ joins it without a dot ('2.0.0rc1'); '' means final +# 2. Clear PRE_RELEASE in nameparser/_version.py — it carries 'dev' through the +# cycle (see step 9), so releasing is setting it to ''. VERSION should already +# be the version you are shipping; bump it here only if step 9 was skipped. +# For an RC, set PRE_RELEASE = 'rc1' (etc.) instead — __version__ joins it +# without a dot ('2.0.0rc1'). +# Also set the `version:` field in CITATION.cff to this release. It is the ONE +# version string that does NOT track the tree: it names the last citable +# released artifact, so it lags on purpose for the whole cycle and catches up +# here. Nothing checks this — no test, no CI — so it is on you. # 3. Stamp "Unreleased" → "X.Y.Z - Month DD, YYYY" in docs/release_log.rst # 4. git commit + git tag -a vX.Y.Z -m "Release X.Y.Z" # 5. git push origin master && git push origin vX.Y.Z ← tag must be pushed separately before gh release create @@ -112,6 +119,19 @@ uv run sphinx-build -b html docs dist/docs # vocabulary (maiden markers, ambiguous acronyms). An alternation # matching no key fails as undeclared -- add it, or record it in # _NOT_A_VOCABULARY_COPY if it copies nothing. +# 9. Open the next cycle's VERSION: bump VERSION in nameparser/_version.py to +# the minor now being worked, and set PRE_RELEASE = 'dev'. The tree then says +# what it is building rather than what it last shipped -- docs/conf.py reads +# __version__ directly, so Read the Docs' "latest" is otherwise stuck on the +# previous release for the whole cycle. +# It also restores the differential harness's version tell: with the tree and +# the baseline wheel both reporting the same release, only the __file__ path +# distinguishes them, which is the weak state test_tell_rejects_a_module_ +# loaded_from_the_checkout documents. A dev tree differs on both halves. +# 'dev' normalizes to X.Y.0.dev0 -- above the last release, below the one it +# precedes -- so an install from master can never masquerade as the release. +# Leave CITATION.cff alone: it names the last RELEASED version and is meant +# to lag until step 2 of the next release. ``` Enable debug logging to see the parser's internal decisions: diff --git a/nameparser/_version.py b/nameparser/_version.py index 840df8a4..8ef1eef7 100644 --- a/nameparser/_version.py +++ b/nameparser/_version.py @@ -1,9 +1,19 @@ #: Release version parts (major, minor, micro). VERSION stays a pure #: numeric tuple so `nameparser.VERSION >= (2, 0, 0)` keeps working; the #: pre-release segment lives separately. -VERSION = (2, 1, 0) +#: +#: Bumped when a cycle OPENS, not when it ships, so the tree says what +#: it is building. Note the cost of the tuple being purely numeric: it +#: cannot carry the dev marker, so `VERSION >= (2, 2, 0)` is already +#: true here while 2.2.0 is unreleased. Compare `__version__` instead +#: where that distinction matters. +VERSION = (2, 2, 0) #: PEP 440 pre-release/dev segment appended to the numeric version, or #: "" for a final release. Joined WITHOUT a dot ("2.0.0rc1", not #: "2.0.0.rc1"); setuptools reads __version__ as the package version. -PRE_RELEASE = "" +#: +#: "dev" through the cycle, cleared at release. It normalizes to +#: 2.2.0.dev0, which sorts above 2.1.0 and BELOW 2.2.0, so an install +#: from master can never masquerade as the release it precedes. +PRE_RELEASE = "dev" __version__ = ".".join(map(str, VERSION)) + PRE_RELEASE