From 5e89c6e3a93a1e7ec7b175a34f01881f32459732 Mon Sep 17 00:00:00 2001
From: blurbery <271863866+blurbery@users.noreply.github.com>
Date: Wed, 19 Aug 2026 19:15:35 +1000
Subject: [PATCH] fix(release): support SemVer build metadata

---
 .github/workflows/release.yml | 13 ++++++++-----
 README.md                     |  3 ++-
 docs/release-versioning.md    |  7 +++++++
 3 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 6c0803727..7886a19d0 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -5,7 +5,7 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: Semantic version tag (vMAJOR.MINOR.PATCH[-PRERELEASE])
+        description: Semantic version tag (vMAJOR.MINOR.PATCH[-PRERELEASE][+BUILD])
         required: true
         type: string
       prerelease:
@@ -39,19 +39,22 @@ jobs:
 
           core_identifier='(0|[1-9][0-9]*)'
           prerelease_identifier='(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)'
-          version_pattern="^v${core_identifier}\\.${core_identifier}\\.${core_identifier}(-${prerelease_identifier}(\\.${prerelease_identifier})*)?$"
+          build_identifier='[0-9A-Za-z-]+'
+          version_pattern="^v${core_identifier}\\.${core_identifier}\\.${core_identifier}(-${prerelease_identifier}(\\.${prerelease_identifier})*)?(\\+${build_identifier}(\\.${build_identifier})*)?$"
 
           if [[ ! "$VERSION" =~ $version_pattern ]]; then
-            echo "::error::Version must use vMAJOR.MINOR.PATCH with an optional prerelease suffix."
+            echo "::error::Version must use vMAJOR.MINOR.PATCH with optional prerelease and build metadata."
             exit 1
           fi
 
-          if [[ "$VERSION" == *-* && "$PRERELEASE" != "true" ]]; then
+          version_without_build="${VERSION%%+*}"
+
+          if [[ "$version_without_build" == *-* && "$PRERELEASE" != "true" ]]; then
             echo "::error::A version with a prerelease suffix must be marked as a prerelease."
             exit 1
           fi
 
-          if [[ "$VERSION" != *-* && "$PRERELEASE" == "true" ]]; then
+          if [[ "$version_without_build" != *-* && "$PRERELEASE" == "true" ]]; then
             echo "::error::A stable version cannot be marked as a prerelease."
             exit 1
           fi
diff --git a/README.md b/README.md
index c23fe6155..988bf0279 100644
--- a/README.md
+++ b/README.md
@@ -76,7 +76,8 @@ modern experience at home or away.
 ## Releases and updates
 
 Silo uses [Semantic Versioning](https://semver.org/) in the form
-`vMAJOR.MINOR.PATCH`, with suffixes such as `-alpha.1` for prereleases. The
+`vMAJOR.MINOR.PATCH`, with suffixes such as `-alpha.1` for prereleases and
+optional `+build.7` metadata. The
 [GitHub Releases](https://github.com/Silo-Server/silo-server/releases) page is
 the canonical public history of shipped changes, with categorized notes,
 contributors, and a full comparison for every version.
diff --git a/docs/release-versioning.md b/docs/release-versioning.md
index f4f08f30e..87a50a49f 100644
--- a/docs/release-versioning.md
+++ b/docs/release-versioning.md
@@ -12,6 +12,8 @@ Release tags follow [Semantic Versioning](https://semver.org/) with a leading
 
 - Stable release: `vMAJOR.MINOR.PATCH`, for example `v1.2.0`
 - Prerelease: `vMAJOR.MINOR.PATCH-SUFFIX`, for example `v0.1.0-alpha.1`
+- Build metadata: append `+IDENTIFIER`, for example `v1.2.0+build.7` or
+  `v0.1.0-alpha.1+build.7`
 
 For releases below `v1.0.0`, a minor release may include breaking changes. Every
 release note must call out upgrade, configuration, and compatibility impact when
@@ -51,5 +53,10 @@ The workflow rejects non-SemVer tags, mismatched prerelease settings, and runs
 from branches other than `main`. It also refuses to reuse a release tag or create
 a release when there are no commits since the previous one.
 
+GitHub's manual-workflow permission is the release access boundary: only users
+with repository write access can dispatch it. If Silo later requires a second
+approval, maintainers should configure a protected release environment with
+required reviewers and attach the release job to it before use.
+
 This process does not choose or create Silo's first version. The first tag must
 be agreed by the maintainers before the workflow is run.