Blame - docs/releasing.html - platform/external/mesa3d

blob: b5a9a5c85bf7ba7208b8e1f708755af8f80198af [file] [log] [blame]

Emil Velikov	2edc29a	2016-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 Velikov	028d29b	2016-11-28 17:22:15 +0000	[diff] [blame]	5	<title>Releasing process</title>
Emil Velikov	2edc29a	2016-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>
				34	This document uses the convention X.Y.Z for the release number with X.Y being
				35	the stable branch name.
				36	<br>
				37	Mesa provides feature and bugfix releases. Former use zero as patch version (Z),
				38	while the latter have a non-zero one.
				39	</p>
				40
				41	<p>
				42	For 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>
				54	Releases should happen on Fridays. Delays can occur although those should be keep
				55	to a minimum.
				56	</p>
				57
				58	<h2>Feature releases</h2>
				59	<ul>
Eric Engestrom	077879c	2017-02-26 23:58:03 +0000	[diff] [blame]	60	<li>Available approximately every three months.
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	61	<li>Initial timeplan available 2-4 weeks before the planned branchpoint (rc1)
				62	on the mesa-announce@ mailing list.
				63	<li>A <a href="#prerelease">pre-release</a> announcement should be available
Eric Engestrom	077879c	2017-02-26 23:58:03 +0000	[diff] [blame]	64	approximately 24 hours before the final (non-rc) release.
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	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
Eric Engestrom	077879c	2017-02-26 23:58:03 +0000	[diff] [blame]	72	approximately 48 hours before the actual release.
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	73	</ul>
				74
				75	<p>
				76	Note: There is one or two releases overlap when changing branches. For example:
				77	<br>
				78	The final release from the 12.0 series Mesa 12.0.5 will be out around the same
				79	time (or shortly after) 13.0.1 is out.
				80	</p>
				81
				82	<h1 id="pickntest">Cherry-picking and testing</h1>
				83
				84	<p>
				85	Commits nominated for the active branch are picked as based on the
				86	<a href="submittingpatches.html#criteria" target="_parent">criteria</a> as
				87	described in the same section.
				88
				89	<p>
				90	Maintainer is responsible for testing in various possible permutations of
				91	the 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>
				99	As an exception, patches can be applied up-to the last ~1h before the actual
				100	release. This is made <strong>only</strong> with explicit permission/request,
				101	and the patch <strong>must</strong> be very well contained. Thus it cannot
				102	affect more than one driver/subsystem.
				103	</p>
				104	<p>
				105	Currently 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
				112	performed where possible.
				113	</ul>
				114	<p>
				115	Achieved by combination of local ad-hoc scripts and AppVeyor plus Travis-CI,
				116	the latter as part of their Github integration.
				117	</p>
Emil Velikov	ccb89e7	2017-03-15 17:34:26 +0000	[diff] [blame^]	118	<p>
				119	<strong>Note:</strong> If a patch in the current queue needs any additional
				120	fix(es), then they should be squashed together.
				121	<br>
				122	The commit messages and the <code>cherry picked from</code> tags must be preserved.
				123	</p>
				124	<p>
				125	This should be noted in the <a href="#prerelease">pre-announce</a> email.
				126	<pre>
				127	git show b10859ec41d09c57663a258f43fe57c12332698e
				128
				129	commit b10859ec41d09c57663a258f43fe57c12332698e
				130	Author: Jonas Pfeil &ltpfeiljonas@gmx.de&gt
				131	Date: Wed Mar 1 18:11:10 2017 +0100
				132
				133	ralloc: Make sure ralloc() allocations match malloc()'s alignment.
				134
				135	The header of ralloc needs to be aligned, because the compiler assumes
				136	...
				137
				138	(cherry picked from commit cd2b55e536dc806f9358f71db438dd9c246cdb14)
				139
				140	Squashed with commit:
				141
				142	ralloc: don't leave out the alignment factor
				143
				144	Experimentation shows that without alignment factor gcc and clang choose
				145	...
				146
				147	(cherry picked from commit ff494fe999510ea40e3ed5827e7818550b6de126)
				148	</pre>
				149	</p>
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	150
				151	<h2>Regression/functionality testing</h2>
				152
				153	<p>
				154	Less often (once or twice), shortly before the pre-release announcement.
				155	Ensure that testing is redone if Intel devs have requested an exception, as per above.
				156	</p>
				157	<ul>
				158	<li><em>no regressions should be observed for Piglit/dEQP/CTS/Vulkan on Intel platforms</em>
				159	<li><em>no regressions should be observed for Piglit using the swrast, softpipe
				160	and llvmpipe drivers</em>
				161	</ul>
				162	<p>
				163	Currently 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.
				164	</p>
				165
				166
				167	<h1 id="branch">Making a branchpoint</h1>
				168
				169	<p>
				170	A branchpoint is made such that new development can continue in parallel to
				171	stabilisation and bugfixing.
				172	</p>
				173
				174	<p>
				175	Note: Before doing a branch ensure that basic build and <code>make check</code>
				176	testing is done and there are little to-no issues.
				177	<br>
				178	Ideally all of those should be tackled already.
				179	</p>
				180
				181	<p>
				182	Check if the version number is going to remain as, alternatively
				183	<code> git mv docs/relnotes/{current,new}.html </code> as appropriate.
				184	</p>
				185
				186	<p>
				187	To setup the branchpoint:
				188	</p>
				189	<pre>
				190	git checkout master # make sure we're in master first
				191	git tag -s X.Y-branchpoint -m "Mesa X.Y branchpoint"
				192	git checkout -b X.Y
Emil Velikov	0f8afde	2017-01-19 15:35:38 +0000	[diff] [blame]	193	git checkout master
				194	$EDITOR VERSION # bump the version number
				195	git commit -as
Emil Velikov	1d104f9	2017-01-26 19:26:13 +0000	[diff] [blame]	196	cp docs/relnotes/{X.Y,X.Y+1}.html # copy/create relnotes template
				197	git commit -as
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	198	git push origin X.Y-branchpoint X.Y
				199	</pre>
				200
				201	<p>
				202	Now go to
				203	<a href="https://bugs.freedesktop.org/editversions.cgi?action=add&product=Mesa" target="_parent">Bugzilla</a> and add the new Mesa version X.Y.
				204	</p>
				205	<p>
Emil Velikov	383e8e2	2017-02-20 19:27:49 +0000	[diff] [blame]	206	Check that there are no distribution breaking changes and revert them if needed.
				207	For example: files being overwritten on install, etc. Happens extremely rarely -
				208	we had only one case so far (see commit 2ced8eb136528914e1bf4e000dea06a9d53c7e04).
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	209	</p>
				210	<p>
				211	Proceed to <a href="#release">release</a> -rc1.
				212	</p>
				213
				214	<h1 id="prerelease">Pre-release announcement</h1>
				215
				216	<p>
				217	It comes shortly after outstanding patches in the respective branch are pushed.
				218	Developers can check, in brief, what's the status of their patches. They,
				219	alongside very early testers, are strongly encouraged to test the branch and
				220	report any regressions.
				221	<br>
				222	It is followed by a brief period (normally 24 or 48 hours) before the actual
				223	release is made.
				224	</p>
				225
				226	<h2>Terminology used</h2>
				227	<ul><li>Nominated</ul>
				228	<p>
				229	Patch that is nominated but yet to to merged in the patch queue/branch.
				230	</p>
				231
				232	<ul><li>Queued</ul>
				233	<p>
				234	Patch is in the queue/branch and will feature in the next release.
				235	Barring reported regressions or objections from developers.
				236	</p>
				237
				238	<ul><li>Rejected</ul>
				239	<p>
				240	Patch does not fit the
				241	<a href="submittingpatches.html#criteria" target="_parent">criteria</a> and
				242	is followed by a brief information.
				243	<br>
				244	The release maintainer is human so if you believe you've spotted a mistake do
				245	let them know.
				246	</p>
				247
				248	<h2>Format/template</h2>
				249	<pre>
				250	Subject: [ANNOUNCE] Mesa X.Y.Z release candidate
				251	To: mesa-announce@...
				252	Cc: mesa-dev@...
				253
				254	Hello list,
				255
				256	The candidate for the Mesa X.Y.Z is now available. Currently we have:
				257	- NUMBER queued
				258	- NUMBER nominated (outstanding)
				259	- and NUMBER rejected patches
				260
				261	BRIEF SUMMARY OF CHANGES
				262
				263	Take a look at section "Mesa stable queue" for more information.
				264
				265
				266	Testing reports/general approval
				267	--------------------------------
				268	Any testing reports (or general approval of the state of the branch) will be
				269	greatly appreciated.
				270
				271	The plan is to have X.Y.Z this DAY (DATE), around or shortly after TIME.
				272
				273	If you have any questions or suggestions - be that about the current patch
				274	queue or otherwise, please go ahead.
				275
				276
				277	Trivial merge conflicts
				278	-----------------------
				279	List of commits where manual intervention was required.
				280	Keep the authors in the CC list.
				281
				282	commit SHA
				283	Author: AUTHOR
				284
				285	COMMIT SUMMARY
				286
				287	CHERRY PICKED FROM
				288
				289
				290	For example:
				291
				292	commit 990f395e007c3204639daa34efc3049f350ee819
				293	Author: Emil Velikov <emil.velikov@collabora.com>
				294
				295	anv: automake: cleanup the generated json file during make clean
				296
				297	(cherry picked from commit 8df581520a823564be0ab5af7dbb7d501b1c9670)
				298
				299
				300	Cheers,
				301	Emil
				302
				303
				304	Mesa stable queue
				305	-----------------
				306
				307	Nominated (NUMBER)
				308	==================
				309
				310	AUTHOR (NUMBER):
				311	SHA COMMIT SUMMARY
				312
				313	For example:
				314
				315	Dave Airlie (1):
				316	2de85eb radv: fix texturesamples to handle single sample case
				317
				318
				319	Queued (NUMBER)
				320	===============
				321
				322	AUTHOR (NUMBER):
				323	COMMIT SUMMARY
				324
Emil Velikov	ccb89e7	2017-03-15 17:34:26 +0000	[diff] [blame^]	325	For example:
				326
				327	Jonas Pfeil (1):
				328	ralloc: Make sure ralloc() allocations match malloc()'s alignment.
				329	Squashed with
				330	ralloc: don't leave out the alignment factor
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	331
				332	Rejected (NUMBER)
				333	=================
				334
				335	Rejected (11)
				336	=============
				337
				338	AUTHOR (NUMBER):
				339	SHA COMMIT SUMMARY
				340
				341	Reason: ...
				342	</pre>
				343
				344	<h1 id="release">Making a new release</h1>
				345
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	346	<p>
				347	These are the instructions for making a new Mesa release.
				348	</p>
				349
				350	<h3>Get latest source files</h3>
				351	<p>
				352	Ensure the latest code is available - both in your local master and the
				353	relevant branch.
				354	</p>
				355
				356	<h3>Perform basic testing</h3>
				357	<p>
				358	Most of the testing should already be done during the
				359	<a href="#pickntest">cherry-pick</a> and
				360	<a href="#prerelease">pre-announce</a> stages.
				361
				362	So we do a quick 'touch test'
				363	<ul>
				364	<li>make distcheck (you can omit this if you're not using --dist below)
				365	<li>scons (from release tarball)
				366	<li>the produced binaries work
				367	</ul>
				368
				369	<p>
				370	Here is one solution that I've been using.
				371	</p>
				372
				373	<pre>
				374	git clean -fXd; git clean -nxd
				375	read # quick cross check any outstanding files
Emil Velikov	f9959ca	2016-11-28 17:18:06 +0000	[diff] [blame]	376	export __version=`cat VERSION`
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	377	export __mesa_root=../
				378	export __build_root=./foo
				379	chmod 755 -fR $__build_root; rm -rf $__build_root
				380	mkdir -p $__build_root && cd $__build_root
				381
Emil Velikov	f9959ca	2016-11-28 17:18:06 +0000	[diff] [blame]	382	$__mesa_root/autogen.sh --enable-llvm-shared-libs && make -j2 distcheck
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	383
Emil Velikov	f9b18d5	2017-02-01 08:42:14 +0000	[diff] [blame]	384	# Build check the tarballs (scons, linux)
				385	tar -xaf mesa-$__version.tar.xz && cd mesa-$__version
				386	scons
				387	cd .. && rm -rf mesa-$__version
				388
				389	# Build check the tarballs (scons, windows/mingw)
				390	tar -xaf mesa-$__version.tar.xz && cd mesa-$__version
				391	scons platform=windows toolchain=crossmingw
				392	cd .. && rm -rf mesa-$__version
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	393
				394	# Test the automake binaries
Emil Velikov	f9959ca	2016-11-28 17:18:06 +0000	[diff] [blame]	395	tar -xaf mesa-$__version.tar.xz && cd mesa-$__version
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	396	./configure \
				397	--with-dri-drivers=i965,swrast \
				398	--with-gallium-drivers=swrast \
Emil Velikov	f9959ca	2016-11-28 17:18:06 +0000	[diff] [blame]	399	--with-vulkan-drivers=intel \
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	400	--enable-llvm-shared-libs \
Emil Velikov	b3b4156	2017-02-07 15:53:14 +0000	[diff] [blame]	401	--enable-llvm \
Emil Velikov	f9959ca	2016-11-28 17:18:06 +0000	[diff] [blame]	402	--enable-glx-tls \
				403	--enable-gbm \
				404	--enable-egl \
				405	--with-egl-platforms=x11,drm,wayland
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	406	make -j2 && DESTDIR=`pwd`/test make -j6 install
Emil Velikov	652e367	2017-02-01 09:31:56 +0000	[diff] [blame]	407	__glxinfo_cmd='glxinfo 2>&1 \| egrep -o "Mesa.\|Gallium.\|.*dri\.so"'
				408	__glxgears_cmd='glxgears 2>&1 \| grep -v "configuration file"'
				409	__es2info_cmd='es2_info 2>&1 \| egrep "GL_VERSION\|GL_RENDERER\|.*dri\.so"'
				410	__es2gears_cmd='es2gears_x11 2>&1 \| grep -v "configuration file"'
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	411	export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/
				412	export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/
Emil Velikov	f9959ca	2016-11-28 17:18:06 +0000	[diff] [blame]	413	export LIBGL_DEBUG=verbose
Emil Velikov	652e367	2017-02-01 09:31:56 +0000	[diff] [blame]	414	eval $__glxinfo_cmd
				415	eval $__glxgears_cmd
				416	eval $__es2info_cmd
				417	eval $__es2gears_cmd
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	418	export LIBGL_ALWAYS_SOFTWARE=1
Emil Velikov	652e367	2017-02-01 09:31:56 +0000	[diff] [blame]	419	eval $__glxinfo_cmd
				420	eval $__glxgears_cmd
				421	eval $__es2info_cmd
				422	eval $__es2gears_cmd
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	423	export LIBGL_ALWAYS_SOFTWARE=1
				424	export GALLIUM_DRIVER=softpipe
Emil Velikov	652e367	2017-02-01 09:31:56 +0000	[diff] [blame]	425	eval $__glxinfo_cmd
				426	eval $__glxgears_cmd
				427	eval $__es2info_cmd
				428	eval $__es2gears_cmd
Emil Velikov	f9959ca	2016-11-28 17:18:06 +0000	[diff] [blame]	429	# Smoke test DOTA2
				430	unset LD_LIBRARY_PATH
				431	unset LIBGL_DRIVERS_PATH
				432	unset LIBGL_DEBUG
				433	unset LIBGL_ALWAYS_SOFTWARE
				434	export VK_ICD_FILENAMES=`pwd`/src/intel/vulkan/dev_icd.json
				435	steam steam://rungameid/570 -vconsole -vulkan
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	436	</pre>
				437
				438	<h3>Update version in file VERSION</h3>
				439
				440	<p>
				441	Increment the version contained in the file VERSION at Mesa's top-level, then
				442	commit this change.
				443	</p>
				444
				445	<h3>Create release notes for the new release</h3>
				446
				447	<p>
				448	Create a new file docs/relnotes/X.Y.Z.html, (follow the style of the previous
				449	release notes). Note that the sha256sums section of the release notes should
				450	be empty (TBD) at this point.
				451	</p>
				452
				453	<p>
				454	Two scripts are available to help generate portions of the release notes:
				455
				456	<pre>
				457	./bin/bugzilla_mesa.sh
				458	./bin/shortlog_mesa.sh
				459	</pre>
				460
				461	<p>
				462	The first script identifies commits that reference bugzilla bugs and obtains
				463	the descriptions of those bugs from bugzilla. The second script generates a
				464	log of all commits. In both cases, HTML-formatted lists are printed to stdout
				465	to be included in the release notes.
				466	</p>
				467
				468	<p>
				469	Commit these changes and push the branch.
				470	</p>
				471	<pre>
				472	git push origin HEAD
				473	</pre>
				474
				475
Emil Velikov	0f988ad	2017-03-15 17:34:25 +0000	[diff] [blame]	476	<h3>Use the release.sh script from xorg <a href="https://cgit.freedesktop.org/xorg/util/modular/">util-modular</a></h3>
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	477
				478	<p>
Emil Velikov	7956203	2017-03-15 17:34:24 +0000	[diff] [blame]	479	Start the release process.
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	480	</p>
				481	<pre>
				482	../relative/path/to/release.sh . # append --dist if you've already done distcheck above
				483	</pre>
				484
				485	<p>
				486	Pay close attention to the prompts as you might be required to enter your GPG
				487	and SSH passphrase(s) to sign and upload the files, respectively.
				488	</p>
				489
				490	<h3>Add the sha256sums to the release notes</h3>
				491
				492	<p>
Eric Engestrom	077879c	2017-02-26 23:58:03 +0000	[diff] [blame]	493	Edit docs/relnotes/X.Y.Z.html to add the sha256sums as available in the mesa-X.Y.Z.announce template. Commit this change.
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	494	</p>
				495
				496	<h3>Back on mesa master, add the new release notes into the tree</h3>
				497
				498	<p>
				499	Something like the following steps will do the trick:
				500	</p>
				501
				502	<pre>
				503	git cherry-pick -x X.Y~1
				504	git cherry-pick -x X.Y
				505	</pre>
				506
				507	<p>
				508	Also, edit docs/relnotes.html to add a link to the new release notes, and edit
				509	docs/index.html to add a news entry. Then commit and push:
				510	</p>
				511
				512	<pre>
				513	git commit -as -m "docs: add news item and link release notes for X.Y.Z"
				514	git push origin master X.Y
				515	</pre>
				516
				517
				518	<h1 id="announce">Announce the release</h1>
				519	<p>
				520	Use the generated template during the releasing process.
				521	</p>
				522
				523
				524	<h1 id="website">Update the mesa3d.org website</h1>
				525
				526	<p>
Emil Velikov	e280a6b	2017-02-10 12:51:22 +0000	[diff] [blame]	527	As the hosting was moved to freedesktop, git hooks are deployed to update the
				528	website. Manually check that it is updated 5-10 minutes after the final <code>git push</code>
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	529	</p>
				530
Emil Velikov	2edc29a	2016-11-16 18:25:41 +0000	[diff] [blame]	531	<h1 id="bugzilla">Update Bugzilla</h1>
				532
				533	<p>
				534	Parse through the bugreports as listed in the docs/relnotes/X.Y.Z.html
				535	document.
				536	<br>
				537	If there's outstanding action, close the bug referencing the commit ID which
				538	addresses the bug and mention the Mesa version that has the fix.
				539	</p>
				540
				541	<p>
				542	Note: the above is not applicable to all the reports, so use common sense.
				543	</p>
				544
				545
				546	</div>
				547	</body>
				548	</html>