Skip to content

Adopt SemVer and publish releases from CI - #19

Closed
dsaiko wants to merge 2 commits into
mainfrom
docs/versioning-policy
Closed

dsaiko wants to merge 2 commits into
mainfrom
docs/versioning-policy

Conversation

@dsaiko

@dsaiko dsaiko commented Sep 13, 2026 •

Copy link
Copy Markdown
Contributor

The repository had exactly one tag — v2025.01, January 2025 — in a vYYYY.NN
shape used once and never repeated. Nothing said whether .01 was a month or a
counter, and three contract changes (#15, #16, #18) shipped untagged behind it.

Nothing enforced a release either: ci.yml already triggered on v* tags but had
no release job, so pushing a tag ran the schema check and produced nothing. That
is how a published contract ends up with one release in twenty months.

This fixes both halves.

The scheme, written into the README

vMAJOR.MINOR.PATCH, with the major tracking the contract generation rather
than this repository's history
. v1.x.y describes wire v1 — the one behind the
/v1/ REST paths and the feed/v1 / rest/v1 SDK packages. A v2.0.0 would
only ever accompany a /v2/, which means a major bump is something clients are
told about rather than something they discover. Additive attributes and messages
are minor; corrections that do not change what the producer sends are patch.

This also brings the repo in line with every other Oddin contract repo —
protocol_buffers v0.1091.0, otsschema v0.29.0, bragischema v0.2.13, and the
three SDKs — where oddsfeedschema was the only CalVer outlier.

v2025.01 is referenced nowhere (not by the SDKs, not by docs), so it is left
in place as a legacy tag rather than continued.

The release job

A v* tag now publishes the GitHub release itself:

  • Gated on needs: schema, so a tag whose schema does not compile cannot
    become a download. Given match_summary.xsd did not compile from before
    v2025.01 until Make the schema describe what the producers actually send #18, this is not hypothetical.
  • Attaches oddsfeedschema-vX.Y.Z.zip containing schema/ alone. Consumers
    who regenerate bindings want the XSDs, not the fixtures and the checker that
    GitHub's own source archives carry.
  • A release written by hand before the tag is pushed keeps its notes and only
    gains the asset — so a breaking change can still be explained properly, the way
    v1.0.0 was. A bare tag gets generated notes instead.
  • A tag with a hyphen (v1.1.0-rc.1) is published as a pre-release, matching
    how the SDKs tag their release candidates.
  • It elevates to contents: write per job, so the job that executes
    repository code keeps read-only.

Verified the three branches of that shell against a mock gh:

tag v1.1.0, no release yet  -> gh release create v1.1.0 …zip --title v1.1.0 --generate-notes
tag v1.1.0, release exists  -> gh release upload v1.1.0 …zip --clobber
tag v1.1.0-rc.1, no release -> gh release create … --generate-notes --prerelease

v1.0.0 is already tagged and released by hand, so the job first runs on the next
tag. No schema change here — make check still passes at 31 schemas, 41 payloads,
0 problems.

Note for whoever reviews this

The oddsfeedschema-main-ruleset sets require_code_owner_review, but the
repository has no CODEOWNERS file. Worth either adding one or dropping that
requirement.

🤖 Generated with Claude Code

@dsaiko dsaiko changed the title Write down the release versioning policy Adopt SemVer and publish releases from CI Sep 13, 2026
dsaiko and others added 2 commits September 14, 2026 15:14
The repository had exactly one tag, v2025.01 from January 2025, in a
vYYYY.NN shape used once and never repeated - so nothing said whether
".01" was a month or a counter, and three contract changes shipped
untagged behind it.

Adopt vMAJOR.MINOR.PATCH instead, matching every other Oddin contract
repository, with the major anchored to the contract generation rather
than to this repository's history: v1.x.y describes wire v1, the one
behind the /v1/ REST paths and the feed/v1 and rest/v1 SDK packages, so
a major bump is something clients are told about rather than something
they discover. Additive attributes and messages are minor; corrections
that do not change what the producer sends are patch.

v2025.01 is referenced nowhere - not by the SDKs, not by the docs - so
it is left in place rather than continued.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Pushing a tag ran the schema check and produced nothing; the release had
to be built by hand, which is how the repository ended up with one tag in
twenty months.

A tag now publishes the GitHub release itself, gated on the schema check
for that same tag so a schema that does not compile cannot become a
download. It attaches a zip of schema/ alone - consumers regenerating
bindings want the XSDs, not the fixtures and the checker.

Two behaviours worth knowing rather than rediscovering: a release created
by hand before the tag is pushed keeps its notes and only gains the
asset, so a breaking change can still be explained properly; and a tag
with a hyphen in it is published as a pre-release, matching how the SDKs
tag their release candidates.

The job elevates to contents:write on its own rather than widening the
workflow default, so the job that executes repository code keeps read.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@dsaiko
dsaiko force-pushed the docs/versioning-policy branch from 2d80e03 to 66cbdd1 Compare September 14, 2026 13:14
@dsaiko

dsaiko commented Sep 14, 2026

Copy link
Copy Markdown
Contributor Author

Landed on main directly as db55490 — the two commits were squashed in rather than merged, so this PR has nothing left to merge. Closing keeps the linear history the ruleset requires.

Content is unchanged from what was reviewed here: README.md versioning + release process, and the release job in ci.yml.

@dsaiko dsaiko closed this Sep 14, 2026
@dsaiko
dsaiko deleted the docs/versioning-policy branch September 14, 2026 13:16
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