-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: -

-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: -

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

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

Make the release archives, signatures, and the release tag

-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: -

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

-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: -

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: -

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

-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: -

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: - -

Adding Extensions

diff --git a/docs/releasing.html b/docs/releasing.html new file mode 100644 index 00000000000..400cf92121e --- /dev/null +++ b/docs/releasing.html @@ -0,0 +1,499 @@ + + + + + Development Notes + + + + +

+ +

Releasing process

+ +

Overview +
Release schedule +
Cherry-pick and test +
Making a branchpoint +
Pre-release announcement +
Making a new release +
Announce the release +
Update the mesa3d.org website +
Update Bugzilla +

+ +

Overview

+ +

+This document uses the convention X.Y.Z for the release number with X.Y being +the stable branch name. +
+Mesa provides feature and bugfix releases. Former use zero as patch version (Z), +while the latter have a non-zero one. +

+ +

+For example: +

+	Mesa 10.1.0 - 10.1 branch, feature
+	Mesa 10.1.4 - 10.1 branch, bugfix
+	Mesa 12.0.0 - 12.0 branch, feature
+	Mesa 12.0.2 - 12.0 branch, bugfix
+

+ +

Release schedule

+ +

+Releases should happen on Fridays. Delays can occur although those should be keep +to a minimum. +

+ +

Feature releases

Available approximatelly every three months. +
Initial timeplan available 2-4 weeks before the planned branchpoint (rc1) +on the mesa-announce@ mailing list. +
A pre-release announcement should be available +approximatelly 24 hours before the final (non-rc) release. +

+ +

Stable releases

Normally available once every two weeks. +
Only the latest branch has releases. See note below. +
A pre-release announcement should be available +approximatelly 48 hours before the actual release. +

+ +

+Note: There is one or two releases overlap when changing branches. For example: +
+The final release from the 12.0 series Mesa 12.0.5 will be out around the same +time (or shortly after) 13.0.1 is out. +

+ +

Cherry-picking and testing

+ +

+Commits nominated for the active branch are picked as based on the +criteria as +described in the same section. + +

+Maintainer is responsible for testing in various possible permutations of +the autoconf and scons build. +

+ +

Cherry-picking and build/check testing

+ +

Done continuously up-to the pre-release announcement.

+ +

+As an exception, patches can be applied up-to the last ~1h before the actual +release. This is made only with explicit permission/request, +and the patch must be very well contained. Thus it cannot +affect more than one driver/subsystem. +

+Currently Ilia Mirkin and AMD devs have requested "permanent" exception. +

+ + +

make distcheck, scons and scons check must pass +
Testing with different version of system components - LLVM and others is also +performed where possible. +

+Achieved by combination of local ad-hoc scripts and AppVeyor plus Travis-CI, +the latter as part of their Github integration. +

+ +

Regression/functionality testing

+ +

+Less often (once or twice), shortly before the pre-release announcement. +Ensure that testing is redone if Intel devs have requested an exception, as per above. +

no regressions should be observed for Piglit/dEQP/CTS/Vulkan on Intel platforms +
no regressions should be observed for Piglit using the swrast, softpipe +and llvmpipe drivers +

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

+ + +

Making a branchpoint

+ +

+A branchpoint is made such that new development can continue in parallel to +stabilisation and bugfixing. +

+ +

+Note: Before doing a branch ensure that basic build and make check +testing is done and there are little to-no issues. +
+Ideally all of those should be tackled already. +

+ +

+Check if the version number is going to remain as, alternatively + git mv docs/relnotes/{current,new}.html as appropriate. +

+ +

+To setup the branchpoint: +

+	git checkout master # make sure we're in master first
+	git tag -s X.Y-branchpoint -m "Mesa X.Y branchpoint"
+	git checkout -b X.Y
+	git push origin X.Y-branchpoint X.Y
+

+ +

+Now go to +Bugzilla and add the new Mesa version X.Y. +

+Check for rare that there are no distribution breaking changes and revert them +if needed. Extremely rare - we had only one case so far (see +commit 2ced8eb136528914e1bf4e000dea06a9d53c7e04). +

+Proceed to release -rc1. +

+ +

Pre-release announcement

+ +

+It comes shortly after outstanding patches in the respective branch are pushed. +Developers can check, in brief, what's the status of their patches. They, +alongside very early testers, are strongly encouraged to test the branch and +report any regressions. +
+It is followed by a brief period (normally 24 or 48 hours) before the actual +release is made. +

+ +

Terminology used

Nominated

+Patch that is nominated but yet to to merged in the patch queue/branch. +

+ +

Queued

+Patch is in the queue/branch and will feature in the next release. +Barring reported regressions or objections from developers. +

+ +

Rejected

+Patch does not fit the +criteria and +is followed by a brief information. +
+The release maintainer is human so if you believe you've spotted a mistake do +let them know. +

+ +

Format/template

+Subject: [ANNOUNCE] Mesa X.Y.Z release candidate
+To: mesa-announce@...
+Cc: mesa-dev@...
+
+Hello list,
+
+The candidate for the Mesa X.Y.Z is now available. Currently we have:
+ - NUMBER queued
+ - NUMBER nominated (outstanding)
+ - and NUMBER rejected patches
+
+BRIEF SUMMARY OF CHANGES
+
+Take a look at section "Mesa stable queue" for more information.
+
+
+Testing reports/general approval
+--------------------------------
+Any testing reports (or general approval of the state of the branch) will be
+greatly appreciated.
+
+The plan is to have X.Y.Z this DAY (DATE), around or shortly after TIME.
+
+If you have any questions or suggestions - be that about the current patch
+queue or otherwise, please go ahead.
+
+
+Trivial merge conflicts
+-----------------------
+List of commits where manual intervention was required.
+Keep the authors in the CC list.
+
+commit SHA
+Author: AUTHOR
+
+    COMMIT SUMMARY
+
+    CHERRY PICKED FROM
+
+
+For example:
+
+commit 990f395e007c3204639daa34efc3049f350ee819
+Author: Emil Velikov <emil.velikov@collabora.com>
+
+    anv: automake: cleanup the generated json file during make clean
+
+    (cherry picked from commit 8df581520a823564be0ab5af7dbb7d501b1c9670)
+
+
+Cheers,
+Emil
+
+
+Mesa stable queue
+-----------------
+
+Nominated (NUMBER)
+==================
+
+AUTHOR (NUMBER):
+      SHA     COMMIT SUMMARY
+
+For example:
+
+Dave Airlie (1):
+      2de85eb radv: fix texturesamples to handle single sample case
+
+
+Queued (NUMBER)
+===============
+
+AUTHOR (NUMBER):
+      COMMIT SUMMARY
+
+
+Rejected (NUMBER)
+=================
+
+Rejected (11)
+=============
+
+AUTHOR (NUMBER):
+      SHA     COMMIT SUMMARY
+
+Reason: ...
+

+ +

Making a new release

+ +* process - manual + xorg tool ++ ^^ verify ++ touch test -> glxgears/info dota2vk + + +

+These are the instructions for making a new Mesa release. +

+ +

Get latest source files

+Ensure the latest code is available - both in your local master and the +relevant branch. +

+ +

Perform basic testing

+Most of the testing should already be done during the +cherry-pick and +pre-announce stages. + +So we do a quick 'touch test' +

make distcheck (you can omit this if you're not using --dist below) +
scons (from release tarball) +
the produced binaries work +

+ +

+Here is one solution that I've been using. +

+ +

+	git clean -fXd; git clean -nxd
+	read # quick cross check any outstanding files
+	export __mesa_root=../
+	export __build_root=./foo
+	chmod 755 -fR $__build_root; rm -rf $__build_root
+	mkdir -p $__build_root && cd $__build_root
+
+	 $__mesa_root/autogen.sh --enable-llvm-shared-libs && make -j2 distcheck
+
+	# Build check the tarballs (scons)
+	tar -xaf mesa-*.tar.xz && cd mesa-* && scons && cd ..
+
+	# Test the automake binaries
+	tar -xaf mesa-*.tar.xz && cd mesa-*
+	./configure \
+		--with-dri-drivers=i965,swrast \
+		--with-gallium-drivers=swrast \
+		--enable-llvm-shared-libs \
+		--enable-gallium-llvm
+	make -j2 && DESTDIR=`pwd`/test make -j6 install
+	export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/
+	export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/
+	xport LIBGL_DEBUG=verbose
+	glxinfo | egrep -o "Mesa.*"
+	glxgears
+	export LIBGL_ALWAYS_SOFTWARE=1
+	glxinfo | egrep -o "Mesa.*|Gallium.*"
+	glxgears
+	export LIBGL_ALWAYS_SOFTWARE=1
+	export GALLIUM_DRIVER=softpipe
+	glxinfo | egrep -o "Mesa.*|Gallium.*"
+	glxgears
+

+ +

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 (TBD) 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 and push the branch. +

+	git push origin HEAD
+

+ + +

Use the release.sh script from xorg util-macros

+ +

+If latest checkout [still] does not the mesa integration, fetch the patches +from Patchwork. +

+ +

+Ensure that the mesa git tree is clean via git clean -fXd and +start the release process. +

+	../relative/path/to/release.sh . # append --dist if you've already done distcheck above
+

+ +

+Pay close attention to the prompts as you might be required to enter your GPG +and SSH passphrase(s) to sign and upload the files, respectively. +

+ +

Add the sha256sums to the release notes

+ +

+Edit docs/relnotes/X.Y.Z.html to add the sha256sums as availabe in the mesa-X.Y.Z.announce template. Commit this change. +

+ +

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

+ +

+Something like the following steps will do the trick: +

+ +

+	git cherry-pick -x X.Y~1
+	git cherry-pick -x X.Y
+

+ +

+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 -as -m "docs: add news item and link release notes for X.Y.Z"
+	git push origin master X.Y
+

+ + +

Announce the release

+Use the generated template during the releasing process. +

+ + +

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 + +

+ + +

Update Bugzilla

+ +

+Parse through the bugreports as listed in the docs/relnotes/X.Y.Z.html +document. +
+If there's outstanding action, close the bug referencing the commit ID which +addresses the bug and mention the Mesa version that has the fix. +

+ +

+Note: the above is not applicable to all the reports, so use common sense. +

+ + +

Making a New Mesa Release

Get latest source files

Perform basic testing

Update version in file VERSION

Create release notes for the new release

Make the release archives, signatures, and the release tag

Add the sha256sums to the release notes

Push all commits and the tag created above

Install the release files and signatures on the distribution server

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

Update the mesa3d.org website

Announce the release

Adding Extensions

The Mesa 3D Graphics Library

Releasing process

Overview

Release schedule

Feature releases

Stable releases

Cherry-picking and testing

Cherry-picking and build/check testing

Regression/functionality testing

Making a branchpoint

Pre-release announcement

Terminology used

Format/template

Making a new release

Get latest source files

Perform basic testing

Update version in file VERSION

Create release notes for the new release

Use the release.sh script from xorg util-macros

Add the sha256sums to the release notes

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

Announce the release

Update the mesa3d.org website

Update Bugzilla