Releasing

Warning
This page is still in progress and may require refinement.

Versioning Scheme

The Unicis Platform uses Calendar Versioning (CalVer):

Major/Minor releases: vYYYY-MM (e.g. v2026-05)
Patch releases: vYYYY-MM-DD (e.g. v2026-05-12)

Release branches follow:

version-YYYY-MM (e.g. version-2026-05)

Creating a Standard Release

Ensure a version branch exists for the release family
- Example: version-2026-05 for v2026-05
Merge all commits intended for release into the version branch
For backports, cherry-pick commits into the relevant version branch
Push the branch to trigger CI validation (tests must pass)
Update or generate release notes

Initial Release (First Patch or Monthly Release)

Copy template:

  %%docs/platform/unicis-platform-changelog/_template.md%%

to:

  %%docs/platform/unicis-platform-changelog/v2026-05.md%%

Replace placeholders with correct CalVer version:
- xxxx.x → vYYYY-MM or vYYYY-MM-DD

Fill in:
- Breaking Changes
- New Features
- Remove sections if not applicable

Generate Commit List

git log --pretty=format:'- %s' version-2026-04...version-2026-05

Replace version-2026-04 with previous release branch/tag
Paste output into Minor Changes / Fixes

Generate Changelog

make gen-changelog

Use output from changelog.md
Remove:
- Dependency-only PRs (unless security relevant)
- website/ prefixed commits
Keep only meaningful changes
Sort alphabetically if needed

API Diff

make gen-diff

Copy diff.md into API Changes

Website Update

Update:

  %%website/sidebars.js%%

Add new release entry under current version family
Move oldest release into Previous Versions

If release notes are prepared before release date, do NOT publish them until release is confirmed.

Build Website

make website

Subsequent Patch Releases

For patch releases within the same CalVer month (e.g. v2026-05-01, v2026-05-12):

Add a new section in:

  %%docs/platform/unicis-platform-changelog/v2026-05.md%%

Example:

## Fixed in v2026-05-12

Patch Release Steps

Add commit list under new patch section
Run:

make gen-changelog
make gen-diff

Replace API Changes section
Run:

make website

Version Tagging

git tag v2026-05-12
git push origin version-2026-05
git push --tags

Or:

bumpversion --new-version 2026-05.12 patch --verbose

Release Publication

GitHub Actions:
- Runs tests
- Builds container images
- Creates draft release

Edit draft release:
- Title format: Release v2026-05-12
- Add changelog link
- Add GitHub release link

Security Release

Security Versioning

Security releases use:

vYYYY-MM-DD

Security Advisory Template

==== Summary ====

Short summary of the issue

==== Patches ====

Versions vYYYY-MM-DD fix this issue.
Workaround available for older versions.

==== Impact ====

Describe impact

==== Details ====

Technical explanation

==== Workarounds ====

If applicable

==== Contact ====

Security team contact email

Security Branch Workflow

Create branch: security/CVE-YYYY-xxxx
Implement fix with unit tests
Update release notes
Create file:

  %%/website/docs/security/CVE-YYYY-xxxx.md%%

Add to:

  %%website/sidebars.js%%

Security Release Process

On release date:

Merge security PR
Cherry-pick into version branch
Run:

bumpversion --new-version YYYY-MM-DD patch

Publish release

Post-Release Communication

Mailing List

Subject: Security Release vYYYY-MM-DD

We are publishing a security fix (CVE-YYYY-xxxx).
Affected versions: ...
Fixed version: vYYYY-MM-DD

See: <link>

Discord

@everyone Security release published: CVE-YYYY-xxxx
Fixed version: vYYYY-MM-DD
Details: <link>

Table of Contents