From 29f97a18e396b9744d042dd4fcac6c0980830f9e Mon Sep 17 00:00:00 2001
From: Matthias Meulien <orontee@gmail.com>
Date: Tue, 9 Jul 2024 00:55:07 +0200
Subject: [PATCH] Document how-to release

---
 CONTRIBUTING.md        |  8 ++++++
 README.md              |  2 +-
 docs/how-to-release.md | 55 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 64 insertions(+), 1 deletion(-)
 create mode 100644 docs/how-to-release.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3ab8df4..f4a184c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -88,6 +88,14 @@ dependencies.
    meson compile -C builddir sha
    ```
 
+### Build through GitHub action
+
+The GitHub action `build-application` allows to simultaneously build
+the application, its installer, and an archive.
+
+It's mainly used to release the application, see [How-to
+release](./docs/how-to-release.md).
+
 ## Tooling
 
 Format sources:
diff --git a/README.md b/README.md
index dc87a66..7196f4f 100644
--- a/README.md
+++ b/README.md
@@ -89,7 +89,7 @@ No developer skills are required to contribute to translations or add
 support for new languages, thanks to the [Weblate
 platform](https://hosted.weblate.org/projects/taranis/taranis/). More
 on this topic in the [translations
-documentation](./po/translations.md).
+documentation](./po/README.md).
 
 Instructions to install an unreleased version, debug, etc. can be
 found in the [CONTRIBUTING guide](./CONTRIBUTING.md).
diff --git a/docs/how-to-release.md b/docs/how-to-release.md
new file mode 100644
index 0000000..d10abca
--- /dev/null
+++ b/docs/how-to-release.md
@@ -0,0 +1,55 @@
+# How-to release
+
+Sticky note for maintainers.
+
+1. Identify new version "number", say `1.9.0`, according to [Semantic
+   Versioning Specification](https://semver.org/) and
+   [NEWS.md](../NEWS.md) content.
+   
+2. Commit "Prepare release of version 1.9.0" with 
+
+  - Update of version number in [meson.build](../meson.build)
+  
+  - Rename of "Unreleased" section in [NEWS.md](../NEWS.md).
+  
+3. Tag previous commit with `v1.9.0` (or `v1.9.0-rcn` if release
+   candidates are needed).
+   
+4. Push previous commit and tag to GitHub.
+
+5. From GitHub website, run the `build-application` action for the
+   `main` branch and the new tag.
+   
+6. Download generated artefact and unzip the downloaded file.
+
+7. [Draft a new
+   release](https://github.com/orontee/taranis/releases/new) named
+   "Release 1.9.0" with content:
+   
+        See [News file](https://github.com/orontee/taranis/blob/v1.9.0/NEWS.md) for release content.
+
+        **Full Changelog**: https://github.com/orontee/taranis/compare/v1.8.0...v1.9.0
+
+        ## How to install
+
+        Install by copying the `taranis.pbi` file to the e-book reader, then open the corresponding "book" using the library application.
+
+        An alternative is to manually copy the files from the `taranis.zip` archive to the `applications` directory of the e-book reader.
+
+   ⚠️ Check the "Set as pre-release" box
+   
+   Attach the following files:
+   
+   - `taranis.pbi`
+   - `taranis.sha256`
+   - `taranis.zip`
+   
+   Then save release.
+   
+8. Download installer from release, install, test.
+
+9. If everything is ok, edit release to uncheck the "Set as
+   pre-release" box and check the "Set as the latest release" box.
+   
+10. Advertise new release on [MobileRead forum dedicated to
+    PocketBook](https://www.mobileread.com/forums/forumdisplay.php?f=206)