DOC Update instructions for bug-fix release

jjerphan · jjerphan · commit a2f71c6e561e · 2023-02-02T10:10:32.000+01:00
diff --git a/doc/developers/maintainer.rst b/doc/developers/maintainer.rst
@@ -17,6 +17,8 @@ Before a release
 
 1. Update authors table:
 
+   Create a token on GitHub's page with the following permission: ``read:org``.
+   Run the following script, entering the token in:
    .. prompt:: bash $
 
        cd build_tools; make authors; cd ..
@@ -107,34 +109,62 @@ 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 and 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.
 
-First, create a branch, **on your own fork** (to release e.g. `0.99.3`):
+ - Create a branch, **on your own fork** (here referred to as `fork`) for the release.
+   For instance, to release `1.2.2` create the `release-1.2.2` branch
+   from `main` with:
+
+    .. prompt:: bash $
+
+        git checkout main
+        git pull upstream main:main
+        git checkout -b release-1.2.2 main
+        git push -u fork release-1.2.2:release-1.2.2
+
+ - Create a 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.
+
+ - Locally rebase `release-1.2.2` from the `upstream/1.2.X` branch using:
+
+    .. prompt:: bash $
+
+        git rebase -i upstream/1.2.X
+
+   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).
+
+     - **Do not remove lines but drop commit by replace** ``pick`` **with** ``drop``
 
-.. prompt:: bash $
+     - Commits to pick for bug-fix release *generally* are prefixed with: `FIX`, `CI`,
+       `DOC`
 
-    # assuming main and upstream/main are the same
-    git checkout -b release-0.99.3 main
+     - Commits to drop for bug-fix release *generally* are prefixed with: `FEAT`,
+       `MAINT`, `ENH`, `API`
 
-Then, create a PR **to the** `scikit-learn/0.99.X` **branch** (not to
-main!) with all the desired changes:
+     - 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`).
 
-.. prompt:: bash $
+     - Save and exit, starting the interactive rebase.
 
-    git rebase -i upstream/0.99.X
+     - Resolve merge conflicts when they happen.
 
-Copy the :ref:`release_checklist` templates in the description of the Pull
-Request to track progress.
+ - Create a commit reordering the changelog.
 
-Do not forget to add a commit updating ``sklearn.__version__``.
+ - Create a commit updating the version number i.e. ``sklearn.__version__``.
 
-It's nice to have a copy of the ``git rebase -i`` log in the PR to help others
-understand what's included.
+Copy the :ref:`release_checklist` template and paste it in the description of the
+Pull Request to track progress.
 
 .. _making_a_release:
 
