-<HTML>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html lang="en">
+<head>
+ <meta http-equiv="content-type" content="text/html; charset=utf-8">
+ <title>Development Notes</title>
+ <link rel="stylesheet" type="text/css" href="mesa.css">
+</head>
+<body>
-<TITLE>Development Notes</TITLE>
+<div class="header">
+ <h1>The Mesa 3D Graphics Library</h1>
+</div>
-<BODY text="#000000" bgcolor="#55bbff" link="#111188">
+<iframe src="contents.html"></iframe>
+<div class="content">
-<H1>Development Notes</H1>
+<h1>Development Notes</h1>
-<H2>Adding Extentions</H2>
+<h2>Adding Extensions</h2>
<p>
-To add a new GL extension to Mesa you have to do the following.
-<pre>
- If glext.h doesn't define the extension, edit include/GL/gl.h and add:
- - new enum tokens
- - new API function entry points
- - #define GL_EXT_the_extension_name 1
+To add a new GL extension to Mesa you have to do at least the following.
- If adding a new API function (call it glNewFunctionEXT):
- - insert glNewFunctionEXT()into src/apiext.h
- - edit src/types.h and add NewFunction to the gl_api_table struct
- - implement gl_NewFunction() in the appropriate src file
- - hook gl_NewFunction() into pointers.c
- - add display list support in dlist.c for save_NewFunction()
- - add glNewFunctionEXT to gl_GetProcAddress() in extensions.c or
- in the device driver's GetProcAddress() function if appropriate
-</pre>
-<p>
-If adding new GL state be sure to update get.c and enable.c
-</p>
-<p>
-In general, look for an extension similar to the new one that's already
-implemented in Mesa and follow it by example.
-</p>
+<ul>
+<li>
+ If glext.h doesn't define the extension, edit include/GL/gl.h and add
+ code like this:
+ <pre>
+ #ifndef GL_EXT_the_extension_name
+ #define GL_EXT_the_extension_name 1
+ /* declare the new enum tokens */
+ /* prototype the new functions */
+ /* TYPEDEFS for the new functions */
+ #endif
+ </pre>
+</li>
+<li>
+ In the src/mapi/glapi/gen/ directory, add the new extension functions and
+ enums to the gl_API.xml file.
+ Then, a bunch of source files must be regenerated by executing the
+ corresponding Python scripts.
+</li>
+<li>
+ Add a new entry to the <code>gl_extensions</code> struct in mtypes.h
+</li>
+<li>
+ Update the <code>extensions.c</code> file.
+</li>
+<li>
+ From this point, the best way to proceed is to find another extension,
+ similar to the new one, that's already implemented in Mesa and use it
+ as an example.
+</li>
+<li>
+ If the new extension adds new GL state, the functions in get.c, enable.c
+ and attrib.c will most likely require new code.
+</li>
+<li>
+ The dispatch tests check_table.cpp and dispatch_sanity.cpp
+ should be updated with details about the new extensions functions. These
+ tests are run using 'make check'
+</li>
+</ul>
-<H2>Coding Style</H2>
+<h2>Coding Style</h2>
<p>
Mesa's code style has changed over the years. Here's the latest.
If you use tabs, set them to 8 columns
</p>
+<p>
+Line width: the preferred width to fill comments and code in Mesa is 78
+columns. Exceptions are sometimes made for clarity (e.g. tabular data is
+sometimes filled to a much larger width so that extraneous carriage returns
+don't obscure the table).
+</p>
+
<p>
Brace example:
</p>
else {
bar;
}
+
+ switch (condition) {
+ case 0:
+ foo();
+ break;
+
+ case 1: {
+ ...
+ break;
+ }
+
+ default:
+ ...
+ break;
+ }
</pre>
<p>
Here's the GNU indent command which will best approximate my preferred style:
+(Note that it won't format switch statements in the preferred way)
</p>
<pre>
- indent -br -i3 -npcs infile.c -o outfile.c
+ indent -br -i3 -npcs --no-tabs infile.c -o outfile.c
</pre>
</p>
<p>
-Global vars not allowed.
+Global variables are not allowed.
</p>
<p>
Function name examples:
</p>
<pre>
- glFooBar() - a public GL entry point (in dispatch.c)
+ glFooBar() - a public GL entry point (in glapi_dispatch.c)
_mesa_FooBar() - the internal immediate mode function
save_FooBar() - retained mode (display list) function in dlist.c
foo_bar() - a static (private) function
_mesa_foo_bar() - an internal non-static Mesa function
</pre>
+<p>
+Places that are not directly visible to the GL API should prefer the use
+of <tt>bool</tt>, <tt>true</tt>, and
+<tt>false</tt> over <tt>GLboolean</tt>, <tt>GL_TRUE</tt>, and
+<tt>GL_FALSE</tt>. In C code, this may mean that
+<tt>#include <stdbool.h></tt> needs to be added. The
+<tt>try_emit_</tt>* methods in src/mesa/program/ir_to_mesa.cpp and
+src/mesa/state_tracker/st_glsl_to_tgsi.cpp can serve as examples.
+</p>
-<H2>Writing a Device Driver</H2>
+<h2>Submitting patches</h2>
<p>
-XXX to do
+You should always run the Mesa Testsuite before submitting patches.
+The Testsuite can be run using the 'make check' command. All tests
+must pass before patches will be accepted, this may mean you have
+to update the tests themselves.
</p>
+<p>
+Patches should be sent to the Mesa mailing list for review.
+When submitting a patch make sure to use git send-email rather than attaching
+patches to emails. Sending patches as attachments prevents people from being
+able to provide in-line review comments.
+</p>
+<p>
+When submitting follow-up patches you can use --in-reply-to to make v2, v3,
+etc patches show up as replies to the originals. This usually works well
+when you're sending out updates to individual patches (as opposed to
+re-sending the whole series). Using --in-reply-to makes
+it harder for reviewers to accidentally review old patches.
+</p>
-<H2>Making a New Mesa Release</H2>
+<h2>Marking a commit as a candidate for a stable branch</h2>
<p>
-These are the instructions for making a new Mesa release.
+If you want a commit to be applied to a stable branch,
+you should add an appropriate note to the commit message.
</p>
<p>
-Prerequisites (later versions may work):
+Here are some examples of such a note:
</p>
<ul>
-<li> autoconf 2.50
-<li> automake 1.4-p2
-<li> libtool 1.4
+ <li>CC: <mesa-stable@lists.freedesktop.org></li>
+ <li>CC: "9.2 10.0" <mesa-stable@lists.freedesktop.org></li>
+ <li>CC: "10.0" <mesa-stable@lists.freedesktop.org></li>
</ul>
+Simply adding the CC to the mesa-stable list address is adequate to nominate
+the commit for the most-recently-created stable branch. It is only necessary
+to specify a specific branch name, (such as "9.2 10.0" or "10.0" in the
+examples above), if you want to nominate the commit for an older stable
+branch. And, as in these examples, you can nominate the commit for the older
+branch in addition to the more recent branch, or nominate the commit
+exclusively for the older branch.
+
+This "CC" syntax for patch nomination will cause patches to automatically be
+copied to the mesa-stable@ mailing list when you use "git send-email" to send
+patches to the mesa-dev@ mailing list. Also, if you realize that a commit
+should be nominated for the stable branch after it has already been committed,
+you can send a note directly to the mesa-stable@lists.freedesktop.org where
+the Mesa stable-branch maintainers will receive it. Be sure to mention the
+commit ID of the commit of interest (as it appears in the mesa master branch).
+
+The latest set of patches that have been nominated, accepted, or rejected for
+the upcoming stable release can always be seen on the
+<a href="http://cworth.org/~cworth/mesa-stable-queue/">Mesa Stable Queue</a>
+page.
+
+<h2>Criteria for accepting patches to the stable branch</h2>
+
+Mesa has a designated release manager for each stable branch, and the release
+manager is the only developer that should be pushing changes to these
+branches. Everyone else should simply nominate patches using the mechanism
+described above.
+
+The stable-release manager will work with the list of nominated patches, and
+for each patch that meets the crtieria below will cherry-pick the patch with:
+<code>git cherry-pick -x <commit></code>. The <code>-x</code> option is
+important so that the picked patch references the comit ID of the original
+patch.
+
+The stable-release manager may at times need to force-push changes to the
+stable branches, for example, to drop a previously-picked patch that was later
+identified as causing a regression). These force-pushes may cause changes to
+be lost from the stable branch if developers push things directly. Consider
+yourself warned.
+
+The stable-release manager is also given broad discretion in rejecting patches
+that have been nominated for the stable branch. The most basic rule is that
+the stable branch is for bug fixes only, (no new features, no
+regressions). Here is a non-exhaustive list of some reasons that a patch may
+be rejected:
+
+<ul>
+ <li>Patch introduces a regression. Any reported build breakage or other
+ regression caused by a particular patch, (game no longer work, piglit test
+ changes from PASS to FAIL), is justification for rejecting a patch.</li>
+
+ <li>Patch is too large, (say, larger than 100 lines)</li>
+
+ <li>Patch is not a fix. For example, a commit that moves code around with no
+ functional change should be rejected.</li>
+
+ <li>Patch fix is not clearly described. For example, a commit message
+ of only a single line, no description of the bug, no mention of bugzilla,
+ etc.</li>
+
+ <li>Patch has not obviously been reviewed, For example, the commit message
+ has no Reviewed-by, Signed-off-by, nor Tested-by tags from anyone but the
+ author.</li>
+
+ <li>Patch has not already been merged to the master branch. As a rule, bug
+ fixes should never be applied first to a stable branch. Patches should land
+ first on the master branch and then be cherry-picked to a stable
+ branch. (This is to avoid future releases causing regressions if the patch
+ is not also applied to master.) The only things that might look like
+ exceptions would be backports of patches from master that happen to look
+ significantly different.</li>
+
+ <li>Patch depends on too many other patches. Ideally, all stable-branch
+ patches should be self-contained. It sometimes occurs that a single, logical
+ bug-fix occurs as two separate patches on master, (such as an original
+ patch, then a subsequent fix-up to that patch). In such a case, these two
+ patches should be squashed into a single, self-contained patch for the
+ stable branch. (Of course, if the squashing makes the patch too large, then
+ that could be a reason to reject the patch.)</li>
+
+ <li>Patch includes new feature development, not bug fixes. New OpenGL
+ features, extensions, etc. should be applied to Mesa master and included in
+ the next major release. Stable releases are intended only for bug fixes.
+
+ Note: As an exception to this rule, the stable-release manager may accept
+ hardware-enabling "features". For example, backports of new code to support
+ a newly-developed hardware product can be accepted if they can be reasonably
+ determined to not have effects on other hardware.</li>
+
+ <li>Patch is a performance optimization. As a rule, performance patches are
+ not candidates for the stable branch. The only exception might be a case
+ where an application's performance was recently severely impacted so as to
+ become unusable. The fix for this performance regression could then be
+ considered for a stable branch. The optimization must also be
+ non-controversial and the patches still need to meet the other criteria of
+ being simple and self-contained</li>
+
+ <li>Patch introduces a new failure mode (such as an assert). While the new
+ assert might technically be correct, for example to make Mesa more
+ conformant, this is not the kind of "bug fix" we want in a stable
+ release. The potential problem here is that an OpenGL program that was
+ previously working, (even if technically non-compliant with the
+ specification), could stop working after this patch. So that would be a
+ regression that is unaacceptable for the stable branch.</li>
+</ul>
+
+<h2>Making a New Mesa Release</h2>
+
<p>
-Be sure to do a "cvs update -d ." in the Mesa directory to
-get all the latest files.
+These are the instructions for making a new Mesa release.
</p>
+<h3>Get latest source files</h3>
<p>
-Update the version strings in src/get.c and src/X/fakeglx.c to return
-the new Mesa version number.
+Use git to get the latest Mesa files from the git repository, from whatever
+branch is relevant. This document uses the convention X.Y.Z for the release
+being created, which should be created from a branch named X.Y.
</p>
+<h3>Perform basic testing</h3>
<p>
-Create/edit the docs/RELNOTES-X-Y file to document what's new in the release.
-Edit the docs/VERSIONS file too.
-Update the docs/IAFA-PACKAGE file.
+The release manager should, at the very least, test the code by compiling it,
+installing it, and running the latest piglit to ensure that no piglit tests
+have regressed since the previous release.
</p>
<p>
-Edit Make-config and change the MESA_MAJOR and/or MESA_MINOR versions.
+The release manager should do this testing with at least one hardware driver,
+(say, whatever is contained in the local development machine), as well as on
+both Gallium and non-Gallium software drivers. The software testing can be
+performed by running piglit with the following environment-variable set:
</p>
+<pre>
+LIBGL_ALWAYS_SOFTWARE=1
+</pre>
+
+And Gallium vs. non-Gallium software drivers can be obtained by using the
+following configure flags on separate builds:
+
+<pre>
+--with-dri-drivers=swrast
+--with-gallium-drivers=swrast
+</pre>
+
<p>
-Edit the GNU configure stuff to change versions numbers as needed:
-Update the version string (second argument) in the line
-"AM_INIT_AUTOMAKE(Mesa, 3.3)" in the configure.in file.
+Note: If both options are given in one build, both swrast_dri.so drivers will
+be compiled, but only one will be installed. The following command can be used
+to ensure the correct driver is being tested:
</p>
+<pre>
+LIBGL_ALWAYS_SOFTWARE=1 glxinfo | grep "renderer string"
+</pre>
+
+If any regressions are found in this testing with piglit, stop here, and do
+not perform a release until regressions are fixed.
+
+<h3>Update version in file VERSION</h3>
+
<p>
-Remove the leading `dnl' from the line "dnl AM_MAINTAINER_MODE".
+Increment the version contained in the file VERSION at Mesa's top-level, then
+commit this change.
</p>
+<h3>Create release notes for the new release</h3>
+
<p>
-Verify the version numbers near the top of configure.in
+Create a new file docs/relnotes/X.Y.Z.html, (follow the style of the previous
+release notes). Note that the sha256sums section of the release notes should
+be empty at this point.
</p>
<p>
-Run "fixam -f" to disable automatic dependency tracking.
+Two scripts are available to help generate portions of the release notes:
+
+<pre>
+ ./bin/bugzilla_mesa.sh
+ ./bin/shortlog_mesa.sh
+</pre>
+
+<p>
+The first script identifies commits that reference bugzilla bugs and obtains
+the descriptions of those bugs from bugzilla. The second script generates a
+log of all commits. In both cases, HTML-formatted lists are printed to stdout
+to be included in the release notes.
</p>
<p>
-Run the bootstrap script to generate the configure script.
+Commit these changes
</p>
+<h3>Make the release archives, signatures, and the release tag</h3>
+<p>
+From inside the Mesa directory:
+<pre>
+ ./autogen.sh
+ make -j1 tarballs
+</pre>
+
<p>
-Edit Makefile.X11 and verify DIRECTORY is set correctly. The Mesa
-sources must be in that directory (or there must be a symbolic link).
+After the tarballs are created, the sha256 checksums for the files will
+be computed and printed. These will be used in a step below.
</p>
<p>
-Edit Makefile.X11 and verify that LIB_NAME and DEMO_NAME are correct.
-If it's a beta release, be sure the bump up the beta release number.
+It's important at this point to also verify that the constructed tar file
+actually builds:
</p>
+<pre>
+ tar xjf MesaLib-X.Y.Z.tar.bz2
+ cd Mesa-X.Y.Z
+ ./configure --enable-gallium-llvm
+ make -j6
+ make install
+</pre>
+
<p>
-cp Makefile.X11 to Makefile so that the old-style Mesa makefiles
-still work. ./configure will overwrite it if that's what the user runs.
+Some touch testing should also be performed at this point, (run glxgears or
+more involved OpenGL programs against the installed Mesa).
</p>
<p>
-Make a symbolic link from $(DIRECTORY) to Mesa. For example,
-ln -s Mesa Mesa-3.3 This is needed in order to make a correct
-tar file in the next step.
+Create detached GPG signatures for each of the archive files created above:
</p>
+<pre>
+ gpg --sign --detach MesaLib-X.Y.Z.tar.gz
+ gpg --sign --detach MesaLib-X.Y.Z.tar.bz2
+ gpg --sign --detach MesaLib-X.Y.Z.zip
+</pre>
+
<p>
-Make the distribution files. From inside the Mesa directory:
+Tag the commit used for the build:
+</p>
+
<pre>
- make -f Makefile.X11 lib_tar
- make -f Makefile.X11 demo_tar
- make -f Makefile.X11 lib_zip
- make -f Makefile.X11 demo_zip
+ git tag -s mesa-X.Y.X -m "Mesa X.Y.Z release"
</pre>
<p>
-Copy the distribution files to a temporary directory, unpack them,
-compile everything, and run some demos to be sure everything works.
+Note: It would be nice to investigate and fix the issue that causes the
+tarballs target to fail with multiple build process, such as with "-j4". It
+would also be nice to incorporate all of the above commands into a single
+makefile target. And instead of a custom "tarballs" target, we should
+incorporate things into the standard "make dist" and "make distcheck" targets.
</p>
+<h3>Add the sha256sums to the release notes</h3>
+
<p>
-Upload the *.tar.gz and *.zip files to ftp.mesa3d.org
+Edit docs/relnotes/X.Y.Z.html to add the sha256sums printed as part of "make
+tarballs" in the previous step. Commit this change.
</p>
+<h3>Push all commits and the tag creates above</h3>
+
<p>
-Update the web site. CJ Beyer (cj@styx.phy.vanderbilt.edu) can
-help with this and uploading to the ftp site.
+This is the first step that cannot easily be undone. The release is going
+forward from this point:
</p>
+<pre>
+ git push origin X.Y --tags
+</pre>
+
+<h3>Install the release files and signatures on the distribution server</h3>
+
<p>
-Make the announcement to the SourceForge.net sites: mesa3d-dev@lists.sf.net,
-mesa3d-users@lists.sf.net and mesa3d-announce@lists.sf.net
+The following commands can be used to copy the release archive files and
+signatures to the freedesktop.org server:
</p>
+<pre>
+ scp MesaLib-X.Y.Z* people.freedesktop.org:
+ ssh people.freedesktop.org
+ cd /srv/ftp.freedesktop.org/pub/mesa
+ mkdir X.Y.Z
+ cd X.Y.Z
+ mv ~/MesaLib-X.Y.Z* .
+</pre>
-<H2>Autoconf info</H2>
+<h3>Back on mesa master, andd the new release notes into the tree</h3>
<p>
-In order to run the bootstrap script you'll need:
+Something like the following steps will do the trick:
+</p>
+
+<pre>
+ cp docs/relnotes/X.Y.Z.html /tmp
+ git checkout master
+ cp /tmp/X.Y.Z.html docs/relnotes
+ git add docs/relnotes/X.Y.Z.html
+</pre>
+
<p>
+Also, edit docs/relnotes.html to add a link to the new release notes, and edit
+docs/index.html to add a news entry. Then commit and push:
+</p>
+
<pre>
-autoconf 2.50
-automake 1.4-p5
-libtool 1.4
+ git commit -a -m "docs: Import X.Y.Z release notes, add news item."
+ git push origin
</pre>
+<h3>Update the mesa3d.org website</h3>
+
+<p>
+NOTE: The recent release managers have not been performing this step
+themselves, but leaving this to Brian Paul, (who has access to the
+sourceforge.net hosting for mesa3d.org). Brian is more than willing to grant
+the permission necessary to future release managers to do this step on their
+own.
+</p>
+
+<p>
+Update the web site by copying the docs/ directory's files to
+/home/users/b/br/brianp/mesa-www/htdocs/ with:
+<br>
+<code>
+sftp USERNAME,mesa3d@web.sourceforge.net
+</code>
+</p>
+
+
+<h3>Announce the release</h3>
+<p>
+Make an announcement on the mailing lists:
+
+<em>mesa-dev@lists.freedesktop.org</em>,
+and
+<em>mesa-announce@lists.freedesktop.org</em>
+
+Follow the template of previously-sent release announcements. The following
+command can be used to generate the log of changes to be included in the
+release announcement:
+
+<pre>
+ git shortlog mesa-X.Y.Z-1..mesa-X.Y.Z
+</pre>
+</p>
+</div>
</body>
</html>