====== Releasing ======

<WRAP warning>
**Warning**\\
This page is still in progress and may require refinement.
</WRAP>

===== Versioning Scheme =====

The Unicis Platform uses [[https://calver.org|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 =====

<code bash>
git log --pretty=format:'- %s' version-2026-04...version-2026-05
</code>

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

===== Generate Changelog =====

<code bash>
make gen-changelog
</code>

  * 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 =====

<code bash>
make gen-diff
</code>

  * 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**

<WRAP info>
If release notes are prepared before release date, do NOT publish them until release is confirmed.
</WRAP>

===== Build Website =====

<code bash>
make website
</code>

===== 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:

<code markdown>
## Fixed in v2026-05-12
</code>

===== Patch Release Steps =====

  * Add commit list under new patch section
  * Run:

<code bash>
make gen-changelog
make gen-diff
</code>

  * Replace API Changes section
  * Run:

<code bash>
make website
</code>

===== Version Tagging =====

<code bash>
git tag v2026-05-12
git push origin version-2026-05
git push --tags
</code>

Or:

<code bash>
bumpversion --new-version 2026-05.12 patch --verbose
</code>

===== 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 ====

<code>
==== 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
</code>

==== 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:

<code bash>
bumpversion --new-version YYYY-MM-DD patch
</code>

  * Publish release

===== Post-Release Communication =====

==== Mailing List ====

<code>
Subject: Security Release vYYYY-MM-DD

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

See: <link>
</code>

==== Discord ====

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

===== Links =====

  * https://github.com/UnicisTeh/unicis-platform-ce
  * https://gitlab.com/unicis/unicis-platform
  * [[https://calver.org|CalVer]]