Skip to content

docs: add ECMWF Versioning (SemVer) policy and cross-link it#71

Open
tlmquintino wants to merge 7 commits into
mainfrom
docs/versioning-policy
Open

docs: add ECMWF Versioning (SemVer) policy and cross-link it#71
tlmquintino wants to merge 7 commits into
mainfrom
docs/versioning-policy

Conversation

@tlmquintino

@tlmquintino tlmquintino commented Jul 16, 2026

Copy link
Copy Markdown
Member

Summary

Closes the versioning gap: the dedicated Languages/Versioning.md was an empty TODO, even though several documents (Branching, External Contributions, the open-source-audit skill, the SMP) already relied on a SemVer convention. This PR writes the authoritative ECMWF Versioning (SemVer) policy and cross-references it from every document that touches versioning.

Languages/Versioning.md — what it covers

  • Semantic Versioning MAJOR.MINOR.PATCH with clear bump rules (MAJOR = breaking, MINOR = backwards-compatible feature/deprecation, PATCH = backwards-compatible fix).
  • No v prefix on ECMWF release tags (the form checked by the open-source-audit skill), noting third-party action tags like actions/checkout@v4 keep their own convention.
  • 0.y.z initial development and how it relates to Project Maturity.
  • Deprecation / compatibility guidance (deprecate before removing; CHANGELOG recommended).
  • Production vs prerelease tags — clean x.y.z on main/master for production; x.y.z-upstream.N for non-production contractor/prerelease builds.
  • Single source of truth — one version per repo, the git tag is authoritative, tooling derives from it (e.g. setuptools_scm), generated _version.py not committed.
  • Multi-language / multi-package repositories (the previously missing piece) — one version for the whole repository, all artefacts tagged and released together; a breaking change in any public component is a MAJOR bump for the repo; components that genuinely need independent version lines belong in separate repositories; and the compiled-Python-wheel x.y.z.C build identifier (which does not change the x.y.z release version).

Cross-references added (so the policy is discoverable from everywhere versioning is mentioned)

  • Languages/README.md — index entry describes the policy.
  • Guidelines/Branching.md — release tags follow the Versioning policy.
  • Guidelines/External-Contributions.md — Tagging Rules point to the policy for the full definition.
  • Languages/Python-Wheels.md — the x.y.z.C scheme is framed as an extension of the base policy.
  • Agent Skills/open-source-audit/SKILL.md — the version-tag check now cites Languages/Versioning.md.
  • Software Management Plan/README.md — the release-strategy versioning line links the policy.
  • TODO.md — the resolved Versioning gap removed.

Notes

  • This is deliberately consistent with the existing scattered rules (no behaviour change, just consolidation + the new multi-language recommendation).
  • There is a separate open PR (docs: Codex consistency pass (links, licensing, ADRs, house style) #69, the consistency pass) that also touches some of these files; both are small and should merge cleanly, but note the overlap.

@tlmquintino
docs(languages): add the ECMWF Versioning (SemVer) policy
cea2894 
Replace the Versioning.md placeholder with the authoritative Semantic Versioning
policy: tag format (clean x.y.z, no 'v' prefix), MAJOR/MINOR/PATCH bump rules,
0.y.z initial development, deprecation/compatibility, production vs prerelease
(x.y.z-upstream.N) tags, single-source-of-truth (git tag), and — the previously
missing piece — how to version multi-language / multi-package repositories under
one version number (all artefacts released together; independent version lines
imply separate repositories; compiled-wheel x.y.z.C build identifier).

Cross-reference it from the documents that touch versioning:
- Languages/README (index description), Guidelines/Branching, Guidelines/
  External-Contributions (Tagging Rules), Languages/Python-Wheels, the
  open-source-audit skill's version-tag check, and the SMP release-strategy line.
- Remove the resolved Versioning gap from TODO.md.
@tlmquintino
tlmquintino requested a review from Copilot July 16, 2026 20:23
Copilot AI reviewed Jul 16, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR replaces the placeholder versioning guidance with an authoritative ECMWF Semantic Versioning policy and cross-links that policy from other documents that reference version tags and release practices.

Changes:

  • Add a complete Languages/Versioning.md policy covering SemVer bump rules, tag format (no v prefix), prerelease vs production tags, and single-version guidance for multi-language repos.
  • Cross-link the new versioning policy from Branching, External Contributions, Python Wheels, the open-source-audit skill, and the Software Management Plan.
  • Remove the now-resolved Languages/Versioning.md gap from TODO.md.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
TODO.md Removes the Versioning.md placeholder item from the gaps tracker.
Software Management Plan/README.md Links SMP “Versioning system” guidance to the canonical Versioning policy.
Languages/Versioning.md Adds the authoritative ECMWF SemVer/tagging/version-source-of-truth policy.
Languages/README.md Updates the Languages index entry to describe and link the new Versioning policy.
Languages/Python-Wheels.md Frames x.y.z.C wheel versioning as an extension of the base Versioning policy.
Guidelines/External-Contributions.md Adds an explicit reference from Tagging Rules to the Versioning policy.
Guidelines/Branching.md Notes release version numbers/tags follow the Versioning policy.
Agent Skills/open-source-audit/SKILL.md Updates the SemVer tag check to cite Languages/Versioning.md.

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

Comment thread Languages/Python-Wheels.md Outdated
@tlmquintino
tlmquintino requested a review from Copilot July 16, 2026 20:27
Copilot AI reviewed Jul 16, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Comment thread Languages/Python-Wheels.md Outdated
Comment thread Languages/Versioning.md Outdated
@tlmquintino
docs: clarify wheel build identifier vs SemVer; fix wheel example pla…
dcacf62 
…ceholders (Copilot)

- Versioning.md: x.y.z.N is a packaging/build identifier for wheels, not a
  SemVer version; the release version and git tag remain x.y.z.
- Python-Wheels: correct the A/C placeholder swap so the example matches its
  own definition (multio=A, mir=B, eckit=C); rename the 4th-component counter to
  N to avoid clashing with eckit's version letter C.
@tlmquintino
tlmquintino requested a review from Copilot July 16, 2026 20:33
Copilot AI reviewed Jul 16, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Comment thread Languages/Python-Wheels.md Outdated
Comment thread Languages/Versioning.md
@tlmquintino
docs: finish wheel example placeholder fix + 'duly'; 'used in product…
4da69d4 
…ion' (Copilot)

- Python-Wheels: the later pip example now uses the consistent placeholders
  (multio.A.1/eckit.C.1/eckit.C+1.2); fix 'dully' -> 'duly'.
- Versioning.md: 'used in production' instead of 'used in anger'.
@tlmquintino
tlmquintino requested a review from Copilot July 16, 2026 20:37
Copilot AI reviewed Jul 16, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Comment thread Languages/Versioning.md Outdated
Comment thread Languages/Python-Wheels.md Outdated
@tlmquintino
docs: clarify tag-as-source-of-truth (mirror rule); format x.y.z.N as…
9e99e56 
… code (Copilot)

- Versioning.md: git tag is the single source of truth; prefer deriving the
  version automatically; any in-repo version field is a single mirror that must
  match the tag.
- Python-Wheels: format the x.y.z.N / N literals as inline code.
@tlmquintino
tlmquintino requested a review from Copilot July 16, 2026 20:42
Copilot AI reviewed Jul 16, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Comment thread Languages/Python-Wheels.md Outdated
@tlmquintino
tlmquintino requested a review from Copilot July 16, 2026 20:45
Copilot AI reviewed Jul 16, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Comment thread Languages/Python-Wheels.md Outdated
Comment thread Languages/Python-Wheels.md Outdated
Comment thread Languages/Python-Wheels.md Outdated
@tlmquintino
tlmquintino requested a review from Copilot July 16, 2026 20:49
Copilot AI reviewed Jul 16, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@tlmquintino