Skip to content

chore: make the version single-sourced and enforce consistency - #27

Merged
arrase merged 1 commit into
mainfrom
chore/version-alignment
Sep 29, 2026
Merged

arrase merged 1 commit into
mainfrom
chore/version-alignment

Conversation

@arrase

@arrase arrase commented Sep 29, 2026

Copy link
Copy Markdown
Owner

Problem

The version is declared only in pyproject.toml, but tags and releases were created by hand. The two disagreed across several releases:

Tag pyproject.toml declared
v0.2.6 0.1.0
v0.2.9 0.2.8
v0.3.0 0.3.0

v0.2.9 shipped a package whose metadata said 0.2.8. Nothing caught it.

Changes

Single source of truth. eloquent_notes.__version__ is read from the installed distribution metadata via importlib.metadata, so the runtime reports what is actually installed rather than a second constant to maintain. An uninstalled source checkout falls back to 0.0.0+unknown, and a test fails if that fallback is ever what runs — so the fallback cannot hide a real problem.

eloquent-notes --version prints it:

$ eloquent-notes --version
eloquent-notes 0.3.0

tests/test_version.py asserts four invariants:

  • the pyproject.toml version is valid MAJOR.MINOR.PATCH
  • the package exposes a real installed version, not the fallback
  • pyproject.toml and the installed metadata agree
  • the newest v* tag equals v<pyproject version>

The last one is the check that would have caught v0.2.9: it fails if a release is tagged before the version bump is merged. It skips when the checkout has no version tags, so shallow clones and source tarballs are unaffected.

I verified it by simulating the v0.2.9 drift locally — setting pyproject.toml back to 0.2.8 with the v0.3.0 tag present fails both the metadata and the tag check.

docs/releasing.md documents the procedure, including the ordering constraint (merge the bump, then tag), and is wired into AGENTS.md and the mkdocs nav.

Scope

No behavioural change to recording, the pipeline, or note output. v0.3.0 is already released and its tag matches pyproject.toml, so this lands after it.

169 tests pass, mypy and ruff clean, mkdocs build --strict clean.

The version was declared only in pyproject.toml, while tags and releases
were created by hand. v0.2.9 shipped with pyproject still declaring 0.2.8,
and v0.2.6 declared 0.1.0, so the tag and the package disagreed across
several releases.

Expose eloquent_notes.__version__ from the installed distribution metadata
and add an `eloquent-notes --version` flag, so the runtime reports what is
actually installed rather than a second constant to keep in sync. Add
tests/test_version.py asserting the pyproject version is valid semver, the
package exposes a real installed version, pyproject matches the installed
metadata, and the newest v* tag equals v<pyproject version>. The last
check fails if a release is tagged before the bump is merged, which is the
exact failure mode that produced v0.2.9; it skips when the checkout has no
tags so shallow clones still work.

Document the release procedure in docs/releasing.md, including the ordering
constraint, and reference it from AGENTS.md and the docs nav.
@sonarqubecloud

Copy link
Copy Markdown

Quality Gate Failed Quality Gate failed

Failed conditions
71.4% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud

@arrase
arrase merged commit 667791d into main Sep 29, 2026
1 of 2 checks passed
@arrase
arrase deleted the chore/version-alignment branch September 29, 2026 20:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant