Release Process¶
How a Versioning bump becomes a published, resolvable ontology release.
The Release PR¶
An open pull request titled Release cut: … (branch release/next) means a release is pending. release-pr.yml maintains it:
- After every push to
mainit rebuilds the branch frommainand updates the PR, so it always covers everything unreleased. When nothing is pending it closes the PR. - Each module's next version is its last released version plus the bump
scripts/compat_diff.pyrequires (a module never released keeps its declared version). The PR bumpsowl:versionInfoandowl:versionIRI, moves[Unreleased]under a dated version heading inchangelogs/<module>.md, and updates theCHANGELOG.mdrollup, the README release-badge links and the versions line inAGENTS.md. - The description has a Pull requests in this release section: for each module, the merged PRs that changed its ontology file since its last tagged release (a commit pushed straight to
mainis listed by its hash). It is the same list the GitHub Release notes will carry once the release is made, and it is rebuilt with the rest of the description, so a PR merged while the Release PR is open appears on the next rebuild. A first release, or a module whose previous release was never tagged, says there is no list to count from. - The PR is a draft while any pending module has an empty
[Unreleased]section: its release notes would be empty. Add the changelog entry onmain; the PR updates itself. - The PR is opened by the ADIRO Bot GitHub App, so it gets the normal PR checks (validation, reasoning, version-impact comment). The workflow also runs
validate_ontology.pyandcompat_diff.py --enforcebefore pushing the branch, as a fail-fast check on its own output. - The bump is the classifier's minimum unless an override raises it. The branch is rebuilt on every merge, so a hand edit to it is overwritten.
How the bump is chosen¶
Each module's bump is the highest one required by any of its unreleased changes:
| Change since the last release | Bump |
|---|---|
| A term is removed, or changes kind (class ↔ property) | MAJOR |
| A domain, range, superclass, superproperty or restriction is changed or tightened | MAJOR |
| A term is added, or a restriction is loosened or removed | MINOR |
| Only annotations change (labels, comments, definitions) | PATCH |
Example¶
How the Release PR evolves as changes reach main:
Merged to main |
The Release PR then shows |
|---|---|
A PR adds a class to adiro_common_symbols and writes its changelog entry |
Opens: adiro_common_symbols 3.0.0 → 3.1.0 (MINOR) |
A PR removes a property from adiro_common_symbols |
Same PR, updated: adiro_common_symbols → 4.0.0 (MAJOR replaces MINOR) |
A PR adds rdfs:comment text to adiro_domain_common, with no changelog entry |
Same PR now lists both modules (adiro_domain_common 2.0.0 → 2.0.1, PATCH) and becomes a draft: its release notes would be empty |
A PR adds the missing adiro_domain_common changelog entry |
Same PR, ready for review again |
| You merge the Release PR | Both modules are tagged and released; the PR is closed |
The next ontology change reaches main |
A new Release PR opens |
Merging the Release PR is the release. The next run of release-pr.yml completes each release whose cut has been merged (declared version has a dated changelog heading, but no snapshot under versions/ yet): it publishes the GitHub Release, or re-dispatches backup-version.yml if the Release already exists. Because a release stays pending until its snapshot lands, a run that failed half way is picked up by the next push to main. Once nothing is pending, the run also deletes the release/next branch left behind by the merge. Both jobs run only on the default branch: a manual dispatch naming any other ref is skipped, so a feature branch can never publish tags or rewrite release/next. Publishing the Release (as the ADIRO Bot) fires the release event, which starts backup-version.yml; everything below then runs as before.
Manual cut¶
The same cut can still be made by hand, for example when the bot is unavailable:
- Determine the bump — classify the change per the compatibility-diff spec → MAJOR / MINOR / PATCH.
- Bump
owl:versionInfoandowl:versionIRIin that module'ssrc/<module>.ttlonmain(CI enforces tag ==versionInfo==versionIRItail). - Move that module's
[Unreleased]changelog entries inchangelogs/<module>.mdunder the new version heading. - Name the earlier versions: run
uv run python scripts/prepare_release.py priors, which rewrites theowl:priorVersionlines of each module's header for its declared version (see Naming earlier versions). The bot does this for every module it releases. - Tag
<module>-v<semver>(e.g.aec_common_symbols-v1.2.0) and publish a GitHub Release from that tag.
Tag convention:
<module>-v<semver>. Module names use_and never contain-v, so the tag parses unambiguously into module + version, and maps 1:1 to the versionIRI path…/<module>/<semver>.
Everything after step 5 is automatic.
What runs automatically¶
backup-version.yml — triggered by the GitHub Release being published:
- Verifies the tag's module/version match what
src/<module>.ttldeclares at that tag. - Snapshots
src/<module>.ttltoversions/<module>/<semver>/and pushes the commit tomain. - Sets the Release notes (
scripts/release_notes.py). They start with a summary line with the SemVer bump (MAJOR / MINOR / PATCH, or first release), the previous → this version and a compare link, followed directly (no header) by three links, in this order: the module's published documentation page,Ontology (latest)andThis versiononw3id.org/adiro. Then the module'schangelogs/<module>.mdsection; and the pull requests that changedsrc/<module>.ttlsince the previous release (a bare commit is listed where there was no PR).
The job then dispatches generate-deploy-docs.yml explicitly (a push made with the default GITHUB_TOKEN does not start other workflows, so the snapshot push cannot trigger it). That workflow regenerates the docs, builds the MkDocs site (--strict, so a broken link would fail the build here), and deploys to GitHub Pages — publishing both the unversioned "latest" …/<module>.ttl and the new versioned snapshot …/<module>/<semver>/<module>.ttl as resolvable URLs.
The same job can be started by hand for an existing tag — gh workflow run backup-version.yml -f tag=<module>-v<semver> — which is what a Release published with GITHUB_TOKEN (and therefore not firing the release event) needs. The deploy dispatch is unconditional: it runs whether or not the job pushed a new snapshot, so re-running the job for a tag whose snapshot already exists repairs a release whose Pages deploy was missed. The cost of a re-run is one extra docs build, and the deploy publishes the current state of main (not the tagged commit), exactly as any push to main does.
If several modules changed together, cut one tag per changed module — each is an independent release, and each publishes through this same chain on its own.
After the deploy, the verify-prior-versions job of post-deploy-checks.yml (run after each successful deploy, #217) requests every owl:priorVersion IRI of every module from the published site and fails the run if one does not resolve to the release it names (scripts/check_prior_versions.py). A failure also opens one tracking issue (opened as the ADIRO Bot, commented on while later deploys keep failing, closed by the first deploy that passes), because a red run on main only notifies whoever merged.
Release badges¶
The README shows the latest released version of every module as a badge beside the banner. Each badge reads badges/<module>.json from the published site; scripts/release_badges.py (called by generate_docs.py) writes those files from the highest SemVer under versions/<module>/, so they refresh on every docs deploy, including the one dispatched after a release. They follow the shields.io endpoint schema (schemaVersion, label, message, color) and can feed anything else that needs the latest version of each module. A badge links to the release page of the module's latest version (…/releases/tag/<module>-v<semver>); the Release PR bumps those links at the release cut, and tests/test_readme_badges.py fails if a link does not match the module's declared version. A new module needs its badge in README.md (the same test enforces it).
Overriding a bump or holding a module¶
The bump is the compat-diff minimum, and that tool compares the Turtle syntactically. Two cases need a human decision, and both are made in config/release_overrides.json on main, where the choice is reviewed like any other commit and survives every rebuild of the Release PR. The file maps a module to one value:
{
"adiro_domain_common": "minor",
"adiro_facade_domain": "hold"
}
| Value | Effect |
|---|---|
"patch", "minor", "major" |
Raises the module's bump to at least that level. It never lowers it below what the changes require; a lower value has no effect, and the PR says so. Consumed by the release cut, so it applies to one release only. |
"hold" |
Leaves the module out of the Release PR (listed under "Held back") until the entry is deleted. |
An unknown module or any other value fails the workflow, so a typo cannot silently do nothing.
When to use an override¶
The classifier reads the Turtle, not the meaning. An override is for the cases where the people making the release know something the syntax does not show, or want to release some modules and not others.
| Scenario | Set | What the Release PR shows | When it goes away |
|---|---|---|---|
A meaning changed with no structural footprint. Ten rdfs:comment definitions in adiro_domain_common are reworded and one changes what Beam means. The classifier sees annotation edits only (PATCH), but consumers should notice. |
"adiro_domain_common": "minor" (or "major" if consumers must change something) |
The module's "Bump" column shows the raised level (MINOR), and its "Driven by" column ends with override: raised from PATCH. |
At the release cut, automatically: a bump override applies to one release only. |
Release one module, keep another back. adiro_drawing_metadata is needed now, while adiro_domain_common holds unfinished work already merged to main. |
"adiro_domain_common": "hold" |
adiro_drawing_metadata is in the table. A Held back line lists adiro_domain_common with the version and bump it would get. |
Never automatically. Delete the line when the module is ready; the next rebuild then includes it. |
| Release nothing yet. A set of related changes should ship together, but half of it is merged. | "hold" on each pending module |
The Release PR is closed (and its branch deleted) with "No release is pending on main any more". |
Delete the hold lines; the next push to main opens a new Release PR. |
| Signal a bigger change than the classifier can see. A class keeps its IRI but now means something different. | "major" for that module |
override: raised from MINOR (or PATCH). | At the release cut. |
An override is not the tool for:
- Lowering a bump. A value below what the changes require has no effect; the row says override: patch (no effect: the changes already require MAJOR). A breaking change cannot be released as a PATCH.
- A module's first release. It keeps its declared version; the row says no effect: first release keeps its declared version.
- A missing or poor release note. Write the entry under
[Unreleased]inchangelogs/<module>.mdonmaininstead. A pending module with an empty entry keeps the Release PR a draft until it is filled in.
Applying an override, step by step¶
- Edit
config/release_overrides.jsononmain, through a PR like any other change. One value per module; leave{}when there are none. Do not edit therelease/nextbranch: it is rebuilt frommainon every merge and the edit is lost. - Wait for the rebuild. The merge triggers the Release PR workflow, which regenerates the PR within a minute or two. Read the table: the bump and the override note, or the Held back line.
- Check the changelog entries in the PR body read well as release notes, then merge the Release PR when ready.
- Clean up. A bump override is removed from the file by the release cut itself. A
holdstays until it is deleted by hand, so a forgotten hold keeps a module out of every release; the Held back line on every Release PR is the reminder.
If the Release PR workflow fails with a message naming config/release_overrides.json, the file holds an unknown module name or a value other than patch, minor, major or hold.
Releasing the checks¶
The data-validation shapes and the UC-01 competency queries are released as the checks, with their own version (#240); what a version number means for them is in Data validation. They are not a module, so the Release PR does not cut them. A release is made by hand:
- Date the release. In a pull request, move the
[Unreleased]entries ofchangelogs/checks.mdunder a new heading## [<version>] — <date>, choosing the version by the rules above, and merge it. - Publish a GitHub Release with the tag
checks-v<version>on that merge commit (gh release create checks-v1.0.0 --target main --title "checks 1.0.0" --notes "See changelogs/checks.md"). - The rest is automatic.
backup-version.ymlchecks thatchangelogs/checks.mdat the tag has the dated section, exports the checks as they are at the tag intoversions/checks/<version>/with the tag's ownscripts/export_checks.py, commits the snapshot, starts the docs deploy, which serves everything underversions/checks/athttps://w3id.org/adiro/checks/<version>/, and sets the Release notes from the changelog section. A failed run is reported by the release-snapshot alert like a module's, andgh workflow run backup-version.yml -f tag=checks-v<version>repairs it. A snapshot that exists is never rebuilt: a repair only redeploys it and resets the notes, so a pinned release does not change.
The snapshot never holds a file named checks.ttl: the scripts that scan versions/ read versions/<name>/<version>/<name>.ttl as a
module release.
Design decisions¶
- The workflow acts as the ADIRO Bot GitHub App, not as
GITHUB_TOKEN. Events created withGITHUB_TOKENstart no other workflows, so a bot PR would get no PR checks and a published Release would not startbackup-version.yml; both needed workarounds. An app installation token has neither limit, and the bot gets its own name and logo. The app is registered at organisation level and installed on this repository; its credentials are the repository secretsADIRO_BOT_APP_IDandADIRO_BOT_PRIVATE_KEY, and the workflow requests a short-lived token from them on each run. The same identity is meant for other bot features (#106). - The Release PR is reasoned over like any ontology PR. It changes
src/*.ttl(version strings), soontology-reasoning.ymlruns on it. It cannot change entailments, so this adds no new coverage. The one real gap, that a PR's reasoner check is not repeated if another PR merges after its last push, is independent of releases and is closed byreasoning-main.yml: it reasons overmainitself after every push that touches the ontology (#104). - A change to the ontology header counts as a PATCH. The compatibility diff compares named terms only, so a header-only change, such as adding
owl:priorVersionto every module, was invisible to it and produced no release. Header annotations other than the version and the imports are now compared as one pseudo-symbol (ONTOLOGY_HEADER_CHANGED, non-breaking, PATCH). A version bump is the release cut's own change, so it does not count. An added or removedowl:importsis its own non-breaking delta (IMPORTS_CHANGED, PATCH), so an imports-only change is released too. - PATCH-only (annotation) changes also open a Release PR. Opening a PR forces nothing; merging does. The purpose is that a pending release is always visible, and hiding PATCH changes would leave them unreleased and unseen until something larger arrived.
- An empty
[Unreleased]section makes the PR a draft rather than failing the job or only warning. A draft cannot be merged by accident with empty release notes, it still shows that a release is pending, and it becomes ready on its own once the changelog entry is added. This is the fallback: the earlier check belongs at PR time, where the author can write the entry while the change is fresh (#105). - Overrides live in a file on
main, not on the PR branch, because the branch is regenerated frommainon every merge. One value per module (a bump level orhold) keeps it to a single thing to remember, and a bump can only be raised so that a breaking change cannot be released as a PATCH.