Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / mesa3d / 64bcdf44c0c1bb1795879d54ed4c572bfc43eea5 / . / docs / releasing.html
blob: 946aaa4176512941898e1e48eb2cbb172c6c7a52 [file] [log] [blame]
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html lang="en">
3<head>
4 <meta http-equiv="content-type" content="text/html; charset=utf-8">
Emil Velikov028d29b2016-11-28 17:22:15 +0000[diff] [blame]5 <title>Releasing process</title>
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]6 <link rel="stylesheet" type="text/css" href="mesa.css">
7</head>
8<body>
9
10<div class="header">
11 <h1>The Mesa 3D Graphics Library</h1>
12</div>
13
14<iframe src="contents.html"></iframe>
15<div class="content">
16
17<h1>Releasing process</h1>
18
19<ul>
20<li><a href="#overview">Overview</a>
21<li><a href="#schedule">Release schedule</a>
22<li><a href="#pickntest">Cherry-pick and test</a>
23<li><a href="#branch">Making a branchpoint</a>
24<li><a href="#prerelease">Pre-release announcement</a>
25<li><a href="#release">Making a new release</a>
26<li><a href="#announce">Announce the release</a>
27<li><a href="#website">Update the mesa3d.org website</a>
28<li><a href="#bugzilla">Update Bugzilla</a>
29</ul>
30
31<h1 id="overview">Overview</h1>
32
33<p>
34This document uses the convention X.Y.Z for the release number with X.Y being
35the stable branch name.
36<br>
37Mesa provides feature and bugfix releases. Former use zero as patch version (Z),
38while the latter have a non-zero one.
39</p>
40
41<p>
42For example:
43</p>
44<pre>
45 Mesa 10.1.0 - 10.1 branch, feature
46 Mesa 10.1.4 - 10.1 branch, bugfix
47 Mesa 12.0.0 - 12.0 branch, feature
48 Mesa 12.0.2 - 12.0 branch, bugfix
49</pre>
50
51<h1 id="schedule">Release schedule</h1>
52
53<p>
54Releases should happen on Fridays. Delays can occur although those should be keep
55to a minimum.
56</p>
57
58<h2>Feature releases</h2>
59<ul>
60<li>Available approximatelly every three months.
61<li>Initial timeplan available 2-4 weeks before the planned branchpoint (rc1)
62on the mesa-announce@ mailing list.
63<li>A <a href="#prerelease">pre-release</a> announcement should be available
64approximatelly 24 hours before the final (non-rc) release.
65</ul>
66
67<h2>Stable releases</h2>
68<ul>
69<li>Normally available once every two weeks.
70<li>Only the latest branch has releases. See note below.
71<li>A <a href="#prerelease">pre-release</a> announcement should be available
72approximatelly 48 hours before the actual release.
73</ul>
74
75<p>
76Note: There is one or two releases overlap when changing branches. For example:
77<br>
78The final release from the 12.0 series Mesa 12.0.5 will be out around the same
79time (or shortly after) 13.0.1 is out.
80</p>
81
82<h1 id="pickntest">Cherry-picking and testing</h1>
83
84<p>
85Commits nominated for the active branch are picked as based on the
86<a href="submittingpatches.html#criteria" target="_parent">criteria</a> as
87described in the same section.
88
89<p>
90Maintainer is responsible for testing in various possible permutations of
91the autoconf and scons build.
92</p>
93
94<h2>Cherry-picking and build/check testing</h2>
95
96<p>Done continuously up-to the <a href="#prerelease">pre-release</a> announcement.</p>
97
98<p>
99As an exception, patches can be applied up-to the last ~1h before the actual
100release. This is made <strong>only</strong> with explicit permission/request,
101and the patch <strong>must</strong> be very well contained. Thus it cannot
102affect more than one driver/subsystem.
103</p>
104<p>
105Currently Ilia Mirkin and AMD devs have requested "permanent" exception.
106</p>
107
108
109<ul>
110<li>make distcheck, scons and scons check must pass
111<li>Testing with different version of system components - LLVM and others is also
112performed where possible.
113</ul>
114<p>
115Achieved by combination of local ad-hoc scripts and AppVeyor plus Travis-CI,
116the latter as part of their Github integration.
117</p>
118
119<h2>Regression/functionality testing</h2>
120
121<p>
122Less often (once or twice), shortly before the pre-release announcement.
123Ensure that testing is redone if Intel devs have requested an exception, as per above.
124</p>
125<ul>
126<li><em>no regressions should be observed for Piglit/dEQP/CTS/Vulkan on Intel platforms</em>
127<li><em>no regressions should be observed for Piglit using the swrast, softpipe
128and llvmpipe drivers</em>
129</ul>
130<p>
131Currently testing is performed courtesy of the Intel OTC team and their Jenkins CI setup. Check with the Intel team over IRC how to get things setup.
132</p>
133
134
135<h1 id="branch">Making a branchpoint</h1>
136
137<p>
138A branchpoint is made such that new development can continue in parallel to
139stabilisation and bugfixing.
140</p>
141
142<p>
143Note: Before doing a branch ensure that basic build and <code>make check</code>
144testing is done and there are little to-no issues.
145<br>
146Ideally all of those should be tackled already.
147</p>
148
149<p>
150Check if the version number is going to remain as, alternatively
151<code> git mv docs/relnotes/{current,new}.html </code> as appropriate.
152</p>
153
154<p>
155To setup the branchpoint:
156</p>
157<pre>
158 git checkout master # make sure we're in master first
159 git tag -s X.Y-branchpoint -m "Mesa X.Y branchpoint"
160 git checkout -b X.Y
161 git push origin X.Y-branchpoint X.Y
162</pre>
163
164<p>
165Now go to
166<a href="https://bugs.freedesktop.org/editversions.cgi?action=add&amp;product=Mesa" target="_parent">Bugzilla</a> and add the new Mesa version X.Y.
167</p>
168<p>
169Check for rare that there are no distribution breaking changes and revert them
170if needed. Extremely rare - we had only one case so far (see
171commit 2ced8eb136528914e1bf4e000dea06a9d53c7e04).
172</p>
173<p>
174Proceed to <a href="#release">release</a> -rc1.
175</p>
176
177<h1 id="prerelease">Pre-release announcement</h1>
178
179<p>
180It comes shortly after outstanding patches in the respective branch are pushed.
181Developers can check, in brief, what's the status of their patches. They,
182alongside very early testers, are strongly encouraged to test the branch and
183report any regressions.
184<br>
185It is followed by a brief period (normally 24 or 48 hours) before the actual
186release is made.
187</p>
188
189<h2>Terminology used</h2>
190<ul><li>Nominated</ul>
191<p>
192Patch that is nominated but yet to to merged in the patch queue/branch.
193</p>
194
195<ul><li>Queued</ul>
196<p>
197Patch is in the queue/branch and will feature in the next release.
198Barring reported regressions or objections from developers.
199</p>
200
201<ul><li>Rejected</ul>
202<p>
203Patch does not fit the
204<a href="submittingpatches.html#criteria" target="_parent">criteria</a> and
205is followed by a brief information.
206<br>
207The release maintainer is human so if you believe you've spotted a mistake do
208let them know.
209</p>
210
211<h2>Format/template</h2>
212<pre>
213Subject: [ANNOUNCE] Mesa X.Y.Z release candidate
214To: mesa-announce@...
215Cc: mesa-dev@...
216
217Hello list,
218
219The candidate for the Mesa X.Y.Z is now available. Currently we have:
220 - NUMBER queued
221 - NUMBER nominated (outstanding)
222 - and NUMBER rejected patches
223
224BRIEF SUMMARY OF CHANGES
225
226Take a look at section "Mesa stable queue" for more information.
227
228
229Testing reports/general approval
230--------------------------------
231Any testing reports (or general approval of the state of the branch) will be
232greatly appreciated.
233
234The plan is to have X.Y.Z this DAY (DATE), around or shortly after TIME.
235
236If you have any questions or suggestions - be that about the current patch
237queue or otherwise, please go ahead.
238
239
240Trivial merge conflicts
241-----------------------
242List of commits where manual intervention was required.
243Keep the authors in the CC list.
244
245commit SHA
246Author: AUTHOR
247
248 COMMIT SUMMARY
249
250 CHERRY PICKED FROM
251
252
253For example:
254
255commit 990f395e007c3204639daa34efc3049f350ee819
256Author: Emil Velikov &lt;emil.velikov@collabora.com&gt;
257
258 anv: automake: cleanup the generated json file during make clean
259
260 (cherry picked from commit 8df581520a823564be0ab5af7dbb7d501b1c9670)
261
262
263Cheers,
264Emil
265
266
267Mesa stable queue
268-----------------
269
270Nominated (NUMBER)
271==================
272
273AUTHOR (NUMBER):
274 SHA COMMIT SUMMARY
275
276For example:
277
278Dave Airlie (1):
279 2de85eb radv: fix texturesamples to handle single sample case
280
281
282Queued (NUMBER)
283===============
284
285AUTHOR (NUMBER):
286 COMMIT SUMMARY
287
288
289Rejected (NUMBER)
290=================
291
292Rejected (11)
293=============
294
295AUTHOR (NUMBER):
296 SHA COMMIT SUMMARY
297
298Reason: ...
299</pre>
300
301<h1 id="release">Making a new release</h1>
302
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]303<p>
304These are the instructions for making a new Mesa release.
305</p>
306
307<h3>Get latest source files</h3>
308<p>
309Ensure the latest code is available - both in your local master and the
310relevant branch.
311</p>
312
313<h3>Perform basic testing</h3>
314<p>
315Most of the testing should already be done during the
316<a href="#pickntest">cherry-pick</a> and
317<a href="#prerelease">pre-announce</a> stages.
318
319So we do a quick 'touch test'
320<ul>
321<li>make distcheck (you can omit this if you're not using --dist below)
322<li>scons (from release tarball)
323<li>the produced binaries work
324</ul>
325
326<p>
327Here is one solution that I've been using.
328</p>
329
330<pre>
331 git clean -fXd; git clean -nxd
332 read # quick cross check any outstanding files
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]333 export __version=`cat VERSION`
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]334 export __mesa_root=../
335 export __build_root=./foo
336 chmod 755 -fR $__build_root; rm -rf $__build_root
337 mkdir -p $__build_root &amp;&amp; cd $__build_root
338
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]339 $__mesa_root/autogen.sh --enable-llvm-shared-libs &amp;&amp; make -j2 distcheck
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]340
341 # Build check the tarballs (scons)
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]342 tar -xaf mesa-$__version.tar.xz &amp;&amp; cd mesa-$__version &amp;&amp; scons &amp;&amp; cd ..
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]343
344 # Test the automake binaries
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]345 rm -rf cd mesa-$__version
346 tar -xaf mesa-$__version.tar.xz &amp;&amp; cd mesa-$__version
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]347 ./configure \
348 --with-dri-drivers=i965,swrast \
349 --with-gallium-drivers=swrast \
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]350 --with-vulkan-drivers=intel \
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]351 --enable-llvm-shared-libs \
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]352 --enable-gallium-llvm \
353 --enable-glx-tls \
354 --enable-gbm \
355 --enable-egl \
356 --with-egl-platforms=x11,drm,wayland
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]357 make -j2 &amp;&amp; DESTDIR=`pwd`/test make -j6 install
358 export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/
359 export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]360 export LIBGL_DEBUG=verbose
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]361 glxinfo | egrep -o "Mesa.*"
362 glxgears
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]363 es2_info | egrep "GL_VERSION|GL_RENDERER"
364 es2gears_x11
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]365 export LIBGL_ALWAYS_SOFTWARE=1
366 glxinfo | egrep -o "Mesa.*|Gallium.*"
367 glxgears
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]368 es2_info | egrep "GL_VERSION|GL_RENDERER"
369 es2gears_x11
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]370 export LIBGL_ALWAYS_SOFTWARE=1
371 export GALLIUM_DRIVER=softpipe
372 glxinfo | egrep -o "Mesa.*|Gallium.*"
373 glxgears
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]374 es2_info | egrep "GL_VERSION|GL_RENDERER"
375 es2gears_x11
376 # Smoke test DOTA2
377 unset LD_LIBRARY_PATH
378 unset LIBGL_DRIVERS_PATH
379 unset LIBGL_DEBUG
380 unset LIBGL_ALWAYS_SOFTWARE
381 export VK_ICD_FILENAMES=`pwd`/src/intel/vulkan/dev_icd.json
382 steam steam://rungameid/570 -vconsole -vulkan
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]383</pre>
384
385<h3>Update version in file VERSION</h3>
386
387<p>
388Increment the version contained in the file VERSION at Mesa's top-level, then
389commit this change.
390</p>
391
392<h3>Create release notes for the new release</h3>
393
394<p>
395Create a new file docs/relnotes/X.Y.Z.html, (follow the style of the previous
396release notes). Note that the sha256sums section of the release notes should
397be empty (TBD) at this point.
398</p>
399
400<p>
401Two scripts are available to help generate portions of the release notes:
402
403<pre>
404 ./bin/bugzilla_mesa.sh
405 ./bin/shortlog_mesa.sh
406</pre>
407
408<p>
409The first script identifies commits that reference bugzilla bugs and obtains
410the descriptions of those bugs from bugzilla. The second script generates a
411log of all commits. In both cases, HTML-formatted lists are printed to stdout
412to be included in the release notes.
413</p>
414
415<p>
416Commit these changes and push the branch.
417</p>
418<pre>
419 git push origin HEAD
420</pre>
421
422
423<h3>Use the release.sh script from xorg util-macros</h3>
424
425<p>
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]426Ensure that the mesa git tree is clean via <code>git clean -fXd</code> and
427start the release process.
428</p>
429<pre>
430 ../relative/path/to/release.sh . # append --dist if you've already done distcheck above
431</pre>
432
433<p>
434Pay close attention to the prompts as you might be required to enter your GPG
435and SSH passphrase(s) to sign and upload the files, respectively.
436</p>
437
438<h3>Add the sha256sums to the release notes</h3>
439
440<p>
441Edit docs/relnotes/X.Y.Z.html to add the sha256sums as availabe in the mesa-X.Y.Z.announce template. Commit this change.
442</p>
443
444<h3>Back on mesa master, add the new release notes into the tree</h3>
445
446<p>
447Something like the following steps will do the trick:
448</p>
449
450<pre>
451 git cherry-pick -x X.Y~1
452 git cherry-pick -x X.Y
453</pre>
454
455<p>
456Also, edit docs/relnotes.html to add a link to the new release notes, and edit
457docs/index.html to add a news entry. Then commit and push:
458</p>
459
460<pre>
461 git commit -as -m "docs: add news item and link release notes for X.Y.Z"
462 git push origin master X.Y
463</pre>
464
465
466<h1 id="announce">Announce the release</h1>
467<p>
468Use the generated template during the releasing process.
469</p>
470
471
472<h1 id="website">Update the mesa3d.org website</h1>
473
474<p>
475NOTE: The recent release managers have not been performing this step
476themselves, but leaving this to Brian Paul, (who has access to the
477sourceforge.net hosting for mesa3d.org). Brian is more than willing to grant
478the permission necessary to future release managers to do this step on their
479own.
480</p>
481
482<p>
483Update the web site by copying the docs/ directory's files to
484/home/users/b/br/brianp/mesa-www/htdocs/ with:
485<br>
486<code>
487sftp USERNAME,mesa3d@web.sourceforge.net
488</code>
489</p>
490
491
492<h1 id="bugzilla">Update Bugzilla</h1>
493
494<p>
495Parse through the bugreports as listed in the docs/relnotes/X.Y.Z.html
496document.
497<br>
498If there's outstanding action, close the bug referencing the commit ID which
499addresses the bug and mention the Mesa version that has the fix.
500</p>
501
502<p>
503Note: the above is not applicable to all the reports, so use common sense.
504</p>
505
506
507</div>
508</body>
509</html>