[docs] Readability fixes in release instructions (#904)

* [docs] Readability fixes in release instructions

* Simplify

* Improve readability in PULL_REQUEST_TEMPLATE.md

Author: ddelange

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,6 +1,8 @@
 > Please **pick a concise, informative and complete title** for your PR.
 > 
-> The title is important because it will appear in [our change log](https://github.com/RaRe-Technologies/smart_open/blob/master/CHANGELOG.md).
+> The title is important because it will appear in [`CHANGELOG.md`](/CHANGELOG.md).
+
+
 
 ### Motivation
 
@@ -12,6 +14,8 @@
 
 Fixes #{issue_number}
 
+
+
 ### Tests
 
 > If you're fixing a bug, consider [test-driven development](https://en.wikipedia.org/wiki/Test-driven_development):
@@ -29,6 +33,8 @@ Fixes #{issue_number}
 > 
 > If there are any failures, please fix them before creating the PR (or mark it as WIP, see below).
 
+
+
 ### Work in progress
 
 > If you're still working on your PR, mark the PR as [draft PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request).
@@ -37,6 +43,8 @@ Fixes #{issue_number}
 > 
 > Once it's ready, mark the PR as "ready for review", and ping one of the maintainers (e.g. mpenkov).
 
+
+
 ### Checklist
 
 > Before you mark the PR as "ready for review", please make sure you have:
@@ -48,6 +56,8 @@ Fixes #{issue_number}
 - [ ] Run `python update_helptext.py` in case there are API changes
 - [ ] Checked that all unit tests pass
 
+
+
 ### Workflow
 
 > Please avoid rebasing and force-pushing to the branch of the PR once a review is in progress.

release/README.md

@@ -1,29 +1,13 @@
-# Release Scripts
-
-This subdirectory contains various scripts for maintainers.
-
-## Prerequisites
-
-You need a GNU-like environment to run these scripts.  I perform the releases
-using Ubuntu 18.04, but other O/S like MacOS should also work.  The
-prerequisites are minimal:
-
-- bash
-- git with authentication set up (e.g. via ssh-agent)
-- virtualenv
-- pip
-
-All of the above are generally freely available, e.g. installable via apt in Ubuntu.
+> <img width=40% src="https://github.com/user-attachments/assets/cf8f2fa4-37c1-4e50-9fd8-ab6e3fd705b5">
+> 
+> [*New GitHub Release dialog*](https://github.com/piskvorky/smart_open/releases/new?target=master)
 
 ## Release Procedure
 
-> ![New GitHub Release](https://github.com/user-attachments/assets/cf8f2fa4-37c1-4e50-9fd8-ab6e3fd705b5)
-> *New GitHub Release dialog*
-
 - Check that the [latest commit](https://github.com/piskvorky/smart_open/commits/develop) on `develop` passed all CI.
 - Run `bash release/release.sh` to update `CHANGELOG.md` and then update `master` branch.
-- Create a [new GitHub Release](https://github.com/piskvorky/smart_open/releases/new?target=master).
-    - Fill in the new version including a `v` prefix and press enter.
+- The script opens a new browser tab to the [new GitHub Release dialog](https://github.com/piskvorky/smart_open/releases/new?target=master).
+    - The new version including a `v` prefix shoulb be pre-filled.
     - Confirm that it reads "Excellent! This tag will be created from the target when you publish this release.".
     - Select target branch `master`.
     - Click "Generate release notes" on the right top.
@@ -33,16 +17,9 @@ All of the above are generally freely available, e.g. installable via apt in Ubu
 
 ## Troubleshooting
 
-Ideally, our CI should save you from major boo-boos along the way.
-If the build is broken, fix it before even thinking about doing a release.
-
-If anything is wrong with the local release branch (before you call merge.sh), for example:
-
-- Typo in CHANGELOG.md
-- Missing entries in CHANGELOG.md
-- Wrong version.py number
-
-then just fix it in the release branch before moving on.
-
-Otherwise, it's too late to fix anything for the current release.
-Make a bugfix release to fix the problem.
+In case of CI/CD rot:
+- Fix it using a new PR to `develop`.
+- The failed release tag is lost: **never force push git tags!**
+- Start the release procedure from scratch and create a new release:
+  - either make new bugfix release like `7.4.2 -> 7.4.3`
+  - or make a post-release like `7.4.2 -> 7.4.2.post1`