Release the schema

Release the schema

CONTRIBUTING.md’s Releasing section and the Semantic release workflow say how a release is made.¹ The release tags, vX.Y.Z, number the schema’s versions, and no file is bumped. SECURITY.md says that the repository releases a LinkML schema, the Python datamodel generated from it, and the schema’s lokf adapt copy as a release asset, and that nothing is published to PyPI.² The package oscal takes its version from git through uv-dynamic-versioning, with 0.0.0 as the fallback.³

Before the first release

• Push the v0.0.0 baseline tag on main before the first releasing merge, which then releases 0.1.0. Both release jobs refuse to run without a v* tag, because semantic-release would otherwise start at 1.0.0. CHANGELOG.md calls v0.0.0 a baseline, not a release.⁴
• Configure required reviewers on the release GitHub Environment in the repository’s settings, or every qualifying merge is released unattended. SECURITY.md says that this setting is not yet in force.
• Leave off any branch rule that requires pull requests, status checks or signed commits on main, because it would reject the release job’s own push to main.

For each change

1. Write the change under ## [Unreleased] in CHANGELOG.md as you go. The release job refuses an empty section, through node .github/scripts/changelog-release.mjs check.
2. Type the commit with Conventional Commits for what the change is. Only feat:, fix:, security: and a breaking ! start a release, and other types leave their entries for the next release that does. A pull request that would release must carry a releasing type in its title too, since a squash merge takes its subject from the title.
3. Merge to main. semantic-release retitles the section to ## [X.Y.Z] - YYYY-MM-DD, commits CHANGELOG.md, tags vX.Y.Z and publishes the GitHub Release. Once the repository variable KNOWLEDGE_RELEASE_ENABLED is true, it dispatches Knowledge Release, which attaches the schema copy and the bundle when the bundle changed. Run that workflow by hand with force when only the schema changed.

Staying below 1.0.0

.releaserc.json maps a breaking change to a minor release and a security commit to a patch release.⁵ So the schema stays in 0.x until someone removes the first rule, which CONTRIBUTING.md asks to be done in a pull request of its own. The release commit’s message is chore(release): ${nextRelease.version} - changelog promoted [skip ci], so the commit skips CI.

Footnotes

1. CONTRIBUTING.md, Releasing (maintainers) ↩

2. SECURITY.md, What this repository releases and the paragraph after the table ↩

3. pyproject.toml, the tool.hatch.version and tool.uv-dynamic-versioning settings ↩

4. CHANGELOG.md, the paragraph on the v0.0.0 tag ↩

5. .releaserc.json, releaseRules and the git plugin’s message ↩