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

blob: e068d87da1369a9560aa8528a521fdeb7aaae399 [file] [log] [blame]

Andreas Boll	ecd5c7c	2012-06-12 09:05:03 +0200	[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">
				5	<title>Development Notes</title>
				6	<link rel="stylesheet" type="text/css" href="mesa.css">
				7	</head>
				8	<body>
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	9
Andreas Boll	b5da52a	2012-09-18 18:57:02 +0200	[diff] [blame]	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
Andreas Boll	ecd5c7c	2012-06-12 09:05:03 +0200	[diff] [blame]	17	<h1>Development Notes</h1>
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	18
				19
Brian Paul	5183061	2004-08-17 14:08:59 +0000	[diff] [blame]	20	<ul>
Brian Paul	98f2f47	2015-05-25 09:13:09 -0600	[diff] [blame]	21	<li><a href="#style">Coding Style</a>
				22	<li><a href="#submitting">Submitting Patches</a>
				23	<li><a href="#release">Making a New Mesa Release</a>
				24	<li><a href="#extensions">Adding Extensions</a>
Brian Paul	5183061	2004-08-17 14:08:59 +0000	[diff] [blame]	25	</ul>
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	26
				27
Brian Paul	98f2f47	2015-05-25 09:13:09 -0600	[diff] [blame]	28	<h2 id="style">Coding Style</h2>
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	29
				30	<p>
				31	Mesa's code style has changed over the years. Here's the latest.
				32	</p>
				33
				34	<p>
				35	Comment your code! It's extremely important that open-source code be
				36	well documented. Also, strive to write clean, easily understandable code.
				37	</p>
				38
				39	<p>
				40	3-space indentation
				41	</p>
				42
				43	<p>
				44	If you use tabs, set them to 8 columns
				45	</p>
				46
				47	<p>
Paul Berry	4396826	2011-08-16 14:09:32 -0700	[diff] [blame]	48	Line width: the preferred width to fill comments and code in Mesa is 78
				49	columns. Exceptions are sometimes made for clarity (e.g. tabular data is
				50	sometimes filled to a much larger width so that extraneous carriage returns
				51	don't obscure the table).
				52	</p>
				53
				54	<p>
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	55	Brace example:
				56	</p>
				57	<pre>
				58	if (condition) {
				59	foo;
				60	}
				61	else {
				62	bar;
				63	}
Paul Berry	4396826	2011-08-16 14:09:32 -0700	[diff] [blame]	64
				65	switch (condition) {
				66	case 0:
				67	foo();
				68	break;
				69
				70	case 1: {
				71	...
				72	break;
				73	}
				74
				75	default:
				76	...
				77	break;
				78	}
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	79	</pre>
				80
				81	<p>
				82	Here's the GNU indent command which will best approximate my preferred style:
Paul Berry	4396826	2011-08-16 14:09:32 -0700	[diff] [blame]	83	(Note that it won't format switch statements in the preferred way)
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	84	</p>
				85	<pre>
Brian Paul	e3f41ce	2006-03-31 23:10:21 +0000	[diff] [blame]	86	indent -br -i3 -npcs --no-tabs infile.c -o outfile.c
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	87	</pre>
				88
				89
				90	<p>
				91	Local variable name example: localVarName (no underscores)
				92	</p>
				93
				94	<p>
				95	Constants and macros are ALL_UPPERCASE, with _ between words
				96	</p>
				97
				98	<p>
Brian Paul	65b7905	2004-11-22 17:49:15 +0000	[diff] [blame]	99	Global variables are not allowed.
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	100	</p>
				101
				102	<p>
				103	Function name examples:
				104	</p>
				105	<pre>
Chia-I Wu	27d260b4	2010-02-24 11:20:14 +0800	[diff] [blame]	106	glFooBar() - a public GL entry point (in glapi_dispatch.c)
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	107	_mesa_FooBar() - the internal immediate mode function
				108	save_FooBar() - retained mode (display list) function in dlist.c
				109	foo_bar() - a static (private) function
				110	_mesa_foo_bar() - an internal non-static Mesa function
				111	</pre>
				112
Kai Wasserbäch	dbec3a5	2011-08-23 10:48:58 +0200	[diff] [blame]	113	<p>
				114	Places that are not directly visible to the GL API should prefer the use
				115	of <tt>bool</tt>, <tt>true</tt>, and
				116	<tt>false</tt> over <tt>GLboolean</tt>, <tt>GL_TRUE</tt>, and
				117	<tt>GL_FALSE</tt>. In C code, this may mean that
Kai Wasserbäch	e106d4c	2011-08-27 17:51:47 +0200	[diff] [blame]	118	<tt>#include <stdbool.h></tt> needs to be added. The
Kai Wasserbäch	dbec3a5	2011-08-23 10:48:58 +0200	[diff] [blame]	119	<tt>try_emit_</tt>* methods in src/mesa/program/ir_to_mesa.cpp and
Kai Wasserbäch	e106d4c	2011-08-27 17:51:47 +0200	[diff] [blame]	120	src/mesa/state_tracker/st_glsl_to_tgsi.cpp can serve as examples.
Kai Wasserbäch	dbec3a5	2011-08-23 10:48:58 +0200	[diff] [blame]	121	</p>
				122
Brian Paul	98f2f47	2015-05-25 09:13:09 -0600	[diff] [blame]	123
				124	<h2 id="submitting">Submitting patches</h2>
Timothy Arceri	2382011	2013-09-05 02:54:00 -0600	[diff] [blame]	125
				126	<p>
Brian Paul	d959885	2015-05-25 09:42:04 -0600	[diff] [blame^]	127	The basic guidelines for submitting patches are:
				128	</p>
				129
				130	<ul>
				131	<li>Patches should be sufficiently tested before submitting.
				132	<li>Code patches should follow Mesa coding conventions.
				133	<li>Whenever possible, patches should only effect individual Mesa/Gallium
				134	components.
				135	<li>Patches should never introduce build breaks and should be bisectable (see
				136	<code>git bisect</code>.)
				137	<li>Patches should be properly formatted (see below).
				138	<li>Patches should be submitted to mesa-dev for review using
				139	<code>git send-email</code>.
				140	<li>Patches should not mix code changes with code formatting changes (except,
				141	perhaps, in very trivial cases.)
				142	</ul>
				143
				144	<h3>Patch formatting</h3>
				145
				146	<p>
				147	The basic rules for patch formatting are:
				148	</p>
				149
				150	<ul>
				151	<li>Lines should be limited to 75 characters or less so that git logs
				152	displayed in 80-column terminals avoid line wrapping. Note that git
				153	log uses 4 spaces of indentation (4 + 75 < 80).
				154	<li>The first line should be a short, concise summary of the change prefixed
				155	with a module name. Examples:
				156	<pre>
				157	mesa: Add support for querying GL_VERTEX_ATTRIB_ARRAY_LONG
				158
				159	gallium: add PIPE_CAP_DEVICE_RESET_STATUS_QUERY
				160
				161	i965: Fix missing type in local variable declaration.
				162	</pre>
				163	<li>Subsequent patch comments should describe the change in more detail,
				164	if needed. For example:
				165	<pre>
				166	i965: Remove end-of-thread SEND alignment code.
				167
				168	This was present in Eric's initial implementation of the compaction code
				169	for Sandybridge (commit 077d01b6). There is no documentation saying this
				170	is necessary, and removing it causes no regressions in piglit on any
				171	platform.
				172	</pre>
				173	<li>A "Signed-off-by:" line is not required, but not discouraged either.
				174	<li>If a patch address a bugzilla issue, that should be noted in the
				175	patch comment. For example:
				176	<pre>
				177	Bugzilla: https://bugs.freedesktop.org/show_bug.cgi?id=89689
				178	</pre>
				179	<li>If there have been several revisions to a patch during the review
				180	process, they should be noted such as in this example:
				181	<pre>
				182	st/mesa: add ARB_texture_stencil8 support (v4)
				183
				184	if we support stencil texturing, enable texture_stencil8
				185	there is no requirement to support native S8 for this,
				186	the texture can be converted to x24s8 fine.
				187
				188	v2: fold fixes from Marek in:
				189	a) put S8 last in the list
				190	b) fix renderable to always test for d/s renderable
				191	fixup the texture case to use a stencil only format
				192	for picking the format for the texture view.
				193	v3: hit fallback for getteximage
				194	v4: put s8 back in front, it shouldn't get picked now (Ilia)
				195	</pre>
				196	<li>If someone tested your patch, document it with a line like this:
				197	<pre>
				198	Tested-by: Joe Hacker <jhacker@foo.com>
				199	</pre>
				200	<li>If the patch was reviewed (usually the case) or acked by someone,
				201	that should be documented with:
				202	<pre>
				203	Reviewed-by: Joe Hacker <jhacker@foo.com>
				204	Acked-by: Joe Hacker <jhacker@foo.com>
				205	</pre>
				206	</ul>
				207
				208
				209
				210	<h3>Testing Patches</h3>
				211
				212	<p>
				213	It should go without saying that patches must be tested. In general,
				214	do whatever testing is prudent.
				215	</p>
				216
				217	<p>
				218	You should always run the Mesa test suite before submitting patches.
				219	The test suite can be run using the 'make check' command. All tests
Timothy Arceri	2382011	2013-09-05 02:54:00 -0600	[diff] [blame]	220	must pass before patches will be accepted, this may mean you have
				221	to update the tests themselves.
				222	</p>
				223
				224	<p>
Brian Paul	d959885	2015-05-25 09:42:04 -0600	[diff] [blame^]	225	Whenever possible and applicable, test the patch with
				226	<a href="http://people.freedesktop.org/~nh/piglit/">Piglit</a> to
				227	check for regressions.
				228	</p>
				229
				230
				231	<h3>Mailing Patches</h3>
				232
				233	<p>
Timothy Arceri	2382011	2013-09-05 02:54:00 -0600	[diff] [blame]	234	Patches should be sent to the Mesa mailing list for review.
				235	When submitting a patch make sure to use git send-email rather than attaching
				236	patches to emails. Sending patches as attachments prevents people from being
				237	able to provide in-line review comments.
				238	</p>
				239
				240	<p>
				241	When submitting follow-up patches you can use --in-reply-to to make v2, v3,
				242	etc patches show up as replies to the originals. This usually works well
				243	when you're sending out updates to individual patches (as opposed to
				244	re-sending the whole series). Using --in-reply-to makes
				245	it harder for reviewers to accidentally review old patches.
				246	</p>
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	247
Brian Paul	98f2f47	2015-05-25 09:13:09 -0600	[diff] [blame]	248	<h3>Marking a commit as a candidate for a stable branch</h3>
Andreas Boll	f07784d	2012-10-02 13:37:34 +0200	[diff] [blame]	249
				250	<p>
				251	If you want a commit to be applied to a stable branch,
				252	you should add an appropriate note to the commit message.
				253	</p>
				254
				255	<p>
				256	Here are some examples of such a note:
				257	</p>
				258	<ul>
Carl Worth	d6c8365	2013-12-12 23:07:26 -0800	[diff] [blame]	259	<li>CC: <mesa-stable@lists.freedesktop.org></li>
				260	<li>CC: "9.2 10.0" <mesa-stable@lists.freedesktop.org></li>
				261	<li>CC: "10.0" <mesa-stable@lists.freedesktop.org></li>
Andreas Boll	f07784d	2012-10-02 13:37:34 +0200	[diff] [blame]	262	</ul>
				263
Carl Worth	d6c8365	2013-12-12 23:07:26 -0800	[diff] [blame]	264	Simply adding the CC to the mesa-stable list address is adequate to nominate
				265	the commit for the most-recently-created stable branch. It is only necessary
				266	to specify a specific branch name, (such as "9.2 10.0" or "10.0" in the
				267	examples above), if you want to nominate the commit for an older stable
				268	branch. And, as in these examples, you can nominate the commit for the older
				269	branch in addition to the more recent branch, or nominate the commit
				270	exclusively for the older branch.
				271
				272	This "CC" syntax for patch nomination will cause patches to automatically be
				273	copied to the mesa-stable@ mailing list when you use "git send-email" to send
				274	patches to the mesa-dev@ mailing list. Also, if you realize that a commit
Nathan Kidd	0691b37	2014-01-03 16:44:00 -0700	[diff] [blame]	275	should be nominated for the stable branch after it has already been committed,
Carl Worth	d6c8365	2013-12-12 23:07:26 -0800	[diff] [blame]	276	you can send a note directly to the mesa-stable@lists.freedesktop.org where
				277	the Mesa stable-branch maintainers will receive it. Be sure to mention the
				278	commit ID of the commit of interest (as it appears in the mesa master branch).
Andreas Boll	1f38fb2	2012-10-02 13:55:53 +0200	[diff] [blame]	279
Carl Worth	4546b70	2014-04-30 16:27:03 -0700	[diff] [blame]	280	The latest set of patches that have been nominated, accepted, or rejected for
				281	the upcoming stable release can always be seen on the
Carl Worth	399b4e2	2014-08-21 09:46:57 -0700	[diff] [blame]	282	<a href="http://cworth.org/~cworth/mesa-stable-queue/">Mesa Stable Queue</a>
Carl Worth	4546b70	2014-04-30 16:27:03 -0700	[diff] [blame]	283	page.
				284
Brian Paul	98f2f47	2015-05-25 09:13:09 -0600	[diff] [blame]	285	<h3>Criteria for accepting patches to the stable branch</h3>
Andreas Boll	1f38fb2	2012-10-02 13:55:53 +0200	[diff] [blame]	286
Carl Worth	399b4e2	2014-08-21 09:46:57 -0700	[diff] [blame]	287	Mesa has a designated release manager for each stable branch, and the release
				288	manager is the only developer that should be pushing changes to these
				289	branches. Everyone else should simply nominate patches using the mechanism
				290	described above.
				291
				292	The stable-release manager will work with the list of nominated patches, and
				293	for each patch that meets the crtieria below will cherry-pick the patch with:
				294	<code>git cherry-pick -x <commit></code>. The <code>-x</code> option is
				295	important so that the picked patch references the comit ID of the original
				296	patch.
				297
				298	The stable-release manager may at times need to force-push changes to the
				299	stable branches, for example, to drop a previously-picked patch that was later
				300	identified as causing a regression). These force-pushes may cause changes to
				301	be lost from the stable branch if developers push things directly. Consider
				302	yourself warned.
				303
				304	The stable-release manager is also given broad discretion in rejecting patches
				305	that have been nominated for the stable branch. The most basic rule is that
				306	the stable branch is for bug fixes only, (no new features, no
				307	regressions). Here is a non-exhaustive list of some reasons that a patch may
				308	be rejected:
				309
				310	<ul>
				311	<li>Patch introduces a regression. Any reported build breakage or other
				312	regression caused by a particular patch, (game no longer work, piglit test
				313	changes from PASS to FAIL), is justification for rejecting a patch.</li>
				314
				315	<li>Patch is too large, (say, larger than 100 lines)</li>
				316
				317	<li>Patch is not a fix. For example, a commit that moves code around with no
				318	functional change should be rejected.</li>
				319
				320	<li>Patch fix is not clearly described. For example, a commit message
				321	of only a single line, no description of the bug, no mention of bugzilla,
				322	etc.</li>
				323
				324	<li>Patch has not obviously been reviewed, For example, the commit message
				325	has no Reviewed-by, Signed-off-by, nor Tested-by tags from anyone but the
				326	author.</li>
				327
				328	<li>Patch has not already been merged to the master branch. As a rule, bug
				329	fixes should never be applied first to a stable branch. Patches should land
				330	first on the master branch and then be cherry-picked to a stable
				331	branch. (This is to avoid future releases causing regressions if the patch
				332	is not also applied to master.) The only things that might look like
				333	exceptions would be backports of patches from master that happen to look
				334	significantly different.</li>
				335
				336	<li>Patch depends on too many other patches. Ideally, all stable-branch
				337	patches should be self-contained. It sometimes occurs that a single, logical
				338	bug-fix occurs as two separate patches on master, (such as an original
				339	patch, then a subsequent fix-up to that patch). In such a case, these two
				340	patches should be squashed into a single, self-contained patch for the
				341	stable branch. (Of course, if the squashing makes the patch too large, then
				342	that could be a reason to reject the patch.)</li>
				343
				344	<li>Patch includes new feature development, not bug fixes. New OpenGL
				345	features, extensions, etc. should be applied to Mesa master and included in
				346	the next major release. Stable releases are intended only for bug fixes.
				347
				348	Note: As an exception to this rule, the stable-release manager may accept
				349	hardware-enabling "features". For example, backports of new code to support
				350	a newly-developed hardware product can be accepted if they can be reasonably
				351	determined to not have effects on other hardware.</li>
				352
				353	<li>Patch is a performance optimization. As a rule, performance patches are
				354	not candidates for the stable branch. The only exception might be a case
				355	where an application's performance was recently severely impacted so as to
				356	become unusable. The fix for this performance regression could then be
				357	considered for a stable branch. The optimization must also be
				358	non-controversial and the patches still need to meet the other criteria of
				359	being simple and self-contained</li>
				360
				361	<li>Patch introduces a new failure mode (such as an assert). While the new
				362	assert might technically be correct, for example to make Mesa more
				363	conformant, this is not the kind of "bug fix" we want in a stable
				364	release. The potential problem here is that an OpenGL program that was
				365	previously working, (even if technically non-compliant with the
				366	specification), could stop working after this patch. So that would be a
				367	regression that is unaacceptable for the stable branch.</li>
				368	</ul>
Andreas Boll	1f38fb2	2012-10-02 13:55:53 +0200	[diff] [blame]	369
Brian Paul	98f2f47	2015-05-25 09:13:09 -0600	[diff] [blame]	370
				371	<h2 id="release">Making a New Mesa Release</h2>
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	372
				373	<p>
				374	These are the instructions for making a new Mesa release.
				375	</p>
				376
Andreas Boll	210a27d	2012-06-12 09:05:36 +0200	[diff] [blame]	377	<h3>Get latest source files</h3>
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	378	<p>
Brian Paul	84c5e48	2009-06-23 19:21:04 -0600	[diff] [blame]	379	Use git to get the latest Mesa files from the git repository, from whatever
Carl Worth	619505a	2014-08-21 10:44:35 -0700	[diff] [blame]	380	branch is relevant. This document uses the convention X.Y.Z for the release
				381	being created, which should be created from a branch named X.Y.
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	382	</p>
				383
Carl Worth	619505a	2014-08-21 10:44:35 -0700	[diff] [blame]	384	<h3>Perform basic testing</h3>
Brian Paul	65b7905	2004-11-22 17:49:15 +0000	[diff] [blame]	385	<p>
Carl Worth	619505a	2014-08-21 10:44:35 -0700	[diff] [blame]	386	The release manager should, at the very least, test the code by compiling it,
				387	installing it, and running the latest piglit to ensure that no piglit tests
				388	have regressed since the previous release.
Brian Paul	65b7905	2004-11-22 17:49:15 +0000	[diff] [blame]	389	</p>
				390
				391	<p>
Carl Worth	619505a	2014-08-21 10:44:35 -0700	[diff] [blame]	392	The release manager should do this testing with at least one hardware driver,
				393	(say, whatever is contained in the local development machine), as well as on
				394	both Gallium and non-Gallium software drivers. The software testing can be
				395	performed by running piglit with the following environment-variable set:
Andreas Boll	b347bb5	2012-06-25 21:53:06 +0200	[diff] [blame]	396	</p>
				397
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	398	<pre>
Carl Worth	619505a	2014-08-21 10:44:35 -0700	[diff] [blame]	399	LIBGL_ALWAYS_SOFTWARE=1
				400	</pre>
				401
				402	And Gallium vs. non-Gallium software drivers can be obtained by using the
				403	following configure flags on separate builds:
				404
				405	<pre>
				406	--with-dri-drivers=swrast
				407	--with-gallium-drivers=swrast
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	408	</pre>
				409
				410	<p>
Carl Worth	619505a	2014-08-21 10:44:35 -0700	[diff] [blame]	411	Note: If both options are given in one build, both swrast_dri.so drivers will
				412	be compiled, but only one will be installed. The following command can be used
				413	to ensure the correct driver is being tested:
				414	</p>
				415
				416	<pre>
				417	LIBGL_ALWAYS_SOFTWARE=1 glxinfo \| grep "renderer string"
				418	</pre>
				419
				420	If any regressions are found in this testing with piglit, stop here, and do
				421	not perform a release until regressions are fixed.
				422
				423	<h3>Update version in file VERSION</h3>
				424
				425	<p>
				426	Increment the version contained in the file VERSION at Mesa's top-level, then
				427	commit this change.
				428	</p>
				429
				430	<h3>Create release notes for the new release</h3>
				431
				432	<p>
				433	Create a new file docs/relnotes/X.Y.Z.html, (follow the style of the previous
				434	release notes). Note that the sha256sums section of the release notes should
				435	be empty at this point.
Brian Paul	65b7905	2004-11-22 17:49:15 +0000	[diff] [blame]	436	</p>
				437
				438	<p>
Carl Worth	619505a	2014-08-21 10:44:35 -0700	[diff] [blame]	439	Two scripts are available to help generate portions of the release notes:
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	440
Carl Worth	619505a	2014-08-21 10:44:35 -0700	[diff] [blame]	441	<pre>
				442	./bin/bugzilla_mesa.sh
				443	./bin/shortlog_mesa.sh
				444	</pre>
				445
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	446	<p>
Carl Worth	619505a	2014-08-21 10:44:35 -0700	[diff] [blame]	447	The first script identifies commits that reference bugzilla bugs and obtains
				448	the descriptions of those bugs from bugzilla. The second script generates a
				449	log of all commits. In both cases, HTML-formatted lists are printed to stdout
				450	to be included in the release notes.
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	451	</p>
				452
				453	<p>
Carl Worth	619505a	2014-08-21 10:44:35 -0700	[diff] [blame]	454	Commit these changes
				455	</p>
				456
				457	<h3>Make the release archives, signatures, and the release tag</h3>
				458	<p>
				459	From inside the Mesa directory:
				460	<pre>
				461	./autogen.sh
				462	make -j1 tarballs
				463	</pre>
				464
				465	<p>
				466	After the tarballs are created, the sha256 checksums for the files will
				467	be computed and printed. These will be used in a step below.
				468	</p>
				469
				470	<p>
				471	It's important at this point to also verify that the constructed tar file
				472	actually builds:
				473	</p>
				474
				475	<pre>
				476	tar xjf MesaLib-X.Y.Z.tar.bz2
				477	cd Mesa-X.Y.Z
				478	./configure --enable-gallium-llvm
				479	make -j6
				480	make install
				481	</pre>
				482
				483	<p>
				484	Some touch testing should also be performed at this point, (run glxgears or
				485	more involved OpenGL programs against the installed Mesa).
				486	</p>
				487
				488	<p>
				489	Create detached GPG signatures for each of the archive files created above:
				490	</p>
				491
				492	<pre>
				493	gpg --sign --detach MesaLib-X.Y.Z.tar.gz
				494	gpg --sign --detach MesaLib-X.Y.Z.tar.bz2
				495	gpg --sign --detach MesaLib-X.Y.Z.zip
				496	</pre>
				497
				498	<p>
				499	Tag the commit used for the build:
				500	</p>
				501
				502	<pre>
				503	git tag -s mesa-X.Y.X -m "Mesa X.Y.Z release"
				504	</pre>
				505
				506	<p>
				507	Note: It would be nice to investigate and fix the issue that causes the
				508	tarballs target to fail with multiple build process, such as with "-j4". It
				509	would also be nice to incorporate all of the above commands into a single
				510	makefile target. And instead of a custom "tarballs" target, we should
				511	incorporate things into the standard "make dist" and "make distcheck" targets.
				512	</p>
				513
				514	<h3>Add the sha256sums to the release notes</h3>
				515
				516	<p>
				517	Edit docs/relnotes/X.Y.Z.html to add the sha256sums printed as part of "make
				518	tarballs" in the previous step. Commit this change.
				519	</p>
				520
				521	<h3>Push all commits and the tag creates above</h3>
				522
				523	<p>
				524	This is the first step that cannot easily be undone. The release is going
				525	forward from this point:
				526	</p>
				527
				528	<pre>
				529	git push origin X.Y --tags
				530	</pre>
				531
				532	<h3>Install the release files and signatures on the distribution server</h3>
				533
				534	<p>
				535	The following commands can be used to copy the release archive files and
				536	signatures to the freedesktop.org server:
				537	</p>
				538
				539	<pre>
				540	scp MesaLib-X.Y.Z* people.freedesktop.org:
				541	ssh people.freedesktop.org
				542	cd /srv/ftp.freedesktop.org/pub/mesa
				543	mkdir X.Y.Z
				544	cd X.Y.Z
				545	mv ~/MesaLib-X.Y.Z* .
				546	</pre>
				547
				548	<h3>Back on mesa master, andd the new release notes into the tree</h3>
				549
				550	<p>
				551	Something like the following steps will do the trick:
				552	</p>
				553
				554	<pre>
				555	cp docs/relnotes/X.Y.Z.html /tmp
				556	git checkout master
				557	cp /tmp/X.Y.Z.html docs/relnotes
				558	git add docs/relnotes/X.Y.Z.html
				559	</pre>
				560
				561	<p>
				562	Also, edit docs/relnotes.html to add a link to the new release notes, and edit
				563	docs/index.html to add a news entry. Then commit and push:
				564	</p>
				565
				566	<pre>
				567	git commit -a -m "docs: Import X.Y.Z release notes, add news item."
				568	git push origin
				569	</pre>
				570
				571	<h3>Update the mesa3d.org website</h3>
				572
				573	<p>
				574	NOTE: The recent release managers have not been performing this step
				575	themselves, but leaving this to Brian Paul, (who has access to the
				576	sourceforge.net hosting for mesa3d.org). Brian is more than willing to grant
				577	the permission necessary to future release managers to do this step on their
				578	own.
Brian Paul	84c5e48	2009-06-23 19:21:04 -0600	[diff] [blame]	579	</p>
				580
				581	<p>
Brian Paul	65b7905	2004-11-22 17:49:15 +0000	[diff] [blame]	582	Update the web site by copying the docs/ directory's files to
Brian Paul	84c5e48	2009-06-23 19:21:04 -0600	[diff] [blame]	583	/home/users/b/br/brianp/mesa-www/htdocs/ with:
				584	<br>
				585	<code>
				586	sftp USERNAME,mesa3d@web.sourceforge.net
				587	</code>
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	588	</p>
				589
Carl Worth	619505a	2014-08-21 10:44:35 -0700	[diff] [blame]	590
				591	<h3>Announce the release</h3>
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	592	<p>
Brian Paul	efe5671	2003-03-19 19:15:28 +0000	[diff] [blame]	593	Make an announcement on the mailing lists:
Ian Romanick	8f32c64	2010-06-16 14:28:08 -0700	[diff] [blame]	594
Kenneth Graunke	7d24d1b	2013-07-25 11:42:38 -0700	[diff] [blame]	595	<em>mesa-dev@lists.freedesktop.org</em>,
Brian Paul	efe5671	2003-03-19 19:15:28 +0000	[diff] [blame]	596	and
Kenneth Graunke	7d24d1b	2013-07-25 11:42:38 -0700	[diff] [blame]	597	<em>mesa-announce@lists.freedesktop.org</em>
Carl Worth	619505a	2014-08-21 10:44:35 -0700	[diff] [blame]	598
				599	Follow the template of previously-sent release announcements. The following
				600	command can be used to generate the log of changes to be included in the
				601	release announcement:
				602
				603	<pre>
				604	git shortlog mesa-X.Y.Z-1..mesa-X.Y.Z
				605	</pre>
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	606	</p>
				607
Brian Paul	98f2f47	2015-05-25 09:13:09 -0600	[diff] [blame]	608
				609	<h2 id="extensions">Adding Extensions</h2>
				610
				611	<p>
				612	To add a new GL extension to Mesa you have to do at least the following.
				613
				614	<ul>
				615	<li>
				616	If glext.h doesn't define the extension, edit include/GL/gl.h and add
				617	code like this:
				618	<pre>
				619	#ifndef GL_EXT_the_extension_name
				620	#define GL_EXT_the_extension_name 1
				621	/* declare the new enum tokens */
				622	/* prototype the new functions */
				623	/* TYPEDEFS for the new functions */
				624	#endif
				625	</pre>
				626	</li>
				627	<li>
				628	In the src/mapi/glapi/gen/ directory, add the new extension functions and
				629	enums to the gl_API.xml file.
				630	Then, a bunch of source files must be regenerated by executing the
				631	corresponding Python scripts.
				632	</li>
				633	<li>
				634	Add a new entry to the <code>gl_extensions</code> struct in mtypes.h
				635	</li>
				636	<li>
				637	Update the <code>extensions.c</code> file.
				638	</li>
				639	<li>
				640	From this point, the best way to proceed is to find another extension,
				641	similar to the new one, that's already implemented in Mesa and use it
				642	as an example.
				643	</li>
				644	<li>
				645	If the new extension adds new GL state, the functions in get.c, enable.c
				646	and attrib.c will most likely require new code.
				647	</li>
				648	<li>
				649	The dispatch tests check_table.cpp and dispatch_sanity.cpp
				650	should be updated with details about the new extensions functions. These
				651	tests are run using 'make check'
				652	</li>
				653	</ul>
				654
				655
				656
				657
Andreas Boll	b5da52a	2012-09-18 18:57:02 +0200	[diff] [blame]	658	</div>
Brian Paul	0b27ace	2003-03-08 17:38:57 +0000	[diff] [blame]	659	</body>
				660	</html>