Skip to content

ci+docs: assert release version matches tag; clarify description; add macOS CI - #3

Merged
gagreene merged 1 commit into
masterfrom
build/pypi_readiness_part2
Aug 24, 2026
Merged

ci+docs: assert release version matches tag; clarify description; add macOS CI#3
gagreene merged 1 commit into
masterfrom
build/pypi_readiness_part2

Conversation

@gagreene

Copy link
Copy Markdown
Owner

Summary

Executes Phase 7 (docs/pypi-publication-readiness-plan.md, local reference doc, not
part of this diff) of the PyPI publication readiness effort: rehearses the full
Release → Trusted Publishing → TestPyPI pipeline end to end, and fixes what that
rehearsal found. Small diff — 4 files, mostly CI config.

Full test suite: 114/114 passing.

What changed

  • Clarified the package description. pyproject.toml's description field ("Fire
    behavior calculations for surface and crown fires") read as vague once it was actually
    visible on a rendered TestPyPI project page. Reworded to "Compute flame characteristics
    (length, height, tilt, residence time, depth, and mid-flame wind speed) for surface and
    crown fires," and aligned README.md's opening paragraph to match.
  • Added a version-assertion safety net to the release workflow. While rehearsing,
    a local sanity check briefly showed an unexpected dev-version instead of the tagged
    release version — root-caused to a stale local build cache, not a real hatch-vcs bug
    (confirmed directly against setuptools_scm.get_version()). actions/checkout's
    fresh-clone-per-run model makes this specific trigger unlikely in CI, but added a step
    to release.yml's build job that asserts the built package's __version__ matches
    the release tag before validation/smoke-test/publish proceed — cheap insurance, fails
    loudly on any mismatch for any cause.
  • Added macOS CI coverage. The Operating System :: OS Independent classifier
    (pre-existing) had never actually been verified — CI only covered Linux and Windows.
    Added a macos-latest + Python 3.12 leg to tests.yml's matrix, same pattern as the
    existing Windows leg. No macOS-specific code exists in the package, and macOS shares
    Windows's spawn multiprocessing default (unlike Linux's fork), which the package
    was already written to be compatible with.

Rehearsal results (not part of this diff, but why these changes exist)

  • v0.1.1rc1 tagged and published to TestPyPI successfully — proved the Trusted
    Publishing pipeline works.
  • Inspecting the rendered project page is what surfaced the vague-description issue
    above.
  • v0.1.1rc2 (this branch's tip) published to TestPyPI with the fix; verified via the
    TestPyPI JSON API: classifiers, all 5 project URLs, License-Expression: MIT,
    corrected summary, Requires-Python >=3.11, and exactly one non-extra Requires-Dist
    all correct.
  • Installed flame-components==0.1.1rc2 from TestPyPI into a fresh, isolated
    environment (NumPy resolved from real PyPI) and ran the package smoke test from
    outside the repo — passed.

Note on the version-assertion step

It won't have been exercised by the TestPyPI rehearsal itself — GitHub only runs
release-triggered workflows using the default branch's copy of the workflow file, and
this branch wasn't merged yet when the rc1/rc2 rehearsals ran. It'll be live for the
real v0.1.1 release once this merges.

Not in this PR

Phase 8 (the real production release: merge → tag v0.1.1 → GitHub Release → PyPI
publish → verification) and Phase 9 (FuelAnalyst downstream adoption) are next, after
this merges.

Test plan

  • uv run pytest tests/ -v — 114/114 pass
  • Verified the version-assertion logic locally (both match and deliberate-mismatch
    paths) before trusting it in CI
  • v0.1.1rc1 and v0.1.1rc2 both published to TestPyPI and verified (metadata via
    JSON API, README rendering confirmed visually, clean-install + smoke test passed)

… macOS CI

Three unrelated changes made while rehearsing Phase 7 (TestPyPI) against
v0.1.1rc1, bundled together since none were committed yet:

1. Reworded the vague pyproject.toml `description` ("Fire behavior
   calculations for surface and crown fires") to specifically name what
   the package computes: "Compute flame characteristics (length, height,
   tilt, residence time, depth, and mid-flame wind speed) for surface and
   crown fires." Aligned README.md's opening paragraph to match
   ("flame characteristics" instead of "fire behavior metrics").

2. While sanity-checking the v0.1.1rc1 tag locally, an initial check
   showed the wrong version (0.1.1.dev11+g<hash> instead of 0.1.1rc1).
   Root-caused to a stale local uv build cache (re-checking out an
   already-built commit changes no file content, so uv reused a cached
   pre-tag build) -- not a real hatch-vcs bug; confirmed via
   `setuptools_scm.get_version()` directly and a cache-cleared rebuild,
   both correctly resolving 0.1.1rc1. `actions/checkout`'s fresh-clone
   model makes this unlikely in CI, but added a version-assertion step to
   release.yml's build job anyway: compares the built __version__ against
   the release tag (GITHUB_REF_NAME, "v" stripped) and fails loudly on any
   mismatch, for any cause, before validation/smoke-test/publish proceed.
   Verified both the match and deliberate-mismatch paths locally first.

3. Added a macos-latest + Python 3.12 leg to tests.yml's matrix, the same
   way as the existing Windows leg. The "Operating System :: OS
   Independent" classifier (pre-dating this readiness effort) was an
   unverified claim -- no macOS CI coverage existed at all. No
   macOS-specific code exists in the package, and macOS shares Windows's
   "spawn" multiprocessing default (unlike Linux's "fork"), so this also
   exercises that code path on a second platform.

The description change means v0.1.1rc1's already-published TestPyPI page
is now stale -- superseded by a new v0.1.1rc2 tag/rehearsal rather than
overwriting the uploaded rc1 (PyPI/TestPyPI versions are immutable).

Full suite verified: 114/114 pass.
@gagreene
gagreene merged commit 0e6273d into master Aug 24, 2026
10 checks passed
@gagreene
gagreene deleted the build/pypi_readiness_part2 branch August 25, 2026 00:28
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