scikit-learn · jeremiedbb · Feb 9, 2023 · Jan 23, 2023 · Jan 26, 2023 · Feb 2, 2023
diff --git a/doc/developers/maintainer.rst b/doc/developers/maintainer.rst
@@ -17,6 +17,11 @@ Before a release
 
 1. Update authors table:
 
+   Create a `classic token on GitHub <https://github.com/settings/tokens/new>`_
+   with the ``read:org`` following permission.
+
+   Run the following script, entering the token in:
+
    .. prompt:: bash $
 
        cd build_tools; make authors; cd ..
@@ -43,14 +48,16 @@ Before a release
 
 **Permissions**
 
-The release manager requires a set of permissions on top of the usual
-permissions given to maintainers, which includes:
+The release manager must be a *maintainer* of the ``scikit-learn/scikit-learn``
+repository to be able to publish on ``pypi.org`` and ``test.pypi.org``
+(via a manual trigger of a dedicated Github Actions workflow).
+
+The release manager does not need extra permissions on ``pypi.org`` to publish a
+release in particular.
 
-- *maintainer* role on ``scikit-learn`` projects on ``pypi.org`` and
-  ``test.pypi.org``, separately.
-- become a member of the *scikit-learn* team on conda-forge by editing the
-  ``recipe/meta.yaml`` file on
-  ``https://github.com/conda-forge/scikit-learn-feedstock``
+The release manager must be a *maintainer* of the ``conda-forge/scikit-learn-feedstock``
+repository. This can be changed by editing the ``recipe/meta.yaml`` file in the
+first release pull-request.
 
 .. _preparing_a_release_pr:
 
@@ -107,34 +114,74 @@ under the ``doc/whats_new/`` folder so PRs that target the next version can
 contribute their changelog entries to this file in parallel to the release
 process.
 
-Minor version release
-~~~~~~~~~~~~~~~~~~~~~
+Minor version release (also known as bug-fix release)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The minor releases should include bug fixes and some relevant documentation
 changes only. Any PR resulting in a behavior change which is not a bug fix
-should be excluded.
+should be excluded. As an example, instructions are given for the `1.2.2` release.
+
+ - Create a branch, **on your own fork** (here referred to as `fork`) for the release
+   from `upstream/main`.
+
+    .. prompt:: bash $
+
+        git fetch upstream/main
+        git checkout -b release-1.2.2 upstream/main
+        git push -u fork release-1.2.2:release-1.2.2
+
+ - Create a **draft** PR to the `upstream/1.2.X` branch (not to `upstream/main`)
+   with all the desired changes.
+
+ - Do not push anything on that branch yet.
 
-First, create a branch, **on your own fork** (to release e.g. `0.99.3`):
+ - Locally rebase `release-1.2.2` from the `upstream/1.2.X` branch using:
 
-.. prompt:: bash $
+    .. prompt:: bash $
 
-    # assuming main and upstream/main are the same
-    git checkout -b release-0.99.3 main
+        git rebase -i upstream/1.2.X
 
-Then, create a PR **to the** `scikit-learn/0.99.X` **branch** (not to
-main!) with all the desired changes:
+   This will open an interactive rebase with the `git-rebase-todo` containing all
+   the latest commit on `main`. At this stage, you have to perform
+   this interactive rebase with at least someone else (being three people rebasing
+   is better not to forget something and to avoid any doubt).
 
-.. prompt:: bash $
+     - **Do not remove lines but drop commit by replace** ``pick`` **with** ``drop``
+
+     - Commits to pick for bug-fix release *generally* are prefixed with: `FIX`, `CI`,
+       `DOC`. They should at least include all the commits of the merged PRs
+       that were milestoned for this release on GitHub and/or documented as such in
+       the changelog. It's likely that some bugfixes were documented in the
+       changelog of the main major release instead of the next bugfix release,
+       in which case, the matching changelog entries will need to be moved,
+       first in the `main` branch then backported in the release PR.
+
+     - Commits to drop for bug-fix release *generally* are prefixed with: `FEAT`,
+       `MAINT`, `ENH`, `API`. Reasons for not including them is to prevent change of
+       behavior (which only must feature in breaking or major releases).
+
+     - After having dropped or picked commit, **do no exit** but paste the content
+       of the `git-rebase-todo` message in the PR.
+       This file is located at `.git/rebase-merge/git-rebase-todo`.
+
+     - Save and exit, starting the interactive rebase.
+
+     - Resolve merge conflicts when they happen.
+
+ - Force push the result of the rebase and the extra release commits to the release PR:
+
+   .. prompt:: bash $
 
-	git rebase -i upstream/0.99.2
+       git push -f fork release-1.2.2:release-1.2.2
 
-Copy the :ref:`release_checklist` templates in the description of the Pull
-Request to track progress.
+ - Copy the :ref:`release_checklist` template and paste it in the description of the
+   Pull Request to track progress.
 
-Do not forget to add a commit updating ``sklearn.__version__``.
+ - Review all the commits included in the release to make sure that they do not
+   introduce any new feature. We should not blindly trust the commit message prefixes.
 
-It's nice to have a copy of the ``git rebase -i`` log in the PR to help others
-understand what's included.
+ - Remove the draft status of the release PR and invite other maintainers to review the
+   list of included commits.
 
 .. _making_a_release: