doc/maintainers/how-to-make-releases.asciidoc

   1 = How to make releases
   2
   3 == Release Candidates (RC)
   4
   5 Release candidates are tagged off the 'master' branch as 'vX.Y.0-rcN'.
   6
   7 === Checklist
   8
   9 - Find Waffle's library version as defined by the CMake and Android files. Find
  10   it with grep. This version defines (1) the library's SONAME and SOVERSION in
  11   the ELF header and (2) the version advertised by pkg-config. This number is
  12   *important*.
  13
  14   $ git grep -E 'waffle_(major|minor|patch)_version.*[[:digit:]]'
  15
  16 - Set the library version to 'X.(Y-1).90' if this is the first RC.  For the
  17   duration of Waffle's RC phase, keep the library version strictly less than
  18   'X.Y.0'.  Bump it on each RC if you want, but don't bump it to 'X.Y.0' until
  19   you're ready to publish the 'vX.Y.0' tag.
  20
  21 - Commit release notes to 'doc/release-notes/waffle-X.Y.0.txt'.
  22
  23 - Use this toplevel heading in the release notes:
  24
  25   Waffle X.Y.0 Release Notes (draft)
  26   ==================================
  27
  28 - If this is not the first RC, then consider inserting a git shortlog that
  29   captures the changes since the previous RC.
  30
  31   Changes since X.Y.0-rc(N-1)
  32   ---------------------------
  33   `git shortlog`
  34
  35 - Clone the website if you haven't already.
  36
  37   $ web_work_tree=/whatever
  38   $ git clone ssh://git@github.com/waffle-gl/waffle-gl.github.io $web_work_tree
  39
  40 - Setup the shell for business.
  41
  42   $ wfl_work_tree=`git rev-parse --show-toplevel`
  43   $
  44   $ X=...
  45   $ Y=...
  46   $ Z=0
  47   $ RC=rc1
  48   $
  49   $ final_ver=$X.$Y.$Z
  50   $ ver=${final_ver}-${RC}
  51   $ tag=v${ver}
  52   $
  53   $ tmp_dir=$(mktemp -d)
  54   $ src_dir=$tmp_dir/waffle-$ver
  55   $ prefix=$tmp_dir/prefix
  56   $
  57   $ sums=waffle-$ver.sha256sums.asc
  58   $ src_ball=waffle-$ver.tar.xz
  59   $ src_sig=waffle-$ver.tar.asc
  60
  61 - Create a test tarball of 'master'.
  62
  63   $ cd $wfl_work_tree
  64   $ git archive --prefix="waffle-$ver/" master | xz > $tmp_dir/$src_ball
  65
  66 - Inspect the tarball contents.
  67
  68   $ cd $tmp_dir
  69   $ tar xf $src_ball
  70   $ find $src_dir
  71
  72 - Verify on Linux that the tarball can build everything (all platforms, the
  73   docs, the examples, etc).
  74
  75   - You should test the build with the CMake generator that is most likely to
  76     exhibit bugs and most likely to be chosen by the end user: that is,
  77     the Makefile generator. Don't use CMake's Ninja generator; it works too
  78     well, so you will be unaware of the Makefile bugs and thus unintentionally
  79     inflict pain on users.
  80
  81     $ cd $src_dir
  82     $ cmake \
  83         -DCMAKE_BUILD_TYPE=Release \
  84         -DCMAKE_INSTALL_PREFIX=$prefix \
  85         \
  86         -Dwaffle_has_glx=1 \
  87         -Dwaffle_has_x11_egl=1 \
  88         -Dwaffle_has_wayland=1 \
  89         -Dwaffle_has_gbm=1 \
  90         \
  91         -Dwaffle_build_manpages=1 \
  92         -Dwaffle_build_htmldocs=1 \
  93         -Dwaffle_build_examples=1 \
  94         .
  95     $ make -j4
  96     $ make check && echo PASS
  97
  98 - Run all functional tests for all Linux platforms.
  99   .
 100   My [chadv] preferred way to run the functional tests is to run them all in
 101   one pass. To do that, I setup my machine like below.
 102
 103   - Enable render nodes by adding 'drm.rnodes=1' to the kernel cmdline. This
 104     will allow the GBM tests to run even when another graphics client (such as
 105     the X server) owns the DRI device.
 106
 107   - Boot and start X. This will allow the 'glx' and 'x11_egl' tests to run.
 108
 109   - Start Weston as a windowed X client. This will allow the 'wayland' tests to
 110     run.
 111
 112     $ DISPLAY=:0 weston
 113
 114   - Finally run the tests.
 115
 116     $ export DISPLAY=:0
 117     $ make check-func && echo PASS
 118
 119 - Install Waffle. Quickly inspect the set of installed files.
 120
 121   $ make install
 122   $ cd $prefix
 123   $ find .
 124
 125 - Inspect the installed man pages.
 126
 127   $ export MANPATH=$prefix/share/man
 128   $ man waffle
 129   $ man wflinfo
 130   $ man waffle_config_choose
 131
 132 - Inspect the install html docs too.
 133
 134   $ $BROWSER $prefix/share/doc/waffle*/html/index.html
 135
 136 - Verify that the examples build and run.
 137
 138   $ cd $prefix/share/doc/waffle*/examples
 139   $ make -f Makefile.example
 140   $ ./simple-x11-egl
 141   $ ./gl_basic --platform=glx --api=gl
 142
 143 - If you're feeling generous, verify that Piglit works when built and ran
 144   against the installed Waffle in '$prefix'.
 145
 146 - If you have a Mac development environment, please test that too.  If you
 147   don't, then ask someone on the mailing list to test a release candidate on
 148   a Mac before the final release.
 149
 150 - Same as previous bullet but s/Mac/Android/.
 151
 152 - Does all look good? Great! Publish the release tag.
 153
 154   $ cd $wfl_work_tree
 155   $ git tag -s $tag -m "Waffle $tag"
 156   $ git push origin master $tag
 157
 158 - Publish the new manpages to the website.
 159
 160   $ cd $web_work_tree
 161   $ git checkout master
 162   $ git status
 163   $ rsync -va -delete $prefix/share/doc/waffle*/html/man/ $web_work_tree/man/
 164   $ git add -A
 165   $ git commit -s -m "man: Update for Waffle $tag"
 166
 167 - Copy the template below to the appropriate location in 'releases.html'.
 168
 169   <li><a name="${ver}" href="#${ver}"><h3>${ver}</h3></a>
 170     <ul>
 171       <li>Date: YYYY-MM-DD</li>
 172       <li><a href="files/release/waffle-$ver/waffle-$ver.txt">Release Notes</a></li>
 173       <li><a href="files/release/waffle-$ver/$src_ball">$src_ball</a></li>
 174       <li><a href="files/release/waffle-$ver/$src_sign" type="text/plain">$src_sign</a></li>
 175       <li><a href="files/release/waffle-$ver/$sums" type="text/plain">$sums</a></li>
 176     </ul>
 177   </li>
 178
 179 - Locally commit the release files to the website.
 180
 181   $ mkdir -p $web_work_tree/files/release/waffle-$ver
 182   $ cd $web_work_tree/files/release/waffle-$ver
 183   $ mv $tmp_dir/$src_ball .
 184   $ xz --stdout --decompress $src_ball | gpg --armor --detach-sign -o $src_sign
 185   $ cp $wfl_work_tree/doc/release-notes/waffle-$final_ver.txt waffle-$ver.txt
 186   $ sha256sum * | gpg --armor --clearsign > $sums
 187   $
 188   $ cd $web_work_tree
 189   $ git add -A
 190   $ git commit -s -m "release: Publish Waffle $rel_version"
 191
 192 - Inspect the local release page's appearance. Validate the links to the
 193   release files.
 194
 195   $ cd $web_work_tree
 196   $ $BROWSER releases.html
 197
 198 - Does all look good? Great! Publish the release files.
 199
 200   $ git tag -s $tag -m "Waffle $tag"
 201   $ git push origin master $rel_tag
 202
 203 - Announce the release candidate.
 204
 205   $ cd $work_tree
 206   $ dev-tools/wfl-make-release-announcement $tag > announce-$ver.eml
 207   $ vim announce-$ver.eml
 208   $ sendmail -t < announce-$ver.eml