Differences

This shows you the differences between two versions of the page.

--- pub:development:release [25.09.2024 12:28] – ↷ Page moved from release to pub:development:release Predrag Tasevski
+++ pub:development:release [19.05.2026 17:23] (current) – [Versioning Scheme] Predrag Tasevski
@@ Line 1: / Line 1: @@
 ====== Releasing ======
-<WRAP warning> **Warring**\\
+<WRAP warning>
-The content of this page is still in progress and needs some tweaking. </WRAP>
+**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 branch exists for the version family (for 2022.12.2 the branch would be ''%%version-2022.12%%'')
+  * Ensure a version branch exists for the release family
-  * Merge all the commits that should be released on the version branch
+    * Example: %%version-2026-05%% for %%v2026-05%%
-  * If backporting commits to a non-current version branch, cherry-pick the commits.
+  * Merge all commits intended for release into the version branch
-  * Push the branch, which will run the CI pipeline to make sure all tests pass
+  * For backports, cherry-pick commits into the relevant version branch
-  * Create/update the release notes
+  * Push the branch to trigger CI validation (tests must pass)
+  * Update or generate release notes
-====== For initial releases: ======
+===== Initial Release (First Patch or Monthly Release) =====
-  * Copy ''%%docs/platform/unicis-platform-changelog/_template.md%%'' to ''%%docs/platform/unicis-platform-changelog/v2022.12.md%%'' and replace ''%%xxxx.x%%'' with the version that is being released
+  * Copy template:
-  * Fill in the section of ''%%Breaking changes%%'' and ''%%New features%%'', or remove the headers if there’s nothing applicable
-  * Run ''%%git log --pretty=format:'- %s' version/2022.11.3...version-2022.12%%'', where ''%%version/2022.11.3%%'' is the tag of the previous stable release. This will output a list of all commits since the previous release.
-  * Paste the list of commits since the previous release under the ''%%Minor changes/fixes%%'' section.
-  * Run ''%%make gen-changelog%%'' and use the contents of ''%%changelog.md%%''. Remove merged PRs from bumped dependencies unless they fix security issues or are otherwise notable. Remove merged PRs with the ''%%website/%%'' prefix.
-  * Sort the list of commits alphabetically and remove all commits that have little importance, like dependency updates and linting fixes
-  * Run ''%%make gen-diff%%'' and copy the contents of ''%%diff.md%%'' under ''%%API Changes%%''
-  * Update ''%%website/sidebars.js%%'' to include the new release notes, and move the oldest release into the ''%%Previous versions%%'' category.
-  * If the release notes are created in advance without a fixed date for the release, only add them to the sidebar once the release is published.
-  * Run ''%%make website%%''
+    %%docs/platform/unicis-platform-changelog/_template.md%%
-====== For subsequent releases: ======
+    to:
-  * Paste the list of commits since the previous release into ''%%docs/platform/unicis-platform-changelog/v2022.12.md%%'', creating a new section called ''%%## Fixed in 2022.12.2%%'' underneath the ''%%Minor changes/fixes%%'' section
+    %%docs/platform/unicis-platform-changelog/v2026-05.md%%
-  * Run ''%%make gen-changelog%%'' and use the contents of ''%%changelog.md%%''. Remove merged PRs from bumped dependencies unless they fix security issues or are otherwise notable. Remove merged PRs with the ''%%website/%%'' prefix.
-  * Run ''%%make gen-diff%%'' and copy the contents of ''%%diff.md%%'' under ''%%API Changes%%'', replacing the previous changes
-  * Run ''%%make website%%''
-  * Run ''%%bumpversion%%'' on the version branch with the new version (i.e. ''%%bumpversion --new-version 2022.12.2 minor --verbose%%'')
-  * Push the tag and commit
-  * A GitHub actions workflow will start to run a last test in container images and create a draft release on GitHub
-  * Edit the draft GitHub release
-  * Make sure the title is formatted ''%%Release 2022.12.0%%''
-  * Add the following to the release notes
-  * See https://www.unicis.tech/docs/platform/unicis-platform-changelog
-  * Or if creating a subsequent release
-  * See https://www.unicis.tech/docs/platform/unicis-platform-changelog
-  * Auto-generate the full release notes using the GitHub //Generate Release Notes// feature
+  * 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
-===== Preparing a Security Release =====
+===== Generate Commit List =====
-  * Create a draft GitHub Security advisory
+<code bash>
+git log --pretty=format:'- %s' version-2026-04...version-2026-05
+</code>
-++++ Template |
+  * 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 ====
@@ Line 56: / Line 167: @@
 ==== Patches ====
-unicis_platform x, y and z fix this issue, for other versions the workaround can be used.
+Versions vYYYY-MM-DD fix this issue.
+Workaround available for older versions.
 ==== Impact ====
-Describe the impact that this issue has
+Describe impact
 ==== Details ====
-Further explain how the issue works
+Technical explanation
 ==== Workarounds ====
-Describe a workaround if possible
+If applicable
-==== For more information ====
+==== Contact ====
-If you have any questions or comments about this advisory:
+Security team contact email
+</code>
-  * Email us at
+==== Security Branch Workflow ====
-++++
+  * Create branch: %%security/CVE-YYYY-xxxx%%
+  * Implement fix with unit tests
+  * Update release notes
+  * Create file:
-  * Request a CVE via the draft advisory
+    %%/website/docs/security/CVE-YYYY-xxxx.md%%
-  * If possible, add the original reporter in the advisory
-  * Implement a fix on a local branch ''%%security/CVE-...%%''
-  * The fix must include unit tests to ensure the issue can’t happen again in the future
-  * Update the release notes as specified above, making sure to address the CVE being fixed
-  * Create a new file ''%%/website/docs/security/CVE-....md%%'' with the same structure as the GitHub advisory
-  * Include the new file in the ''%%/website/sidebars.js%%''
-  * Check with the original reporter that the fix works as intended
-  * Wait for GitHub to assign a CVE
-  * Announce the release of the vulnerability via Mailing list and discord
-++++ Mailing list template” close |
+  * Add to:
-Subject: ''%%Notice of upcoming authentik Security releases 2022.10.3 and 2022.11.3%%''
+    %%website/sidebars.js%%
-We’ll be publishing a security Issue (CVE-2022-xxxxx) and accompanying fix on //date//, 13:00 UTC with the Severity level High. Fixed versions x, y and z will be released alongside a workaround for previous versions. For more info, see the authentik [[docs/trust-center/policies/it-security-policy/|Security policy]].
+===== Security Release Process =====
-++++
-++++ Discord template |
+On release date:
-@everyone We’ll be publishing a security Issue (CVE-2022-xxxxx) and accompanying fix on //date//, 13:00 UTC with the Severity level High. Fixed versions x, y and z will be released alongside a workaround for previous versions. For more info, see the authentik [[docs/trust-center/policies/it-security-policy/|Security policy]].
+  * Merge security PR
-++++
+  * Cherry-pick into version branch
+  * Run:
-===== Creating a Security Release =====
+<code bash>
+bumpversion --new-version YYYY-MM-DD patch
+</code>
-  * On the date specified in the announcement, push the local ''%%security/CVE-2022-xxxxx%%'' branch into a PR, and squash merge it if the pipeline passes
+  * Publish release
-  * If the fix made any changes to the API schema, merge the PR to update the web API client
-  * Cherry-pick the merge commit onto the version branch
-  * If the fix made any changes to the API schema, manually install the latest version of the API client in ''%%/web%%''
-  * Resume the instructions above, starting with the ''%%bumpversion%%'' step
-  * After the release has been published, update the Discord announcement and send another mail to the mailing list to point to the new releases
-++++ Mailing list template |
+===== Post-Release Communication =====
-Subject: ''%%Release of authentik Security releases 2022.10.3 and 2022.11.3%%''
-The security advisory for CVE-2024-xxxxx has been published: https:%%//%%github.com/UnicisTech/unicis-platform-ce/security/advisories/
+==== Mailing List ====
-Releases 2022.10.3 and 2022.11.3 with fixes included are available here: https:%%//%%github.com/UnicisTech/unicis-platform-ce/releases/
+<code>
-++++
+Subject: Security Release vYYYY-MM-DD
-++++ Discord template |
+We are publishing a security fix (CVE-YYYY-xxxx).
+Affected versions: ...
+Fixed version: vYYYY-MM-DD
-[…existing announcement…]
+See: <link>
+</code>
-Edit:
+==== Discord ====
-Advisory for for CVE-2022-xxxxx has been published here https:%%//%%www.unicis.tech/docs/platform/unicis-platform-changelog The fixed versions 2022.10.3 and 2022.11.3 are available here: https:%%//%%github.com/UnicisTech/unicis-platform-ce/releases/
+<code>
-++++
+@everyone Security release published: CVE-YYYY-xxxx
+Fixed version: vYYYY-MM-DD
+Details: <link>
+</code>
 ===== Links =====
-  * [[https://github.com/UnicisTeh/unicis-platform-ce|GitHub Community Edition]]
+  * https://github.com/UnicisTeh/unicis-platform-ce
-  * [[https://gitlab.com/unicis/unicis-platform|GitLab Business Edition]]
+  * https://gitlab.com/unicis/unicis-platform
+  * [[https://calver.org|CalVer]]
-This guide includes the steps required for creating both standard and security releases, with specific references and links for the Unicis Platform Business and Community Editions.