1= How to make releases
2
3== Release Candidates (RC)
4
5Release 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
209