misc/release.md

   1 # Making a release
   2
   3 * assuming some variables
   4   - `VERSION=1.3`
   5   - `RELEASE=1.3.0`
   6
   7 * perform a sanity check
   8   - check the BTS
   9   - check that the nightly bench is OK
  10   - `make xml-validate-local` (see below for `why3session.dtd`)
  11   - check `CHANGES.md`
  12   - run `make detect-unused` and remove unused files
  13   - run `make update-doc-png` and check if some pictures need to be updated
  14   - run `make doc/latex/manual.pdf` and check the manual
  15   - run `make dist` and check the content of `distrib/why3-X.X.X.tar.gz`
  16   - check `lib/why3/META.in` (e.g., against `EXTPKGS` in `Makefile.in`)
  17   - update `opam/why3{,-ide,-coq}.opam` with correct dependencies on external packages
  18   - check the gallery, especially the new examples (see below)
  19   - run the manual job `trywhy3-extra` to build Alt-Ergo for TryWhy3 if needed (see below)
  20
  21 * check/update authors and copyright
  22   - update the content of the About dialog in `src/ide/gconfig.ml`
  23     around lines 680-700
  24   - update the `copyright` field in `doc/conf.py` around line 50
  25   - update `doc/foreword.rst`
  26   - update `src/trywhy3/trywhy3.html`
  27   - check headers, modify `misc/header.txt` and run `make headers` if needed
  28   - commit as needed
  29
  30 * perform and push the release commit
  31   - create a branch if needed, `git checkout -b bugfix/v$VERSION master`
  32   - or just move to it, `git checkout bugfix/v$VERSION`
  33   - update the first line of `configure.in` using `$RELEASE`
  34   - update the `version` and `release` fields in `doc/conf.py` around line 60
  35   - add the release date to `CHANGES.md`
  36   - update the date in `doc/index.rst`
  37   - make a last commit
  38     ```
  39     git commit -am "Version $RELEASE"
  40     git tag $RELEASE
  41     git push
  42     git push --tags
  43     ```
  44
  45 * prepare and upload the archive to https://gitlab.inria.fr/why3/releases
  46   - `make dist`
  47   - get the Git repository of the releases and move to it
  48     ```
  49     cp .../distrib/why3-$RELEASE.tar.gz releases/
  50     git add releases/why3-$RELEASE.tar.gz
  51     git commit -m "Add release $RELEASE."
  52     git push
  53     ```
  54
  55 * update the repository, if this is the most recent release
  56   - forward the `stable` branch of the Why3 repository:
  57     `git push origin bugfix/v$VERSION:stable`
  58   - run the manual job `trywhy3` in the corresponding pipeline on the `stable` branch
  59   - merge back the changes to the `master` branch
  60   - update the first line of `configure.in` using `$RELEASE+git`,
  61     commit and push the change to `master`
  62
  63 * update the website, if this is the most recent release
  64   - get the sources from https://gitlab.com/why3project/why3project.gitlab.io
  65   - update `index.html` with the new url for download
  66   - update `.gitlab-ci.yml` if the Alt-Ergo worker was rebuilt (job `trywhy3-extra`)
  67   - update `why3session.dtd` with the current version
  68   - wait for completion of the pipeline of the `stable` branch
  69   - commit and push the changes, to trigger an update of the website
  70
  71 * prepare and upload the OPAM packages to https://github.com/ocaml/opam-repository
  72   - reinitialize the repository if not fresh:
  73     ```
  74     git remote add upstream https://github.com/ocaml/opam-repository.git
  75     git fetch upstream
  76     git reset --hard upstream/master
  77     ```
  78   - `mkdir packages/why3/why3.$RELEASE packages/why3-coq/why3-coq.$RELEASE packages/why3-ide/why3-ide.$RELEASE`
  79   - copy the `opam` files from the directories of the previous release
  80   - reconcile with the changes from Why3's repository
  81   - update the `url` section of all three `opam` files
  82   - push and make a pull request on Github
  83   - check whether some downstream developments were broken
  84     and update the pull request accordingly
  85
  86 * produce the Why3 part of Toccata gallery, if this is the most recent release
  87   - update the git repository of Toccata
  88   - have `GALLERYDIR` point to the sub-directory `gallery` of that git repository,
  89     e.g., `export GALLERYDIR=.../toccata/web/gallery`
  90   - in Why3 sources, run `make gallery`;
  91     it exports to `$GALLERYDIR` all the Why3 programs for which there is a session
  92   - now move to the directory `$GALLERYDIR`
  93   - check the examples that are currently untracked in the Toccata repository
  94     and update `examples.rc` accordingly
  95   - put the directories of the broken examples in `.gitignore`
  96   - run `make`; this requires to have installed the newly released Why3;
  97     the presence of `.prehtml.new` files means that something went wrong,
  98     hopefully only for non-Why3 examples
  99   - `git add` the new files
 100     (except for the `.html` files, which should go in `web/gallery/.gitignore`)
 101   - commit and push the modified files
 102
 103 * announce the release using the features of `CHANGES.md`