Adjust releasing infra/docs (#8795)

* Adjust releasing infra/docs

Follow-up for #8150, see #7507

* Add suggestions

Author: The-Compiler

.github/workflows/release-on-comment.yml

@@ -14,60 +14,90 @@ Preparing: Automatic Method
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We have developed an automated workflow for releases, that uses GitHub workflows and is triggered
-by opening an issue.
+by `manually running <https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow>`__
+the `prepare-release-pr workflow <https://github.com/pytest-dev/pytest/actions/workflows/prepare-release-pr.yml>`__
+on GitHub Actions.
 
-Bug-fix releases
-^^^^^^^^^^^^^^^^
+The automation will decide the new version number based on the following criteria:
 
-A bug-fix release is always done from a maintenance branch, so for example to release bug-fix
-``5.1.2``, open a new issue and add this comment to the body::
+- If the "major release" input is set to "yes", release a new major release
+  (e.g. 7.0.0 -> 8.0.0)
+- If there are any ``.feature.rst`` or ``.breaking.rst`` files in the
+  ``changelog`` directory, release a new minor release (e.g. 7.0.0 -> 7.1.0)
+- Otherwise, release a bugfix release (e.g. 7.0.0 -> 7.0.1)
+- If the "prerelease" input is set, append the string to the version number
+  (e.g. 7.0.0 -> 8.0.0rc1), if "major" is set, and "prerelease" is set to `rc1`)
 
-    @pytestbot please prepare release from 5.1.x
+Bug-fix and minor releases
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Where ``5.1.x`` is the maintenance branch for the ``5.1`` series.
+Bug-fix and minor releases are always done from a maintenance branch. First,
+consider double-checking the ``changelog`` directory to see if there are any
+breaking changes or new features.
 
-The automated workflow will publish a PR for a branch ``release-5.1.2``
-and notify it as a comment in the issue.
+For a new minor release, first create a new maintenance branch from ``main``::
 
-Minor releases
-^^^^^^^^^^^^^^
+     git fetch --all
+     git branch 7.1.x upstream/main
+     git push upstream 7.1.x
 
-1. Create a new maintenance branch from ``main``::
+Then, trigger the workflow with the following inputs:
 
-        git fetch --all
-        git branch 5.2.x upstream/main
-        git push upstream 5.2.x
+- branch: **7.1.x**
+- major release: **no**
+- prerelease: empty
+
+Or via the commandline using `GitHub's cli <https://github.com/cli/cli>`__::
 
-2. Open a new issue and add this comment to the body::
+    gh workflow run prepare-release-pr.yml -f branch=7.1.x -f major=no -f prerelease=
 
-    @pytestbot please prepare release from 5.2.x
+Where ``7.1.x`` is the maintenance branch for the ``7.1`` series. The automated
+workflow will publish a PR for a branch ``release-7.1.0``.
 
-The automated workflow will publish a PR for a branch ``release-5.2.0`` and
-notify it as a comment in the issue.
+Similarly, for a bug-fix release, use the existing maintenance branch and
+trigger the workflow with e.g. ``branch: 7.0.x`` to get a new ``release-7.0.1``
+PR.
 
-Major and release candidates
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Major releases
+^^^^^^^^^^^^^^
 
 1. Create a new maintenance branch from ``main``::
 
         git fetch --all
-        git branch 6.0.x upstream/main
-        git push upstream 6.0.x
+        git branch 8.0.x upstream/main
+        git push upstream 8.0.x
 
-2. For a **major release**, open a new issue and add this comment in the body::
+2. Trigger the workflow with the following inputs:
 
-        @pytestbot please prepare major release from 6.0.x
+   - branch: **8.0.x**
+   - major release: **yes**
+   - prerelease: empty
 
-   For a **release candidate**, the comment must be (TODO: `#7551 <https://github.com/pytest-dev/pytest/issues/7551>`__)::
+Or via the commandline::
 
-        @pytestbot please prepare release candidate from 6.0.x
+    gh workflow run prepare-release-pr.yml -f branch=8.0.x -f major=yes -f prerelease=
 
-The automated workflow will publish a PR for a branch ``release-6.0.0`` and
-notify it as a comment in the issue.
+The automated workflow will publish a PR for a branch ``release-8.0.0``.
 
 At this point on, this follows the same workflow as other maintenance branches: bug-fixes are merged
 into ``main`` and ported back to the maintenance branch, even for release candidates.
 
+Release candidates
+^^^^^^^^^^^^^^^^^^
+
+To release a release candidate, set the "prerelease" input to the version number
+suffix to use. To release a ``8.0.0rc1``, proceed like under "major releases", but set:
+
+- branch: 8.0.x
+- major release: yes
+- prerelease: **rc1**
+
+Or via the commandline::
+
+    gh workflow run prepare-release-pr.yml -f branch=8.0.x -f major=yes -f prerelease=rc1
+
+The automated workflow will publish a PR for a branch ``release-8.0.0rc1``.
+
 **A note about release candidates**
 
 During release candidates we can merge small improvements into