From 94c64d225128eb56841a76f19ef7065815ea9f70 Mon Sep 17 00:00:00 2001
From: Jonas L <jooola@users.noreply.github.com>
Date: Tue, 26 Jul 2022 18:00:43 +0200
Subject: [PATCH] docs: add release instructions (#1995)

---
 docs/developer-manual/development/releases.md | 132 ++++++++++++++++++
 1 file changed, 132 insertions(+)

diff --git a/docs/developer-manual/development/releases.md b/docs/developer-manual/development/releases.md
index edbfb177a..d0b3998af 100644
--- a/docs/developer-manual/development/releases.md
+++ b/docs/developer-manual/development/releases.md
@@ -25,3 +25,135 @@ In a nutshell, given a version number `MAJOR.MINOR.PATCH` we increment the:
 1. `MAJOR` version when we make incompatible API changes,
 2. `MINOR` version when we add functionality in a backwards-compatible manner, and
 3. `PATCH` version when we make backwards-compatible bug fixes.
+
+## Releasing a new version
+
+This guide walks you through the steps required to release a new version of LibreTime.
+
+:::caution
+
+This guide is still a work in progress, and does not cover every use cases. Depending on
+the version bump, some steps might be wrong. For example, in case of a patch release,
+the documentation requires different changes.
+
+:::
+
+Before releasing a new version, make sure linter don't fail and tests are passing.
+
+Start by cleaning the repository and make sure you don't have uncommitted changes:
+
+```
+git checkout main
+make clean
+git status
+```
+
+Choose the next version based the our [versioning schema](#versioning-schema):
+
+```bash
+export VERSION=3.0.0-beta.0
+```
+
+Create a new `release-$VERSION` branch and release commit to prepare a release pull request:
+
+```bash
+git checkout -b "release-$VERSION"
+git commit --allow-empty "chore: release $VERSION"
+```
+
+### 1. Version bump
+
+Write the new `$VERSION` to the VERSION file, and bump the python packages version:
+
+```bash
+echo $VERSION > VERSION
+bash tools/bump-python-version.sh
+
+git add .
+git commit --fixup ":/chore: release $VERSION"
+```
+
+### 2. Release note
+
+Prepare a new release note based on the `docs/releases/unreleased.md` file. Be sure that
+the filename match the releases notes naming conventions:
+
+```bash
+ls -l docs/releases/
+cp docs/releases/unreleased.md docs/releases/$VERSION.md
+```
+
+The release note file must be updated with:
+
+- the version and date of this release,
+- an auto generated features and bug fixes changelog,
+- instructions for upgrading,
+- deprecation notices,
+- remove empty sections.
+
+Reset and clean the `docs/releases/unreleased.md` file for a future version.
+
+Update the Github release creation job to use the new release note file in `.github/workflows/release.yml`.
+
+Commit the release note changes:
+
+```bash
+git add .
+git commit --fixup ':/chore: release'
+```
+
+### 3. Website and docs
+
+Update the version in the website files, the files that need changing are:
+
+- `website/vars.js`
+- `website/versions.json`
+
+Replace the old versioned docs with the current docs:
+
+```bash
+mv website/versioned_sidebars/version-*-sidebars.json website/versioned_sidebars/version-$VERSION-sidebars.json
+
+rm -R website/versioned_docs/version-*
+cp -R docs website/versioned_docs/version-$VERSION
+```
+
+Commit the website and docs changes:
+
+```bash
+git add .
+git commit --fixup ':/chore: release'
+```
+
+### 4. Create a new pull request
+
+Squash the changes and open a pull request for others to review:
+
+```bash
+git rebase --autosquash --interactive main
+```
+
+Merge the pull request when it is reviewed and ready.
+
+### 5. Create and push a tag
+
+Pull the merged release commit:
+
+```bash
+git checkout main
+git pull upstream main
+```
+
+Make sure `HEAD` is the previously merged release commit and tag it with the new version:
+
+```bash
+git show --quiet
+
+git tag -a -m "$VERSION" "$VERSION"
+```
+
+Push the tag upstream to finalize the release process:
+
+```bash
+git push upstream main --follow-tags
+```