[FEATURE] Branching strategy Phase 2.A - version computing & baselining (merge conflict resolution)

[John McCall (lowlydba)]

Major change release plan

This is not a MAJOR schema change; section included to preserve template structure.

A. Expected release date for this MAJOR change

N/A.

B. Related MINOR change steps

• N/A.

C. Public documentation and messaging plan

N/A.

Description

Phase 2.A of the branching strategy: establish version baselines and build the CI infrastructure that future publish workflows (Phases 2.B & 3) will consume.

Additional update in this PR iteration:

• Resolved merge conflicts by merging latest main into this branch.
• Kept branch changes and aligned with current main state, including upstream cleanup/removal of obsolete gers/examples/python content.

Reference

1. Prereq for [Devops] Branching Strategy - Phase 2.B - Release Versions #533 (Phase 2.B — release triggers & changelog).
2. Prereq for [Devops] Branching Strategy - Phase 3 #509 (Phase 3 — publish workflows).

Testing

• Ran repository validation with make check.
• Result: 1993 passed.
• Ran final automated validation (Code Review + CodeQL); CodeQL reported no alerts.

Checklist

1. Add relevant examples.
2. Add relevant counterexamples.
3. 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.
4. Update in-schema documentation using plain English written in complete sentences, if an update is required.
5. Update Docusaurus documentation, if an update is required.
6. 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.

Documentation website

Docs preview for this PR.

[github-actions]

🗺️ Schema reference docs preview is live!

🌍 Preview	https://staging.overturemaps.org/schema/pr/534/schema/index.html
🕐 Updated	May 27, 2026 20:16 UTC
📝 Commit	a8622b6
🔧 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.

[Eric Godwin (ericgodwin)]

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

[Victor Schappert (vcschapp)]

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:

1. 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.
2. 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...

[Victor Schappert (vcschapp)]

Not blocking, but for larger scripts (maybe 10+ lines to make up an arbitrary number) I think there's value in factoring them out into a separate .py or .sh script that's independently testable, i.e., you can run it from the command line with appropriate arguments and it does what's expected.

[John McCall (lowlydba)]

Totally - once the dust settles I'll likely convert these to GitHub Actions + scripts for similar reasons and benefits

[John McCall (lowlydba)]

Copilot resolve the merge conflicts in this pull request

[Copilot]

Copilot resolve the merge conflicts in this pull request

Conflicts are resolved in commit a8622b6 by merging origin/main into this branch and resolving the delete/modify conflicts in gers/examples/python.