TODO
====

@@ Local Clang test is broken and disabled, using FreeBSD for Clang testing

Notes
=====

* Be very careful with submodules if fixing anything, remember to update
  build2-toolchain.


Setup
=====

* Make symlinks to development b, bpkg in /usr/local/bin/, used as the latest
  toolchain.

* Set passwordless sudo, logins to freebsd, cppget1, rbook (Mac OS)

  For Mac OS:
    echo "boris ALL=(ALL) NOPASSWD:ALL" >>/etc/sudoers

- Boot cppget1, freebsd VMs, make sure data/time is correct.

+ Copy prerequisites into build2-X.Y/, generate sha256 sums in BINARY (-b)

+ Build new prerequisites (if any) on local, freebsd (install to /usr/local).

+ If new preprequisites/version, need to update manifests.

Prelude
=======

+ Remove etc/ from modules in etc/git/modules.

+ Review '@@' items [note: etc, private excluded]

  etc/review | less -R

+ Need to make sure Intro is still accurate wrt output, etc. Use -s switch
  to etc/intro to compare:

  etc/intro -s `pwd`/hello/repository/1/

+ Increment version to final.

  * Need to update versions/dates for man generation (cli.sh in build2,
    bpkg, brep, and built2-toolchain).

  * Review manifests for any other changes (new entries/files, etc).

+ Close schema versions, review schema changlog difference from previous
  release (tag) for any data migration that may be required (@@ would also
  need to test this; see upgrade test).

+ Need to update submodules? Remember to push first.

+ Need to regenerate ODB files, CLI documentation, in build2-toolchin!

+ Update everything:

  b libbutl/ build2/ libbpkg/ bpkg/ brep/ build2-toolchain-default/

- Run tests for each project:

  * b 'test(libbutl/ libbpkg/)'

  * Manually in build2/

  * Manually in bpkg/; test (valgrind/asan), publish, test remote with -v,
    FreeBSD tools:

    ./test.sh -v --remote --fetch fetch --fetch-option --no-verify-peer \
      --tar bsdtar --sha256 sha256-freebsd

  * Update cppget repository (existing packages, not publishing yet):

    @@ What is the purpose of this step? It will mess up upgrade test
    below.

    -t /home/boris/work/build2/etc1/install/0.2.0 -e queue

    cd cppget.org
    git -C repository status
    ./update repository/1/

    This might not work in the early stage (backwards-incompatible)

    ./test -c cxx \
    -c config.cxx.loptions=-L/usr/local/lib \
    -c config.cxx.poptions="-I/usr/include/apache2 -I/usr/include/apr-1.0" \
      repository/1/

  * Test dev integration of brep/ on hello and cppget repos

    First check if Apache2 configuration needs updating (INSTALL-DEV). Then
    from build2/ work root:

    # This will have broken links since we are not running it as /pkg/hello.
    #
    brep/migrate/brep-migrate --recreate
    brep/load/brep-load hello/brep-loader-home.conf
    sudo /etc/init.d/apache2 restart

    brep/migrate/brep-migrate --recreate
    brep/load/brep-load cppget.org/brep-loader-home.conf
    sudo /etc/init.d/apache2 restart

    If need to drop the entire database, one way to do it is by executing:

    DROP OWNED BY <user>;

Procession
==========

- Generate distribution (use -t for toolchain-only, without brep). The
  result is placed into the queue.

  etc/dist 2>&1 | tee dist.log

- @@ Would be nice to test packages for missing files, etc., before upgrade.

- Test upgrade from previous version (replace Y in 0.Y.0).

  etc/test-upgrade -c cxx \
    -c config.cxx.loptions=-L/usr/local/lib \
    -c config.cxx.poptions="-I/usr/include/apache2 -I/usr/include/apr-1.0" \
    /home/boris/work/build2/etc1/install/0.Y.0

- Update and test hello repository

  cd hello
  for d in hello libhello libprint libformat repository; do \
    git -C $d status; done
  ./release -a

- Test Intro steps on the local hello repository

  etc/intro `pwd`/hello/repository/1/

- Publish hello repository, commit but don't push.

  [We need to publish now because etc/test uses it.]

  @@ Ideally we would want to stage it.

  ./release -p

- Test Intro steps on the remote hello repository

  etc/intro https://build2.org/pkg/1/hello/

- Stage queue to cppget.org

  etc/stage --dry-run
  etc/stage

- Regenerate other cppget.org sections with the new toolchain

  cd cppget.org
  git -C repository status
  ./update -e queue repository/1/

- Determine the earliest supported backwards-compatible toolchain (see
  requires: in manifests), update etc/test

- Test

  etc/test 2>&1 | tee test.log
  grep -i warning test.log

- Upgrade brep on build2.org (via package/queue upgrade if possible),
  verify works.

  Backup configs if changed:

  cd private/
  scp -r lists.build2.org:/home/brep/config lists.build2.org/home/brep/

- Move packages from queue to alpha, regenerate repositories.

  ./update repository/1/

- Publish to production (build2.org/cppget.org).

  etc/publish

- Test production and save a copy of toolchain in etc1/install/X.Y.Z

  etc/install -t -i "etc1/install/`cat build2-toolchain/version`" \
    https://download.build2.org/0.Y/build2-toolchain-0.Y.0.tar.gz \
    https://pkg.cppget.org/1/alpha

- Upgrade brep on cppget.org (via package/alpha upgrade if possible),
  verify works.

  Note that here we also have queue:

  install/bin/brep-migrate -n brep_queue
  install/bin/brep-load -n brep_queue config/brep-queue-load.conf

  Backup configs if changed:

  cd private/
  scp -r lists.cppget.org:/home/brep/config lists.cppget.org/home/brep/

- Tag (review tag_modules)

  etc/tag
  ./push.sh

- Commit and push cppget.org, hello git repositories

Release
=======

- Update style/ submodule in private/

- Write release notes, use placeholder for announcement URL. Add link to
  the doc page.

- Any new FAQ entries or any other updates (main page, etc)?

- Update download page.

- Regenerate (./cli.sh) all hosts.

- Test local, publish, test production:

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

- Write and send announcements

  Remember upgrade instructions.

  cat `ls -1 *.sha256`

- Patch the announcement URL in release notes, re-publish.

- Announce on reddit and other places (doc/ann).

Postlude
========

- Need to regenerate/republish hello/ repository?

- Increment and open schema versions. Maybe not. Maybe we should only do that
  when there is a model change.

- Increment project versions to alpha1, open master for business

- Commit changes to etc/, add it back to etc/git/modules.