summaryrefslogtreecommitdiff
path: root/doc/release.cli
blob: 78d505f746fe917c65a8f6dc77ce8fe2560f774a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
// file      : doc/release.cli
// license   : MIT; see accompanying LICENSE file

"\title=Release Process"

// NOTES
//
// - Maximum <pre> line is 70 characters.
//

"\h1|Table of Contents|"
"\$TOC$"

"
\h0#process|Process|

Review the state and services list (currently on paper) for any new additions.
Consider how/when they are updated/tested during the release process.

@@ We have switched to a single configuration for the entire toolchain
   (plus -libs).

@@ We currently have an issue in that \c{queue} builds \c{public} using
\c{public} \c{buildtabs} (since it's querying \c{public} brep) which means
existing packages are not tested with new build configurations. But maybe
that's correct, conceptually.

\h1#stage|Stage|

The staging repository is completely independent which means it must contain
all the \c{build2} dependencies (plus a few extra packages for testing; see
the \c{etc/stage} script for the complete list). This in turn means that if
any of these dependencies are in the unreleased state, then they should go
through the applicable steps in this section (e.g., updating of \c{NEWS}, etc)
and then be queued and published (effectively released) as part of the
\c{build2} release. Generally, however, we should strive to not unnecessarily
bundle the release of dependencies with the release of \c{build2} to keep the
process as streamlined as possible. In fact, we now have \c{queue.stage} (see
\c{etc/stage-queue}) which is the place for such \"extra packages for
testing\".

\N|When unbundling the release of a dependency we need to remove its
distribution from \c{etc/stage} and add the pre-distributed packages
(for example, from \c{public}) to \c{staging/repository/1/}.|

\b{Pre-Conditions:}

\ul|

\li|Current \c{stage} build is clean.||

\h#stage-public|Build public with stage toolchain|

  Before starting the release process we rebuild all the packages in the
  public repository with the stage toolchain in order to detect any
  regressions.

  \ol|

  \li|Review \c{brep} commit log for any potential issues and upgrade \c{brep}
      on public to latest staged version. See the detailed instructions in
      \c{private}.|

  \li|Compare stage and public \c{buildtabs} and identify public machines that
      are no longer present on stage. We aim to at least have a build machine
      for the primary compiler for each operating system.|

  \li|Temporarily add missing machines to stage build bots.|

  \li|Uncomment controller URL for public repository in \c{devel-config} and
      \c{stage-config} build bot configuratons. Regenerate and reboot.|

  \li|Confirm all the primary configurations are being built.|

  \li|Wait for the builds to complete (note that there may be unbuilt
      entries for secondary configurations) and compare public toolchain
      build results to stage for regressions. See the detailed instructions
      in \c{private}.||

\h#copy|Update copyright if new year|

  Use the \c{git/copyright} script. See the script header for instructions.

  Note that most of (all?) our project have been converted to the automatic
  copyright update notification via a pre-commit hook. So perhaps this step
  can be removed.

\h#install-times|Update install script times.|

  See \c{private/install/build2-times.txt} for instructions.

\h#etc|Update \c{etc/git/modules}|

  Review for any new modules. Remove \c{etc/} and \c{private/} from
  \c{modules} to reduce noise during stat.

\h#review|Review \c{@@}|

  Review \c{etc/review} for new modules. Then review \c{@@} notes:

  \
  etc/review | less -R
  \

  At least look for \c{@@\ TMP}

  \
  etc/review | grep TMP
  \

\h#review-db|Review database schema changes|

  Review database schema changelog differences in \c{bpkg}, \c{bdep}, and
  \c{brep} compared to the previous release (tag) for any schema/data
  migration that may be required (if something is missing, then it would also
  have to be tested).

\h#news|Update \c{NEWS} files|

  Update in all projects (including dependencies) that will have a release
  version.

  See \c{etc/stage} for the complete list.


\h#packaging|Release \c{packaging/} dependencies|

  Release dependencies that have the snapshot version as described in
  \l{https://github.com/build2-packaging/README#version-and-release-management
  Version and Release Management}.

  Also, consider upgrading the \c{curl/ca-certificates-curl}.

  \N|Maybe this should be done during queuing? Why do we release (but not
     publish) these now and other dependencies later? Maybe so that we can
     stage them one more time?|


\h#dependencies|Finalize all other dependencies|

  Make sure all other unreleased dependencies listed in \c{etc/stage} are
  ready to be released (\c{NEWS}, etc). Effectively, the only remaining step
  should be to change the version.

  Do this in the dependency order and finish each off with:

  \
  git pull
  bdep sync -fura && bdep test -ar
  \

  For some it may make sense to go straight to release; see
  \l{#version-release Change to release version}.


\h#upgrade-dep|Upgrade dependencies|

  Upgrade all dependencies in the \c{build2} toolchain build:

  \
  etc/upgrade
  \

  Or, if released ODB on the previous step, update \c{libodb*} version
  constraint using \c{etc/version}, commit, and then:

  \
  # Step 0: make sure b, bpkg, bdep are runnable.

  # Step 1a: pull CLI compiler and build it, make sure runnable.
  # Step 1b: 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

  # Step 4: trigger header regeneration (ignore ODB version errors).
  #
  BDEP_SYNC=0 b --match-only ~/work/build2/builds/gcc7/

  # 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.
  \

  Then push \c{build2} repositories.


\h#hello|Update \c{hello/} projects|

  These projects should closely track the output of \c{bdep-new(1)}. The
  recommended procedure is to generate a new project with the same name and
  then review/resolve the differences with \c{diff\ -ru}.

  Every change in these projects must be accompanied by a revision increment
  and a re-tag. This should be managed with \c{bdep-release(1)}:

  \
  # make changes
  git add .
  bdep release --revision --show-push
  # review commit
  git push ...
  \

  Once done, make sure the latest \c{libhello} revision is on stage, run the
  \c{intro} scripts, and review any changes in the output (this information
  will be helpful on the next step):

  \
  cd etc

  script -qc ./intro2-tldr intro2-tldr.out && sed -i -e 's/\r//g' intro2-tldr.out
  diff -u intro2-tldr.orig intro2-tldr.out  # Or use gitk.
  mv intro2-tldr.out intro2-tldr.orig


  script -qc ./intro2-tour intro2-tour.out && sed -i -e 's/\r//g' intro2-tour.out
  diff -u intro2-tour.orig intro2-tour.out  # Or use gitk.
  mv intro2-tour.out intro2-tour.orig
  \

\h#doc|Review documentation|

  Review the following documentation for (1) sample output changes and (2)
  still being relevant/making sense. Also (3) check the \c{NEWS} files for
  anything new worth mentioning.

  \N|Ideally this should be done during development but it's easy to forget.
     Also, check if there is any new documentation that has been added that is
     not on the below list.|

  \ul|

    \li|Install guide: 1 & 2 (also review \c{build2-toolchain} commit log).|

    \li|Toolchain introduction: 1, 2 & 3 (use \c{intro} script output for 2).|

    \li|Packaging gude: 2 & 3 (also \c{bdep-new}-generated buildfiles).|

    \li|Introduction in the build system manual: 1 (uses \c{bdep-new(1)}
        output).|

    \li|Testscript manual: 1.||


\h#submod|Update all submodules|

  Make sure all working trees are clean. Review \c{sub_modules} in
  \c{etc/git/modules} for any missing new modules, then:

  \N|\c{etc/} and \c{private/} need to be committed manually.|

  \
  ./modup.sh
  ./commit.sh # If changes.
  ./push.sh

  cd build2-toolchain

  git submodule update --remote --checkout
  git submodule foreach git submodule update --init --recursive

  git status  # There should only be 'new commits'; see README-GIT

  git commit -a -m \"Update submodules\"
  git push
  \

\h#stage-machines|Update \c{stage} \c{buildtab}s and build machines|

  NOTE: may want to keep old machines around for public testing (since we use
  existing public buildtabs, none of the new machines will be used).

  Note: normally, we try to do all of this as part of normal development
  (e.g., when adding new machines, etc).

  Review \c{stage} \c{buildtab} for any configurations to drop (for example,
  an intermediate version of a compiler), classes to adjust (\c{legacy},
  \c{default}, \c{latest}, etc).

  Based on these changes update \c{stage} CI \c{buildtab}, which is a subset
  of the \c{stage} configurations (and is a base for the \c{queue}/\c{public}
  configurations).

  Review deployed machines against the updated \c{stage} \c{buildtab} and
  remove those that are no longer used:

  \
  cd private/buildos/

  grep '.*' .../brep-buildtab | cut -d' ' -f1 | sort -u
  ./ls-machines -c stage -c devel

  ~/work/buildos/remove-machine <host> <machine>
  \

  Also review deployed machines against the latest available versions and
  upgrade those that are not the latest:

  \
  cd private/buildos/

  ./ls-machines -l \"/btrfs/$(whoami)/machines/default/\" | sort
  ./ls-machines -c stage -c devel

  ~/work/build2/buildos/upload-machine <host> .../new-ver .../old-ver
  \


\h#restage|Restage|

  Confirm \c{stage} and \c{devel} \c{buildos} images, hardware-specific
  configurations are the same.

  Review \c{staging/0/} and \c{staging/repository/1/} for anything stray.

  If no upgrade is possible from the previous version, uncomment errors in
  install scripts (and add a note to restore after the release).

  Enable extra packages for testing in \c{etc/stage} script.

  Restage and upgrade \c{brep} by performing the following steps:

  \ol|

  \li|Disable building of all repositories on \c{stage} by adding the
      \c{buildable:no} field at the end of each line in \c{loadtab}.|

  \li|Restage with \c{baseutils}/\c{mingw} regeneration:

      \
      etc/stage -b
      \

      Consider restaging queue for good measure.

      \
      etc/stage-queue
      \

  |

  \li|While build machines are bootstrapping, upgrade \c{brep} on \c{stage},
      sync latest \c{buildtab}s but do not restart the web server.|

  \li|Once all build machines have bootstrapped, enabling build of all
      repositories and restart the web server. To check bootstrap progress:

     \
     ./ls-machines -b stage -c stage -c devel
     \

  ||

  Verify \c{stage} build is clean, nothing is unbuilt.


\h#test-extra|Perform extra testing|

  CI: (check for any new repositories in github.com/build2/)\n
  \n
  \c{libauto-symexport}\n
  \c{hello-thrift}\n
  \c{assembler-with-cpp}\n

  Test \c{cxx20-modules-examples} (see \c{test} script).

  Test any third-party/demos (\c{build2-dynamic-module-demo},
  \c{cherimcu}, \c{boost-dependency}).

  Test on ARM Mac (run tests for \c{libbutl/build2/bpkg/bdep}).

  Test build system modules (especially standard pre-installed).

  Test old toolchain version (can fetch and build old packages from
  \c{queue.stage}; add dummy package if all require to be released toolchain).


\h#install-stage|Test install scripts|

  Test \l{https://stage.build2.org/0/ \c{stage} install scripts}, including
  upgrading, as described in \c{private/install/testing.txt}.

  Perform necessary upgrades, if any, and test on ad hoc test machines
  (\c{test-*}).

  Also test \c{bootstrap-mingw.bat} and \c{bootstrap.sh} (preferably on
  something less mainstream like FreeBSD) since not exercised as part of
  install.

\h1#queue|Queue|

\b{Pre-Conditions:}

\ul|

\li|Final \c{stage} build is clean.|

\li|Build with the \c{queue} toolchain is inactive.||


\h#queue-repo|Review \c{queue} repository|

  Pull, review, and clean the \c{queue} \c{git} repository for any stale
  packages or anything (ownership, etc) that may conflict with packages being
  released.

  Also clean toolchain distribution:

  \
  rm -rf cppget.org/queue/0/*
  \

\h#version-release|Change to release version|

  Change to the release version in all the packages being released and tag
  (see \c{etc/stage} for the list). Use \c{bdep-release(1)} unless a custom
  versioning/tagging scripts are used:

  \
  git pull
  bdep release --no-open --show-push [--alpha|--beta]
  # review commit, run update (in case anything comitted is pre-generated)
  git push ...
  \

  Do this in the dependency order and finish each off with:

  \
  bdep sync -fura && bdep update
  \

  For the \c{build2} packages (commit but don't push after each step if
  required):

  \ul|

    \li|Close schema versions in \c{bpkg}, \c{bdep}, and \c{brep}.|

    \li|Change \c{LIBBUILD2_STAGE} in \c{build2/libbuild2/config.hxx.in} to \c{false}.|

    \li|If necessary, update minimum \c{build2} and \c{bpkg} version
        requirements in projects generated by \c{bdep-new}. \b{This must be
        done if created projects use new features.}

        \N|Why shouldn't we always do this for simplicity? Maybe because then
        we cannot run tests using \c{public} services?

        Also if we change this in toolchain packages, the below upgrade steps
        will break since there is no continuity. Perhaps do it in two stages:
        first change version to final, upgrade, then change toolchain
        dependencies to final, upgrade again? But then nobody involed in
        development will be able to pull and upgrade. Maybe KISS and keep
        it pre-release.||

    \li|Change version by updating \c{etc/version} (including with new modules
        and/or new dependencies, but keep pre-release in minimum toolchain
        version requirements) and then executing:

        \
        etc/version
        ./commit.sh
        git -C build2-toolchain commit --amend # \"Change version to X.Y.Z\"
        \

        Note that \c{libbuild2-*} modules (e.g., \c{libbuild2-hello}) are
        independently versioned but may still need to update minimum toolchain
        version requirements (see below).|

    \li|Tag by executing \c{tag.sh\ <version>}.|


    \li|Release all standard pre-installed build system modules. Update
        minimum toolchain version requirements.

        \
        bdep release --no-open --show-push
        \

        Also release \c{libbuild2-hello} (it's not standard pre-installed
        but it gets published).

        |

    \li|Regenerate documentation in each package (including standard
        pre-installed build system modules, use \c{BDEP_SYNC=0}).|

    \li|Upgrade all dependencies in configure-only mode by executing
        \c{etc/upgrade\ -c}.

        Avoid this (see above): If the \c{build2}/\c{bpkg} requirements in the
        manifests have been bumped to the version being released, then first
        bootstrap the build system and update \c{bpkg}/\c{bdep} (might have to
        hack their generated \c{version.hxx} to disable constraint checking;
        also if you forget \c{BDEP_SYNC=0} it will most likely hose the build
        configuration).

        \
        BDEP_SYNC=0 b-boot build2/build2/
        BDEP_SYNC=0 b bpkg/ bdep/
        \

    |

    \li|Trigger regeneration of version files (might require several runs
        to \"close off\"):

        \
        BDEP_SYNC=0 b --match-only ~/work/build2/builds/gcc7-asan/
        \

        If using GCC prior to 8 then might also need explicit version target
        upgrades:

        \
        BDEP_SYNC=0 b ~/work/build2/builds/gcc7-asan/.../hxx{version}
        \

    |

    \li|Regenerate ODB in relevant packages passing upgraded configuration
        path explicitly (\c{bdep} is not runnable):

       \
       ./odb.sh ~/work/build2/builds/gcc7-asan/
       \

    |

    \li|Finish upgrading all dependencies by executing in the upgraded
    configuration:

       \
       BDEP_SYNC=0 b ~/work/build2/builds/gcc7-asan/

       b build2/ bpkg/ bdep/

       # Update standard pre-installed build system modules.
       \

    |


    \li|Update other \c{libbuild2-*} modules if required.||

  Verify key tests pass (in particular, the \c{bdep} tests will now be running
  against \c{public} services):

  \
  b test: build2/ bpkg/ bdep/
  b test: bpkg/ config.bpkg.test.remote=true
  b test: libbuild2-hello/libbuild2-hello-tests/

  # Test standard pre-installed build system modules.
  \

  \N|We could have queued after this step before preparing
     \c{build2-toolchain}. However, splitting this seems to only increase
     complexity without any major benefits (it's not hard to update submodules
     and regenerated \c{build2-toolchain} if there are any issues with
     packages). Plus we can start testing install scripts, etc.|

  Next push the above changes and update all submodules in
  \c{build2-toolchain}:

  \
  ./push.sh

  # Push (with tags) standard pre-installed build system modules.

  cd build2-toolchain

  git submodule update --remote --checkout

  git status  # There should only be 'new commits'; see README-GIT

  git commit -a -m \"Update submodules\"
  \

  As well as (commit after each step if required):

  \ul|

    \li|Regenerate documentation in each package inside as well as in
        \c{build2-toolchain} itself. @@ \c{libbuild-kconfig} not configured
        out of tree? Or maybe it gets updated automatically during dist?|

    \li|Update ODB by copying relevant files from the previous step (trust me,
        this is the easy way for now). Make sure all \c{*-odb.*} are copied!|

    \li|Change \c{build2_repo} in \c{build2-toolchain} \c{buildfile} to
    \c{queue}.||

  Finally, push the changes:

  \
  git push
  \

\h#queuing|Queue|

   Prepare packages and the toolchain distribution (disable extra packages
   first if any were enabled in the \c{etc/stage} script):

   \
   etc/stage -q -b
   \

   Sort non-alpha packages from \c{cppget.org/queue/1/alpha/} into appropriate
   sections (we could probably automate this similar to \c{bdep-release(1)}).
   Also check if any of them are already in \c{public}.

   Note also that we assume all the packages already have the corresponding
   ownership information either in \c{queue} or \c{public}. However, if any
   new packages were added, then that will have to be added as well.

   Commit and push queue repository:

   \
   cd cppget.org/queue/
   git add .
   git ci -m \"Queue build2 toolchain X.Y.Z\"
   git push
   \

   If queued package manifests contain new values, then the
   \c{bpkg-rep-publish} script will fail to create repository due to unknown
   manifest values. To resolve this we temporarily add (to \c{crontab})
   \c{--ignore-unknown} and make a note to restore.

   Also change \c{--min-bpkg-version} from previous to current release
   (not the one being released).

\h#build-public|Verify queued packages build with \c{public}|

   This makes sure that the new version can be built with the old toolchain.

   While all the packages should build (except perhaps \c{libhello} which,
   being based on the latest \c{bdep-new(1)} output, may use new features),
   some tests may fail. In particular, we will be running \c{bpkg} tests using
   a previous version of the build system and \c{bdep} tests also using a
   previous version of \c{bpkg}. None of that is or will be supported. So
   for now we manually review all the failed builds for anything suspicious
   and in the future we may skip tests if the tool versions mismatch.


\h#install-queue|Test install scripts|

  Test \l{https://download.build2.org/queue/ \c{queue} install scripts}. Here
  we just smoke-test each script on its \"primary\" platform and make sure
  \c{queue} URLs/repositories are used.


\h#upgrade-brep-bpub|Upgrade \c{brep} and \c{bpub} on \c{cppget.org}|

  Upgrade \c{brep} and \c{bpub} using the queued toolchain according
  to \c{private/brep-bpub-upgrade.txt}.

  After upgrade, drop all package builds for \c{public} and \c{queue} and
  verify there are no regressions. This makes sure that the \c{brep} services
  in the new version are usable with the old toolchain. If there are issues,
  they have to be fixed by publishing/queuing revisions.

  \N|The \c{bdep} tests that exercise CI and publishing services do it in the
  simulation mode. To properly test that these services are compatible with
  the old version of the toolchain we would need to CI/publish a real test
  package manually.|


\h#start-queue|Start \c{queue} builds|

  Update \c{queue} \c{buildtab} based on the \c{stage} CI \c{buildtab}
  (normally just a copy sans the sanitized toolchain configurations).

  \N|Note that the \c{queue} \c{buildtab} is shared between \c{public} and
     \c{queue} builds. As a result, after this update, \c{public} build hosts
     may not have some of the new (or renamed) build machines.

     This also means that if the \c{buildtab} contains anything new (options,
     etc) that are incompatible with \c{public}, then they should only be
     enabled later, when upgrading \c{public} \c{buildtab} (make a note if
     that's the case).|

  Adjust \c{stage} and \c{devel} build host configurations (both \c{*-config}
  and hardware classes) to enable the \c{queue} toolchain. Shift most
  instances from \c{stage} to \c{queue} in the hardware class-specific
  configurations. Regenerate affected configurations and reboot build hosts:

  \
  cd private/buildos/

  ./regen
  ./po-hosts -r -c stage -c devel
  \

  Verify both \c{queue} and \c{public} builds with the queued toolchain,
  fixing any breakages with revisions, moving to legacy, and/or queuing
  replacements. We can only proceed further once we have a \"resolution\"
  for every (newly) broken package.

  \N|If public has been built with the staged toolchain, rebuilding of the
     public repository (which takes days) can be omitted.|

\h#stop-queue|Stop \c{queue} builds|

  Adjust \c{stage} and \c{devel} build host configurations to disable the
  \c{queue} toolchain (comment out). Regenerate affected configurations and
  reboot build hosts as on the previous step (or poweroff until stage
  reopening).

\h1#public|Public|

\b{Pre-Conditions:}

\ul|

\li|A \"resolution\" is queued or published for every (newly) broken package.||

\h#public-machines|Update \c{public} \c{buildtab}s and build machines|

  Poweroff the old set of \c{public} build hosts:

  \
  ./po-hosts -c public
  \

  Update \c{public} \c{buildtab}s based on the \c{queue} \c{buildtab}
  (normally just a copy).

  Adjust build host configurations (hardware classes, etc) and add/remove
  new/old build hosts.

  Replace the \c{public} \c{buildos} image on \c{build-cache} with the
  one for \c{stage}.

  Comment out the \c{public} toolchain in the build host configuration
  (effectively making it a no-toolchain configuration), regenerate, and power
  on the new set of \c{public} build hosts.


  @@ See new sync scripts for this step: Review deployed machines against the
  updated \c{public} \c{buildtab} and remove those that are no longer used:

  \
  cd private/buildos/

  grep '.*' .../brep-buildtab | cut -d' ' -f1 | sort -u
  ./ls-machines -c public

  ~/work/build2/buildos/remove-machine <host> <machine>
  \

  Then move now legacy machines to the \"legacy\" build host:

  \
  grep 'legacy' .../brep-buildtab | cut -d' ' -f1 | sort -u
  \

  Also review deployed machines against the latest available versions and
  upgrade those that are not the latest:

  \
  cd private/buildos/

  ./ls-machines -l \"/btrfs/$(whoami)/machines/default/\" | sort
  ./ls-machines -c public

  ~/work/build2/buildos/upload-machine <host> .../new-ver .../old-ver
  \

  Finally, add any new machines:

  \
  grep -v 'legacy' .../brep-buildtab | cut -d' ' -f1 | sort -u
  \

  Uncomment the \c{public} toolchain in the build host configuration and
  regenerate. The only remaining step is to reboot (not yet):

  \
  ./po-hosts -r -c public
  \

\h#pub-dist|Publish distribution|

  Change \c{build2_repo} in \c{build2-toolchain} \c{buildfile} to \c{public},
  commit, and publish the distribution (this also cleans/disables the
  \c{queue} toolchain):

  \
  etc/stage -p
  \

\h#pub-pkg|Publish packages|

  @@ Need to add --min-bpkg-version 0.13.0

  Move packages (manually for now) from the \c{queue} to \c{public} \c{git}
  repository, including ownership information. Move old/replaced/FTB
  packages either to legacy or delete.

  Commit everything (see the commit log for procedure @@ this needs
  automation) and push (which should trigger auto-publish). Note: commit and
  push both \c{queue} and \c{public} \c{git} repositories.

  Note that once published, the existing install instructions/download
  links are no longer usable, so do not linger (in fact, may make sense
  to update Download and Install pages before publishing packages and
  only sync them immediately after).

\h#start-public|Start \c{public} builds|

  Reboot \c{public} build hosts. They should next bootstrap and proceed
  with building all packages.

  Once all the machines have bootstrapped, submit a test CI task.

\h#install-public|Test install scripts|

  Test \l{https://download.build2.org/ \c{public} install scripts}. Here
  we just smoke-test each script on its \"primary\" platform and make sure
  \c{public} URLs/repositories are used.

  Also test building an old package with the previous version of the
  toolchain.

\h#web|Update web|

  \ul|

  \li|Write release notes, use placeholder for announcement URL (or guess).
      Add link from the \c{doc.cli}. Add blog entry.|

  \li|Add any new FAQ entries or any other updates (main page, etc). Any new
      documentation to link from the Doc page?|

  \li|Update the Download page.

      \
      cat `ls -1 cppget.org/public/0/X.Y.Z/*.sha256`
      \

  |

  \li|Update the Install page.

      \
      cat cppget.org/public/0/toolchain.sha256
      \

  |

  \li|Regenerate documentation in \c{private/} for all hosts:

      \
      cd private/

      cd <host>/www/
      ./cli.sh
      \

  |

  \li|Test locally, publish, and test remote:

      \
      cd private/
      ./publish --dry-run
      ./publish
      \

  ||


\h#ann|Announce|

  \ul|

  \li|Write and send the announcement to the mailing lists.

      \
      cat `ls -1 cppget.org/public/0/X.Y.Z/*.sha256`
      \

      Add \c{reply-to:} header for \c{users@} announcement.|

  \li|Patch (or verify) the announcement URL in release notes, re-publish.|

  \li|Announce on reddit, slack, and other relevant places.|

  \li|Add links to reddit discussions to release notes.||

\h#tag|Commit, tag, and push the rest.|

   Tag \c{build2-toolchain}:

   \
   cd build2-toolchain
   git tag -a vX.Y.Z -m \"Tag version X.Y.Z\"
   git push --follow-tags
   \

   Add \c{etc/} and \c{private/} back to \c{modules} in \c{etc/git/modules}
   (essentially reverse \l{#etc Update \c{etc/git/modules}}).

   Finalize changes, commit, tag, and push \c{style/}, \c{etc/}, and
   \c{private/}.

   Snapshot \c{buildos} subvolumes:

   \
   btrfs subvolume snapshot buildos-3 buildos-3-X.Y.Z
   btrfs subvolume snapshot buildos-6 buildos-6-X.Y.Z
   \

\h1#reopen|Reopen|

\h#version-snapshot|Change to snapshot version|

  Change to the snapshot version in all the released packages. Use
  \c{bdep-release(1)} unless a custom versioning script is used:

  \
  bdep release --open --show-push [--open-*]
  # review commit
  git push ...
  \

  Essentially, the same steps as in \l{#version-release Change to
  release version} (but no tagging).

  Revert changes to install scripts if upgrade was disabled.

\h#stage-machines-reopen|Update \c{stage} \c{buildtab}s and build machines|

  Essentially, the same steps as in \l{#public-machines Update \c{public}
  \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. 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
  rebalance machines across available hosts.

\h#restage-reopen|Restage|

  Make symlinks for the new version in \c{private/baseutils} (for both
  \c{baseutils} and \c{mingw}; the idea is that we will start with those and
  maybe upgrade later).

  Review \c{etc/stage} for any packages to enabled/disable.

  Then cleanup and restage:

  \
  rm -r staging/0/*
  rm -r staging/repository/1/*/

  etc/stage -b
  \

\h#start-stage|Start \c{stage} builds|

  Reboot \c{stage} build hosts. They should next bootstrap and proceed with
  building all the staged packages. Make sure all the builds of the new
  development snapshot are successful and there is nothing unbuilt.

  Upgrade \c{brep} on \c{stage}.

  Review \c{etc/stage-queue} and restage queue.stage:

  \
  rm -r staging/repository/1/*/

  etc/stage-queue
  \

\h#commit-reopen|Commit and push \c{etc/} and \c{private/}.|

  Commit and push changes to \c{etc/} and \c{private/}.


\h1#upgrade|Upgrade|

\h#upgrade-baseutils|Upgrade \c{baseutils}|

  Check for abnormalities in new package sizes. Restage:

  \
  rm -r staging/0/*

  etc/stage -b
  \

  Remember to update the GCC version in the stage \c{buildtab}s for the
  configuration that uses \c{mingw} package.

\h#upgrade-db-migration|Cleanup database migrations|

  Drop old database migration code. Keep migration entries for two previous
  versions for \c{bpkg} and \c{bdep} and for one previous version for
   \c{brep}.

\h#upgrade-buildos|Upgrade \c{buildos}|

  See \c{bootstrap.txt} for the procedure. Start with the \c{devel}
  configuration and upgrade \c{stage} after testing.

\h#upgrade-build-machines|Upgrade build machines|

  Check every major compiler and OS if a new version is available.

\h#upgrade-packages|Upgrade third-party packages|

  Consider upgrading to new upstream versions in \c{packaging/}.

  Also, bundled \c{libodb}, \c{libsqlite3}, and \c{libpkg-config} in
  \c{libbutl}.

\h#upgrade-projects|Upgrade own projects|

  Adjust own projects to use any newly available features.

\h#upgrade-bdep-new|Upgrade \c{bdep-new}|

  Adjust \c{bdep-new}-generated projects to use any newly available features.


\h1#re-review|Re-review \c{@@}|

  Review \c{@@} notes (in case some should be fixed after the release):

  \
  etc/review | less -R
  \

  At least look for \c{@@\ TMP}

  \
  etc/review | grep TMP
  \

\h1#plan|Plan|

Plan the next release and update the project roadmap.
"