From 2372b6321efc3f5ef5c3301ead5bc9487f67fc0f Mon Sep 17 00:00:00 2001
From: Samantaz Fox <coding@samantaz.fr>
Date: Sun, 18 May 2025 13:08:03 +0000
Subject: [PATCH] Improve release instructions

---
 docs/create-new-invidious-release.md | 70 ++++++++++++++++++++++++----
 1 file changed, 60 insertions(+), 10 deletions(-)

diff --git a/docs/create-new-invidious-release.md b/docs/create-new-invidious-release.md
index beda9d6..db931ec 100644
--- a/docs/create-new-invidious-release.md
+++ b/docs/create-new-invidious-release.md
@@ -19,12 +19,12 @@ git remote update
 git pull origin master
 ```
 
-
 ## Step 1
 
-Update CHANGELOG.md to reflect the changes made since the last release.
+* Update version in `shard.yml`.
+* Update `CHANGELOG.md` to reflect the changes made since the last release.
 
-Each changelog entry is composed of a summary and a list of PRs (~= diff).
+Each changelog entry is composed of a summary and a list of PRs.
 
 The summary should be simple and concise, and only reflect most important
 changes, preferably sorted by impact (new features/breaking changes that the
@@ -34,13 +34,14 @@ last). Minor changes that are related to repo maintenance can be ignored.
 Do not forget to list **ALL** the PRs that have been merged since the last
 release, with the proper links.
 
-Note: Maybe this should be done each time a PR is marged?
+Note: Maybe this should be done each time a PR is merged?
 
 
 ## Step 2
 
-Commit the changes made to `CHANGELOG.md`:
+Commit the changes made in step 1:
 ```sh
+git add CHANGELOG.md shard.yml
 git commit -S -m "Release vX.Y.Z"
 ```
 
@@ -49,22 +50,71 @@ git commit -S -m "Release vX.Y.Z"
 git tag -as vX.Y.Z
 ```
 
-Git will ask to provide a tag message. All you have to do is copy/pasting the
-summary from `CHANGEMLOG.md` and adapt a the formatting as required. Do not
+Git will ask to provide a tag annotation. All you have to do is copy/pasting
+the summary from `CHANGELOG.md` and adapt the formatting as required. Do not
 include the list of PRs merged.
 
+??? warning Amending your release commit
+
+    If for some reason you need to amend your release commit (e.g you made a typo
+    in the changelog), **make sure to retag afterwards!**
+    
+    Amending a commit will change its hash, but the tag will remain attached to
+    the previous (now dangling) commit.
+
+    Here's is how to amend your changes and retag:
+    ```sh
+    # Amend changes
+    git commit --amend --no-edit
+
+    # Retag while reusing the previous tag's annotation
+    git tag -l --format='%(contents)' vX.Y.Z > tag_msg.tmp
+    git tag -F tag_msg.tmp -as -f vX.Y.Z
+    rm tag_msg.tmp
+    ```
+
+    Note: **DO NOT** retag if you already pushed you changes. If you made a
+    mistake (it happens to everybody), just create a new release.
+
 
 ## Step 3
 
-Once you have checked everything, push to GitHub:
+Check that the release commit is properly tagged:
 ```sh
-git push origin master
-git push upstream vX.Y.Z
+# Either with git log (colorful, also shows the branches/tags on the remote)
+git log --pretty=oneline -3
+
+# Or using git tag (only shows the tag(s) pointing to HEAD)
+git tag --points-at HEAD
 ```
 
+If not, go back to step 2.
+
 
 ## Step 4
 
+Edit again `shard.yml` to add `-dev` to the version string. If you didn't already, also add a "future version" title line to the
+top of the changelog under which future PR will be listed.
+
+[Example commit](https://github.com/iv-org/invidious/commit/98926047586154269bb269d01e3e52e60e044035)
+
+Commit you changes:
+```
+git add CHANGELOG.md shard.yml
+git commit -S -m "Prepare for next release"
+```
+
+# Step 5
+
+Once you have checked everything, push to GitHub:
+```sh
+git push origin master
+git push origin vX.Y.Z
+```
+
+
+## Step 6
+
 Got to GitHub to make a new release:
 https://github.com/iv-org/invidious/releases/new