OASF Release Process

[akijakya]

Hi team,

I'd like to clarify and document our release process for the OASF project to ensure everyone is aligned.

Release Branches and Versioning

• We use release branches for each schema release because the schema and server are shipped bundled within a Docker image.
• The schema itself should never be changed once published, but the server can be improved independently.
• It is common to cherry-pick commits and update the server for earlier schema versions to fix bugs or add features that should be present across all OASF versions.
• We bump the minor version when the schema changes, and the patch version when only the server changes.

Release Steps for a New Schema Version

1. Create a release branch named after the version number without the v prefix (e.g., 0.6.0) to avoid collision with tag names.
2. Push a commit to that branch updating the version number in schema/version.json to the new version. Also bump the server version to the same version number in server/mix.exs.
3. Tag the commit with the new version tag (e.g., v0.6.0) and push it so the CI pipeline can create the packages.
4. Generate release notes on GitHub and publish the new release.
5. Do not delete the release branch after the release.

Tasks After a Schema Release

• Open a pull request to the main branch where the version in schema/version.json is bumped to the upcoming schema version with the -dev suffix, for example, 0.7.0-dev.
• Adjust the versions in install/charts/oasf/values-test.yaml and install/charts/oasf/values-test-versions.yaml so that local development versions are displayed correctly during project development.
• Add the new version to the compatibility matrix in proto/README.md.

Backporting Server Changes to Earlier Versions

• Checkout the relevant release branch.
• Create a new branch from it and add or cherry-pick the necessary server changes.
• Bump the server patch version in server/mix.exs.
• Open a pull request for review.
• Once merged, tag and push a new patch version (e.g., for branch 0.6.0, tags would be 0.6.1, 0.6.2, etc.).

API Version Bumping

• The API version in server/lib/schema_web/router.ex only needs to be bumped when the API endpoints themselves are changed.

Releasing a New Chart Version

• Use tags with the prefix helm/ followed by the version number, e.g., helm/vX.X.X.

Please follow this process to maintain consistency and ensure smooth releases across all OASF versions.

[akijakya]

It might be a bit confusing that while OASF has 3 components: the schema, the server and the API, we only use tags for the server that triggers building the container images. This also pollutes the Releases page where each server tag (backports, too) has its own release, making it difficult to find only schema-, server- and API related changes.

The current tagging strategy

tag	build	release notes
v1.0.0	builds a new image with server, schema and API bundled	list of all changes since the last tag
helm/v1.0.0	builds a new Helm chart	❌ no release notes

Proposed system for tags and releases

tag	build	release notes
schema/v1.0.0	❌ no build	only schema-related changes since the last tag
api/v1.0.0	❌ no build	only api-related changes since the last tag
server/v1.0.0	builds a new image with server, schema and API bundled	only server-related changes since the last tag
helm/v1.0.0	builds a new Helm chart	only helm-related changes since the last tag

The server version would still follow the schema version so it is clear that e.g. server/v0.7.6 serves schema/v0.7.0, server/v1.0.2 serves schema/v1.0.0 etc.
The release process could also be moved to a RELEASE.md document in the repo instead of being in a discussion.

[ramizpolic]

My only concern is that server tagging is schema specific, although it is clear that server maps to schema, this does not address the api-versioning. For example, between server/v1.0.1 and server/v1.0.2 there may be no breaking changes to the schema but lots of breaking changes to the api which will still be unclear.

An alternative versioning strategy is server/{schema-version}_{api-version} like server/schema-v1.0.0_api-v0.1.2 which would make it explicitly clear what was released and included in the server image

[akijakya]

What if only the server changes? Or both the server and api? What do you think about schemaA.B.C-apiD.E.F-serverG.H.I like schema1.0.0-api0.6.0-server1.0.2? In the release notes the three components could get their own sections, so it is clearer what changed in which component.

[akijakya]

After some discussions with the team, we decided not to change the versioning strategy for now.

[akijakya]

This document moved to https://github.com/agntcy/oasf/blob/main/RELEASE.md