From c396fde46af69b4b0868f413fbd199c43fbb40f3 Mon Sep 17 00:00:00 2001
From: Horst Gutmann <horst.gutmann@grafana.com>
Date: Fri, 2 Aug 2024 09:15:15 +0200
Subject: [PATCH] docs: add instructions for releasing a new version

---
 docs/astro.config.mjs                       | 10 +++++++++
 docs/src/content/docs/internal/releasing.md | 24 +++++++++++++++++++++
 2 files changed, 34 insertions(+)
 create mode 100644 docs/src/content/docs/internal/releasing.md

diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index c981b5cf7..204706110 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -146,6 +146,16 @@ export default defineConfig({
           label: 'Known issues',
           link: '/known-issues',
         },
+        {
+          label: 'Project internals',
+          collapsed: true,
+          items: [
+            {
+              label: 'Releasing a new version',
+              link: '/internal/releasing',
+            }
+          ]
+        },
       ],
     }),
     tailwind({
diff --git a/docs/src/content/docs/internal/releasing.md b/docs/src/content/docs/internal/releasing.md
new file mode 100644
index 000000000..2435d893c
--- /dev/null
+++ b/docs/src/content/docs/internal/releasing.md
@@ -0,0 +1,24 @@
+---
+title: "Releasing a new version"
+---
+
+Releasing a new version of Tanka requires a couple of manual and automated steps.
+This guide will give you a runbook on how to do them in the right order.
+
+## 1. Create a release tag
+
+1. Pull the latest changes from the `main` branch to your local clone.
+1. Create a new tag with the prefix `v` (e.g. `v0.28.0`).
+1. Push that tag back to GitHub.
+
+This starts multiple GitHub workflows that will produce binaries, a Docker image, and also a new GitHub release that is *marked as draft*.
+
+## 2. Add changelog to the release notes
+
+Once all these actions have finished, go to <https://github.com/grafana/tanka/releases> and you should see the new draft release.
+Click the pencil icon ("edit") at the top-right and go to the last line of the text body.
+Now hit the "Generate release notes" button to add a changelog to the end of the release notes.
+
+## 3. Publish the release notes
+
+Once you've check that the release looks fine (e.g. no broken links, no missing version numbers in the download paths) click the "Publish release" button.