Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / mesa3d / b755f2f233e621d8fa066d5e7dfd1b24f8ecf46d / . / docs / releasing.html
blob: d650910075a601afa792f3c956fc98576b05454e [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
Emil Velikov0f8afde2017-01-19 15:35:38 +0000[diff] [blame]161 git checkout master
162 $EDITOR VERSION # bump the version number
163 git commit -as
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]164 git push origin X.Y-branchpoint X.Y
165</pre>
166
167<p>
168Now go to
169<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.
170</p>
171<p>
172Check for rare that there are no distribution breaking changes and revert them
173if needed. Extremely rare - we had only one case so far (see
174commit 2ced8eb136528914e1bf4e000dea06a9d53c7e04).
175</p>
176<p>
177Proceed to <a href="#release">release</a> -rc1.
178</p>
179
180<h1 id="prerelease">Pre-release announcement</h1>
181
182<p>
183It comes shortly after outstanding patches in the respective branch are pushed.
184Developers can check, in brief, what's the status of their patches. They,
185alongside very early testers, are strongly encouraged to test the branch and
186report any regressions.
187<br>
188It is followed by a brief period (normally 24 or 48 hours) before the actual
189release is made.
190</p>
191
192<h2>Terminology used</h2>
193<ul><li>Nominated</ul>
194<p>
195Patch that is nominated but yet to to merged in the patch queue/branch.
196</p>
197
198<ul><li>Queued</ul>
199<p>
200Patch is in the queue/branch and will feature in the next release.
201Barring reported regressions or objections from developers.
202</p>
203
204<ul><li>Rejected</ul>
205<p>
206Patch does not fit the
207<a href="submittingpatches.html#criteria" target="_parent">criteria</a> and
208is followed by a brief information.
209<br>
210The release maintainer is human so if you believe you've spotted a mistake do
211let them know.
212</p>
213
214<h2>Format/template</h2>
215<pre>
216Subject: [ANNOUNCE] Mesa X.Y.Z release candidate
217To: mesa-announce@...
218Cc: mesa-dev@...
219
220Hello list,
221
222The candidate for the Mesa X.Y.Z is now available. Currently we have:
223 - NUMBER queued
224 - NUMBER nominated (outstanding)
225 - and NUMBER rejected patches
226
227BRIEF SUMMARY OF CHANGES
228
229Take a look at section "Mesa stable queue" for more information.
230
231
232Testing reports/general approval
233--------------------------------
234Any testing reports (or general approval of the state of the branch) will be
235greatly appreciated.
236
237The plan is to have X.Y.Z this DAY (DATE), around or shortly after TIME.
238
239If you have any questions or suggestions - be that about the current patch
240queue or otherwise, please go ahead.
241
242
243Trivial merge conflicts
244-----------------------
245List of commits where manual intervention was required.
246Keep the authors in the CC list.
247
248commit SHA
249Author: AUTHOR
250
251 COMMIT SUMMARY
252
253 CHERRY PICKED FROM
254
255
256For example:
257
258commit 990f395e007c3204639daa34efc3049f350ee819
259Author: Emil Velikov &lt;emil.velikov@collabora.com&gt;
260
261 anv: automake: cleanup the generated json file during make clean
262
263 (cherry picked from commit 8df581520a823564be0ab5af7dbb7d501b1c9670)
264
265
266Cheers,
267Emil
268
269
270Mesa stable queue
271-----------------
272
273Nominated (NUMBER)
274==================
275
276AUTHOR (NUMBER):
277 SHA COMMIT SUMMARY
278
279For example:
280
281Dave Airlie (1):
282 2de85eb radv: fix texturesamples to handle single sample case
283
284
285Queued (NUMBER)
286===============
287
288AUTHOR (NUMBER):
289 COMMIT SUMMARY
290
291
292Rejected (NUMBER)
293=================
294
295Rejected (11)
296=============
297
298AUTHOR (NUMBER):
299 SHA COMMIT SUMMARY
300
301Reason: ...
302</pre>
303
304<h1 id="release">Making a new release</h1>
305
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]306<p>
307These are the instructions for making a new Mesa release.
308</p>
309
310<h3>Get latest source files</h3>
311<p>
312Ensure the latest code is available - both in your local master and the
313relevant branch.
314</p>
315
316<h3>Perform basic testing</h3>
317<p>
318Most of the testing should already be done during the
319<a href="#pickntest">cherry-pick</a> and
320<a href="#prerelease">pre-announce</a> stages.
321
322So we do a quick 'touch test'
323<ul>
324<li>make distcheck (you can omit this if you're not using --dist below)
325<li>scons (from release tarball)
326<li>the produced binaries work
327</ul>
328
329<p>
330Here is one solution that I've been using.
331</p>
332
333<pre>
334 git clean -fXd; git clean -nxd
335 read # quick cross check any outstanding files
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]336 export __version=`cat VERSION`
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]337 export __mesa_root=../
338 export __build_root=./foo
339 chmod 755 -fR $__build_root; rm -rf $__build_root
340 mkdir -p $__build_root &amp;&amp; cd $__build_root
341
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]342 $__mesa_root/autogen.sh --enable-llvm-shared-libs &amp;&amp; make -j2 distcheck
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]343
344 # Build check the tarballs (scons)
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]345 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]346
347 # Test the automake binaries
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]348 rm -rf cd mesa-$__version
349 tar -xaf mesa-$__version.tar.xz &amp;&amp; cd mesa-$__version
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]350 ./configure \
351 --with-dri-drivers=i965,swrast \
352 --with-gallium-drivers=swrast \
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]353 --with-vulkan-drivers=intel \
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]354 --enable-llvm-shared-libs \
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]355 --enable-gallium-llvm \
356 --enable-glx-tls \
357 --enable-gbm \
358 --enable-egl \
359 --with-egl-platforms=x11,drm,wayland
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]360 make -j2 &amp;&amp; DESTDIR=`pwd`/test make -j6 install
361 export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/
362 export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]363 export LIBGL_DEBUG=verbose
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]364 glxinfo | egrep -o "Mesa.*"
365 glxgears
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]366 es2_info | egrep "GL_VERSION|GL_RENDERER"
367 es2gears_x11
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]368 export LIBGL_ALWAYS_SOFTWARE=1
369 glxinfo | egrep -o "Mesa.*|Gallium.*"
370 glxgears
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]371 es2_info | egrep "GL_VERSION|GL_RENDERER"
372 es2gears_x11
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]373 export LIBGL_ALWAYS_SOFTWARE=1
374 export GALLIUM_DRIVER=softpipe
375 glxinfo | egrep -o "Mesa.*|Gallium.*"
376 glxgears
Emil Velikovf9959ca2016-11-28 17:18:06 +0000[diff] [blame]377 es2_info | egrep "GL_VERSION|GL_RENDERER"
378 es2gears_x11
379 # Smoke test DOTA2
380 unset LD_LIBRARY_PATH
381 unset LIBGL_DRIVERS_PATH
382 unset LIBGL_DEBUG
383 unset LIBGL_ALWAYS_SOFTWARE
384 export VK_ICD_FILENAMES=`pwd`/src/intel/vulkan/dev_icd.json
385 steam steam://rungameid/570 -vconsole -vulkan
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]386</pre>
387
388<h3>Update version in file VERSION</h3>
389
390<p>
391Increment the version contained in the file VERSION at Mesa's top-level, then
392commit this change.
393</p>
394
395<h3>Create release notes for the new release</h3>
396
397<p>
398Create a new file docs/relnotes/X.Y.Z.html, (follow the style of the previous
399release notes). Note that the sha256sums section of the release notes should
400be empty (TBD) at this point.
401</p>
402
403<p>
404Two scripts are available to help generate portions of the release notes:
405
406<pre>
407 ./bin/bugzilla_mesa.sh
408 ./bin/shortlog_mesa.sh
409</pre>
410
411<p>
412The first script identifies commits that reference bugzilla bugs and obtains
413the descriptions of those bugs from bugzilla. The second script generates a
414log of all commits. In both cases, HTML-formatted lists are printed to stdout
415to be included in the release notes.
416</p>
417
418<p>
419Commit these changes and push the branch.
420</p>
421<pre>
422 git push origin HEAD
423</pre>
424
425
426<h3>Use the release.sh script from xorg util-macros</h3>
427
428<p>
Emil Velikov2edc29a2016-11-16 18:25:41 +0000[diff] [blame]429Ensure that the mesa git tree is clean via <code>git clean -fXd</code> and
430start the release process.
431</p>
432<pre>
433 ../relative/path/to/release.sh . # append --dist if you've already done distcheck above
434</pre>
435
436<p>
437Pay close attention to the prompts as you might be required to enter your GPG
438and SSH passphrase(s) to sign and upload the files, respectively.
439</p>
440
441<h3>Add the sha256sums to the release notes</h3>
442
443<p>
444Edit docs/relnotes/X.Y.Z.html to add the sha256sums as availabe in the mesa-X.Y.Z.announce template. Commit this change.
445</p>
446
447<h3>Back on mesa master, add the new release notes into the tree</h3>
448
449<p>
450Something like the following steps will do the trick:
451</p>
452
453<pre>
454 git cherry-pick -x X.Y~1
455 git cherry-pick -x X.Y
456</pre>
457
458<p>
459Also, edit docs/relnotes.html to add a link to the new release notes, and edit
460docs/index.html to add a news entry. Then commit and push:
461</p>
462
463<pre>
464 git commit -as -m "docs: add news item and link release notes for X.Y.Z"
465 git push origin master X.Y
466</pre>
467
468
469<h1 id="announce">Announce the release</h1>
470<p>
471Use the generated template during the releasing process.
472</p>
473
474
475<h1 id="website">Update the mesa3d.org website</h1>
476
477<p>
478NOTE: The recent release managers have not been performing this step
479themselves, but leaving this to Brian Paul, (who has access to the
480sourceforge.net hosting for mesa3d.org). Brian is more than willing to grant
481the permission necessary to future release managers to do this step on their
482own.
483</p>
484
485<p>
486Update the web site by copying the docs/ directory's files to
487/home/users/b/br/brianp/mesa-www/htdocs/ with:
488<br>
489<code>
490sftp USERNAME,mesa3d@web.sourceforge.net
491</code>
492</p>
493
494
495<h1 id="bugzilla">Update Bugzilla</h1>
496
497<p>
498Parse through the bugreports as listed in the docs/relnotes/X.Y.Z.html
499document.
500<br>
501If there's outstanding action, close the bug referencing the commit ID which
502addresses the bug and mention the Mesa version that has the fix.
503</p>
504
505<p>
506Note: the above is not applicable to all the reports, so use common sense.
507</p>
508
509
510</div>
511</body>
512</html>