From 35cf3bf8fd05a89b7a5807f9327d3b8346dc4566 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Fri, 29 Jul 2022 10:40:39 +0200
Subject: Additional notes to release doc

---
 doc/release.cli | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/doc/release.cli b/doc/release.cli
index ce19557..285da4d 100644
--- a/doc/release.cli
+++ b/doc/release.cli
@@ -137,17 +137,31 @@ distribution from \c{etc/stage} and add the pre-distributed packages
   constraint using \c{etc/version}, commit, and then:
 
   \
+  # Step 0: make sure b, bpkg, bdep are runnable.
+
+  # Step 1: pull ODB compiler and build it, make sure runnable.
+
+  # Step 2: pull everything in build2 (including brep).
+
+  # Step 3: upgrade (in configure-only mode).
+  #
+  # If this step goes sideways, use the saved .bak configurations to
+  # revert, fix the issue, and try again. If unable to fix the issue
+  # (for example, the toolchain is not runnable), then do the from-
+  # scratch bootstrap using the etc/bootstrap script.
+  #
   etc/upgrade -c
 
-  # Trigger header regeneration (ignore ODB version mismatch errors).
+  # Step 4: trigger header regeneration (ignore ODB version errors).
   #
   BDEP_SYNC=0 b --match-only ~/work/build2/builds/gcc7/
 
-  # Make sure the ODB compiler is up-to-date and run in all the relevant
-  # projects (bpkg, bdep, brep):
+  # Step 5: regenerated ODB code in the relevant projects (bpkg, bdep, brep):
   #
   ./odb.sh ~/work/build2/builds/gcc7/
 
+  # Step 6: finish toolchain update:
+  #
   BDEP_SYNC=0 b build2/ bpkg/ bdep/
   b build2/ bpkg/ bdep/ # Should be noop.
   \
@@ -895,7 +909,9 @@ distribution from \c{etc/stage} and add the pre-distributed packages
   \c{buildtab}s and build machines} but for stage. Some differences:
 
   Clean \c{buildtab}s (both \c{stage} and CI) by removing no longer relevant
-  configurations, moving some to \c{legacy}, etc.
+  configurations, moving some to \c{legacy}, etc. NOTE: we now keep the
+  same set of machines as public until next release so that we can build
+  public with stage for testing.
 
   More generally, this is the time to do sweeping changes such as renaming
   machines/configurations, adjusting classes, etc. This is also the time to
-- 
cgit v1.1