[FEATURE] Branching strategy Phase 2.A - version computing & baselining (merge conflict resolution) by lowlydba · Pull Request #534 · OvertureMaps/schema

John McCall (lowlydba) · 2026-05-21T16:35:56Z

Major change release plan

Not applicable — this PR does not introduce a MAJOR schema change.

Description

Part of the branching strategy rollout — this is Phase 2.A (#508): establishes package version baselines and the CI plumbing that later phases will publish with.

Nothing is published anywhere by this PR — it only computes and logs what versions would be used.

What this adds:

Every package pinned to a static baseline version in pyproject.toml (overture-schema at 1.17.1, others at 0.1.1), replacing the old __about__.py-driven dynamic versioning.
compute-version: a composite action that computes the PEP 440 version a package would get for a given branch context (vnext, main, or main-bump).
code-artifact: a composite action for CodeArtifact auth, replacing the old shell script.
compute-versions-dry-run: a CI workflow that logs computed versions on every push to main/vnext (and on relevant PRs) — visibility only, nothing is built or published (yet)

What's still to come (out of scope here):

Phase 2.B (#533): decide + implement when a main merge actually cuts a release.
Phase 3 (#509): the real publish workflows (CodeArtifact dev builds, patch builds, public PyPI releases) that will call compute-version

See the updated roadmap table in CONTRIBUTING.md for the full phase-by-phase status.

Additional update in this PR iteration:

Resolved merge conflicts by merging latest main into this branch (picked up upstream cleanup/removal of obsolete gers/examples/python content).
Fixed a bug where compute-version hard-failed instead of falling back when a package had never been published.
Fixed a bug where compute-version regressed a package's baseline patch (from pyproject.toml) back to .0 instead of using it as a floor.

Testing

Ran repository validation with make check. Result: 1993 passed.
Verified compute-versions-dry-run end-to-end in CI (successful run) and locally with act for both workflow_dispatch and pull_request events.
Verified the compute-version version-resolution fixes with synthetic test cases (both main and vnext contexts).
Ran final automated validation (Code Review + CodeQL); CodeQL reported no alerts.

Checklist

Add relevant examples.
Add relevant counterexamples.
Update any counterexamples that became obsolete. For example, if a counterexample uses property A but is not intended to test property A's validity, and you made a schema change that invalidates property A in that counterexample, fix the counterexample to align it with your schema change.
Update in-schema documentation using plain English written in complete sentences, if an update is required.
Update Docusaurus documentation, if an update is required.
Review change with Overture technical writer to ensure any advanced documentation needs will be taken care of, unless the change is trivial and would not affect the documentation.

Enforce LF storage in the repository via .gitattributes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: John McCall <john@overturemaps.org>

github-actions · 2026-05-21T16:37:41Z

🗺️ Schema reference docs preview is live!


🌍 Preview	https://staging.overturemaps.org/schema/pr/534/schema/index.html
🕐 Updated	Jul 08, 2026 20:02 UTC
📝 Commit	964748e
🔧 env SCHEMA_PREVIEW	`true`

Note

♻️ This preview updates automatically with each push to this PR.

Copilot

Pull request overview

Phase 2.A of the branching strategy: move Python packages to static baseline versions in pyproject.toml, introduce reusable CI building blocks for CodeArtifact auth and version computation, and add a dry-run workflow to surface what versions would be published on main / vnext.

Changes:

Baselined package versions in pyproject.toml and updated __about__.py modules to read runtime version from installed package metadata.
Added composite actions for CodeArtifact credentials and branch-context-aware version computation, and migrated workflows off the legacy code-artifact.sh script.
Added a “compute versions (dry run)” workflow plus line-ending normalization via .gitattributes.

Reviewed changes

Copilot reviewed 34 out of 50 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
uv.lock	Updates lock metadata and adds editable package version fields.
reference/counterexamples/transportation/segment/road/bad-road-destinations.yaml	Line ending/format normalization.
reference/counterexamples/divisions/division_area/bad-missing-is-land.yaml	Line ending/format normalization.
packages/overture-schema/src/overture/schema/about.py	Switches to runtime metadata-based version lookup.
packages/overture-schema/pyproject.toml	Replaces dynamic Hatch versioning with a static baseline version.
packages/overture-schema-transportation-theme/src/overture/schema/transportation/about.py	Runtime metadata-based version lookup.
packages/overture-schema-transportation-theme/pyproject.toml	Static baseline version.
packages/overture-schema-system/src/overture/schema/system/about.py	Runtime metadata-based version lookup.
packages/overture-schema-system/pyproject.toml	Static baseline version.
packages/overture-schema-places-theme/src/overture/schema/places/about.py	Runtime metadata-based version lookup.
packages/overture-schema-places-theme/pyproject.toml	Static baseline version.
packages/overture-schema-divisions-theme/src/overture/schema/divisions/about.py	Runtime metadata-based version lookup.
packages/overture-schema-divisions-theme/pyproject.toml	Static baseline version.
packages/overture-schema-common/src/overture/schema/common/about.py	Runtime metadata-based version lookup.
packages/overture-schema-common/pyproject.toml	Static baseline version.
packages/overture-schema-codegen/src/overture/schema/codegen/about.py	Runtime metadata-based version lookup.
packages/overture-schema-codegen/pyproject.toml	Static baseline version.
packages/overture-schema-cli/src/overture/schema/cli/about.py	Runtime metadata-based version lookup.
packages/overture-schema-cli/pyproject.toml	Static baseline version.
packages/overture-schema-buildings-theme/src/overture/schema/buildings/about.py	Runtime metadata-based version lookup.
packages/overture-schema-buildings-theme/pyproject.toml	Static baseline version.
packages/overture-schema-base-theme/src/overture/schema/base/about.py	Runtime metadata-based version lookup.
packages/overture-schema-base-theme/pyproject.toml	Static baseline version.
packages/overture-schema-annex/src/overture/schema/about.py	Runtime metadata-based version lookup.
packages/overture-schema-annex/pyproject.toml	Static baseline version.
packages/overture-schema-addresses-theme/src/overture/schema/addresses/about.py	Runtime metadata-based version lookup.
packages/overture-schema-addresses-theme/pyproject.toml	Static baseline version.
gers/examples/python/utils.py	Line ending normalization; no functional intent changes.
gers/examples/python/tests/utils_test.py	Line ending normalization.
gers/examples/python/tests/test_setup.py	Line ending normalization.
gers/examples/python/tests/match_traces_test.py	Line ending normalization.
gers/examples/python/route_utils.py	Line ending normalization.
gers/examples/python/README.md	Line ending normalization.
gers/examples/python/match_traces.py	Line ending normalization.
gers/examples/python/MATCH_TRACES.md	Line ending normalization.
gers/examples/python/match_classes.py	Line ending normalization.
gers/examples/python/constants.py	Line ending normalization.
gers/examples/python/init.py	Line ending normalization.
counterexamples/transportation/segment/road/bad-road-destinations.yaml	Line ending/format normalization.
counterexamples/divisions/division_area/bad-missing-is-land.yaml	Line ending/format normalization.
CONTRIBUTING.md	Documents Phase 2.A and the dry-run workflow.
.github/workflows/scripts/package-versions.py	Filters package discovery to dirs with `pyproject.toml`.
.github/workflows/scripts/code-artifact.sh	Removes legacy CodeArtifact helper script.
.github/workflows/reusable-check-python-package-versions.yaml	Migrates CodeArtifact auth to composite action.
.github/workflows/publish-python-packages.yaml	Migrates CodeArtifact auth to composite action and updates triggers.
.github/workflows/compute-versions-dry-run.yaml	Adds workflow to compute/log versions per context without publishing.
.github/workflows/check-python-package-versions.yaml	Updates triggers (removes `__about__.py` path trigger).
.github/actions/compute-version/action.yml	New composite action for context-aware version calculation.
.github/actions/code-artifact/action.yml	New composite action to produce CodeArtifact token + index/publish URLs.
.gitattributes	Enforces LF normalization and declares common binary patterns.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Introduce reusable GitHub Actions for CodeArtifact credentials and version computation. Baseline all packages to static versions (overture-schema at 1.17.0, others at 0.1.0). Add dry-run workflow for version visibility. Migrate callers off legacy code-artifact.sh. Closes #508 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: John McCall <john@overturemaps.org>

Eric Godwin (ericgodwin)

A little bit overwhelming of a review, but the concept seems sound.

Victor Schappert (vcschapp) · 2026-05-27T02:49:30Z

19 legacy CRLF files fixed

Good catch, appeals to the pedant in me! I wonder how they escaped my all-seeing eye!?

Victor Schappert (vcschapp)

I think we (or at least I) need to think this through a bit more:

Why remove hatch dynamic versions?

Previously, each package used dynamic = ["version"] with [tool.hatch.version] pointing at an __about__.py file containing a hardcoded string. This meant version bumps required editing source files and committing them — tightly coupling human commits to version identity. The new model separates concerns: <major>.<minor> lives in pyproject.toml (bumped intentionally by humans), while <patch> is computed at build time by CI based on what's already published. __about__.py now reads from installed package metadata at runtime, so it always reflects whatever version was actually stamped during build — no manual sync needed.

The choice of automated version bumps for public PyPI was intentional, the idea being that there should be human intention with an explicit version bump commit to trigger (public) publishing, and that the reason for the publish would be included in the commit message.

Let me give a concrete example of a workflow that I think would have unexpected results in a fully automated model.

Steps:

On May 29, Alice commits a minor change to main, with the intention that it will go out in a schema update just before the June release.
On May 30, Bob commits a second minor change to main with the same intention.

If we do automated patch updates, one of two things will happen.

If they omit the major.minor change from their commits, then both Alice's and Bob's changes are going to be independently and immediately published as patch version bumps.
If they include major.minor changes then both of their changes are going to be independently and immediately published as separate minor version bumps within a day of each other.

Whereas it seems more likely the intention was to combine those changes together into a single explicit minor version release...

- resolve_latest() in compute-version action now distinguishes a benign "no matching version" result from real uv pip compile failures, so the vnext/main fallback paths are reachable again (uv exits non-zero for both cases). - Refactor compute-versions-dry-run.yaml to discover packages/context once and call the compute-version composite action per package via a matrix, removing the duplicated version formula. - Add a pull_request trigger (paths-scoped) to compute-versions-dry-run.yaml so edits to the compute-version/code-artifact actions are smoke-tested; job names get a "(test)" suffix on that trigger to distinguish from real runs. Link to Phase 3 tracking issue (#509). - Regenerate uv.lock to match the pyproject.toml version bumps. - Add UV_LOCKED=1 to the default-resolution check-python-code.yaml matrix cell so a stale uv.lock fails fast, without a dedicated check. - Fix Makefile uv-sync target to surface uv's error output on failure instead of silently swallowing it. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: John McCall <john@overturemaps.org>

…nternal-versions

Route matrix/step-output values through env: vars instead of interpolating them directly into the run: script body. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: John McCall <john@overturemaps.org>

…sions' of https://github.com/OvertureMaps/schema into 508-devops-branching-strategy---phase-2a---internal-versions Signed-off-by: John McCall <john@overturemaps.org>

'main' and 'vnext' contexts previously discarded the seed version's patch component whenever nothing was published yet, hardcoding patch 0 (main) or major.minor.0 (vnext). This regressed packages that had already bumped their pyproject.toml patch (e.g. baselining) back down until CodeArtifact caught up. main now takes max(seed_patch, last_published_patch + 1); vnext falls back to the full seed version instead of major.minor.0. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: John McCall <john@overturemaps.org>

Adds a compact status table (done/next/planned) to the Migration Notes section so the overall branching-strategy rollout is easier to follow, and replaces the 'WIP / Pending' placeholders for Phases 2.B/3/4 with one-line summaries and links to their tracking issues. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: John McCall <john@overturemaps.org>

John McCall (lowlydba) · 2026-07-08T17:45:47Z

@copilot resolve the merge conflicts in this pull request

Copilot · 2026-07-08T17:50:05Z

Copilot resolve the merge conflicts in this pull request

Resolved in commit 964748e by merging origin/main into this branch and fixing the uv.lock merge conflict.

John McCall (lowlydba) · 2026-07-08T21:33:11Z

Apologies for yet another review request Seth Fitzsimmons (@sethfitz) , Eric Godwin (@ericgodwin) - had to fix a merge conflict on the uv.lock file 🙃

chore: add .gitattributes and normalize line endings to LF

bc9441f

Enforce LF storage in the repository via .gitattributes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: John McCall <john@overturemaps.org>

John McCall (lowlydba) linked an issue May 21, 2026 that may be closed by this pull request

[Devops] Branching Strategy - Phase 2.A - Internal versions #508

Open

3 tasks

John McCall (lowlydba) temporarily deployed to staging May 21, 2026 16:37 — with GitHub Actions Inactive

John McCall (lowlydba) force-pushed the 508-devops-branching-strategy---phase-2a---internal-versions branch from 93c890b to 3910756 Compare May 21, 2026 16:37

John McCall (lowlydba) temporarily deployed to staging May 21, 2026 16:39 — with GitHub Actions Inactive

John McCall (lowlydba) force-pushed the 508-devops-branching-strategy---phase-2a---internal-versions branch from 3910756 to 393040a Compare May 21, 2026 16:44

John McCall (lowlydba) temporarily deployed to staging May 21, 2026 16:45 — with GitHub Actions Inactive

John McCall (lowlydba) force-pushed the 508-devops-branching-strategy---phase-2a---internal-versions branch 2 times, most recently from 7318477 to e1abdfe Compare May 21, 2026 16:49

John McCall (lowlydba) added the change type - cosmetic 🌹 Cosmetic change label May 21, 2026

John McCall (lowlydba) temporarily deployed to staging May 21, 2026 16:51 — with GitHub Actions Inactive

John McCall (lowlydba) force-pushed the 508-devops-branching-strategy---phase-2a---internal-versions branch from e1abdfe to d33ed40 Compare May 21, 2026 16:52

John McCall (lowlydba) temporarily deployed to staging May 21, 2026 16:53 — with GitHub Actions Inactive

John McCall (lowlydba) marked this pull request as ready for review May 21, 2026 16:55

John McCall (lowlydba) requested a review from a team as a code owner May 21, 2026 16:55

Copilot AI review requested due to automatic review settings May 21, 2026 16:55

Copilot started reviewing on behalf of John McCall (lowlydba) May 21, 2026 16:56 View session

Copilot AI reviewed May 21, 2026

View reviewed changes

John McCall (lowlydba) force-pushed the 508-devops-branching-strategy---phase-2a---internal-versions branch from d33ed40 to 720291d Compare May 21, 2026 17:02

John McCall (lowlydba) temporarily deployed to staging May 21, 2026 17:04 — with GitHub Actions Inactive

John McCall (lowlydba) mentioned this pull request May 21, 2026

Package-versions existence check produces false positives when CodeArtifact has a local-version build #523

Open

John McCall (lowlydba) requested review from Eric Godwin (ericgodwin), Seth Fitzsimmons (sethfitz) and Victor Schappert (vcschapp) May 21, 2026 17:23

Eric Godwin (ericgodwin) previously approved these changes May 26, 2026

View reviewed changes

Victor Schappert (vcschapp) reviewed May 27, 2026

View reviewed changes

Comment thread .github/workflows/compute-versions-dry-run.yaml Outdated

John McCall (lowlydba) temporarily deployed to staging June 4, 2026 14:12 — with GitHub Actions Inactive

Eric Godwin (ericgodwin) requested a review from Roel Bollens (RoelBollens-TomTom) July 7, 2026 17:11

Seth Fitzsimmons (sethfitz) previously approved these changes Jul 7, 2026

View reviewed changes

John McCall (lowlydba) mentioned this pull request Jul 8, 2026

[CHORE] Drop unused __about__.py files from Python packages #549

Open

John McCall (lowlydba) dismissed stale reviews from Seth Fitzsimmons (sethfitz) and Eric Godwin (ericgodwin) via 28812d4 July 8, 2026 14:23

Merge branch 'main' into 508-devops-branching-strategy---phase-2a---i…

b57ca7f

…nternal-versions

John McCall (lowlydba) temporarily deployed to staging July 8, 2026 14:24 — with GitHub Actions Inactive

John McCall (lowlydba) added 2 commits July 8, 2026 10:28

Merge branch '508-devops-branching-strategy---phase-2a---internal-ver…

5df09e6

…sions' of https://github.com/OvertureMaps/schema into 508-devops-branching-strategy---phase-2a---internal-versions Signed-off-by: John McCall <john@overturemaps.org>

John McCall (lowlydba) changed the title ~~[FEATURE] Branching strategy Phase 2.A - version computing & baselining (merge conflict resolution)~~ [FEATURE] Branching strategy Phase 2.A - version computing & baselining (merge conflict resolution) Jul 8, 2026

John McCall (lowlydba) temporarily deployed to staging July 8, 2026 14:34 — with GitHub Actions Inactive

John McCall (lowlydba) temporarily deployed to staging July 8, 2026 14:39 — with GitHub Actions Inactive

John McCall (lowlydba) requested review from Eric Godwin (ericgodwin) and Seth Fitzsimmons (sethfitz) July 8, 2026 14:41

Seth Fitzsimmons (sethfitz) previously approved these changes Jul 8, 2026

View reviewed changes

Copilot started work on behalf of John McCall (lowlydba) July 8, 2026 17:46 View session

Merge origin/main to resolve conflicts

964748e

Copilot AI dismissed Seth Fitzsimmons (sethfitz)’s stale review via 964748e July 8, 2026 17:50

Copilot finished work on behalf of John McCall (lowlydba) July 8, 2026 17:50

Copilot AI deployed to staging July 8, 2026 20:01 View deployment

John McCall (lowlydba) requested a review from Seth Fitzsimmons (sethfitz) July 8, 2026 21:32

Seth Fitzsimmons (sethfitz) approved these changes Jul 8, 2026

View reviewed changes

Seth Fitzsimmons (sethfitz) mentioned this pull request Jul 10, 2026

[CHORE] Drop unused __about__.py files from Python packages #551

Draft

Uh oh!

Conversation

John McCall (lowlydba) commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Major change release plan

Description

Testing

Checklist

Uh oh!

github-actions Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🗺️ Schema reference docs preview is live!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Eric Godwin (ericgodwin) left a comment

Choose a reason for hiding this comment

Uh oh!

Victor Schappert (vcschapp) commented May 27, 2026

Uh oh!

Victor Schappert (vcschapp) left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Why remove hatch dynamic versions?

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

John McCall (lowlydba) commented Jul 8, 2026

Uh oh!

Copilot AI commented Jul 8, 2026

Uh oh!

John McCall (lowlydba) commented Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

John McCall (lowlydba) commented May 21, 2026 •

edited

Loading

github-actions Bot commented May 21, 2026 •

edited

Loading

Victor Schappert (vcschapp) left a comment •

edited

Loading