The Mesa 3D Graphics Library

Development Notes

Making a New Mesa Release

These are the instructions for making a new Mesa release.

Get latest source files

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.

Perform basic testing

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.

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:

LIBGL_ALWAYS_SOFTWARE=1
And Gallium vs. non-Gallium software drivers can be obtained by using the following configure flags on separate builds:
--with-dri-drivers=swrast
--with-gallium-drivers=swrast

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:

LIBGL_ALWAYS_SOFTWARE=1 glxinfo | grep "renderer string"
If any regressions are found in this testing with piglit, stop here, and do not perform a release until regressions are fixed.

Update version in file VERSION

Increment the version contained in the file VERSION at Mesa's top-level, then commit this change.

Create release notes for the new release

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.

Two scripts are available to help generate portions of the release notes:

	./bin/bugzilla_mesa.sh
	./bin/shortlog_mesa.sh

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.

Commit these changes

Make the release archives, signatures, and the release tag

From inside the Mesa directory:

	./autogen.sh
	make -j1 tarballs

After the tarballs are created, the sha256 checksums for the files will be computed and printed. These will be used in a step below.

It's important at this point to also verify that the constructed tar file actually builds:

	tar xjf MesaLib-X.Y.Z.tar.bz2
	cd Mesa-X.Y.Z
	./configure --enable-gallium-llvm
	make -j6
	make install

Some touch testing should also be performed at this point, (run glxgears or more involved OpenGL programs against the installed Mesa).

Create detached GPG signatures for each of the archive files created above:

	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

Tag the commit used for the build:

	git tag -s mesa-X.Y.X -m "Mesa X.Y.Z release"

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.

Add the sha256sums to the release notes

Edit docs/relnotes/X.Y.Z.html to add the sha256sums printed as part of "make tarballs" in the previous step. Commit this change.

Push all commits and the tag created above

This is the first step that cannot easily be undone. The release is going forward from this point:

	git push origin X.Y --tags

Install the release files and signatures on the distribution server

The following commands can be used to copy the release archive files and signatures to the freedesktop.org server:

	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* .

Back on mesa master, add the new release notes into the tree

Something like the following steps will do the trick:

	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

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:

	git commit -a -m "docs: Import X.Y.Z release notes, add news item."
        git push origin

Update the mesa3d.org website

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.

Update the web site by copying the docs/ directory's files to /home/users/b/br/brianp/mesa-www/htdocs/ with:
sftp USERNAME,mesa3d@web.sourceforge.net

Announce the release

Make an announcement on the mailing lists: mesa-dev@lists.freedesktop.org, and mesa-announce@lists.freedesktop.org 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:

	git shortlog mesa-X.Y.Z-1..mesa-X.Y.Z

Adding Extensions

To add a new GL extension to Mesa you have to do at least the following.