X-Git-Url: https://git.libre-soc.org/?a=blobdiff_plain;f=docs%2Freleasing.html;h=3d529f889ab0de67d818ec3c1394e1c3486abc7a;hb=b06471b77d5c35e04499c7ac27fce8c21bbadd2d;hp=020f3dec70a516cbe65d2ff40066a65bea986ed5;hpb=1d104f9aa71aae1ef7c64f3a52dbfb1f62ddaa31;p=mesa.git diff --git a/docs/releasing.html b/docs/releasing.html index 020f3dec70a..3d529f889ab 100644 --- a/docs/releasing.html +++ b/docs/releasing.html @@ -2,38 +2,41 @@ - Releasing process + Releasing Process
-

The Mesa 3D Graphics Library

+ The Mesa 3D Graphics Library
-

Releasing process

+ +

Releasing Process

-

Overview

+ +

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.

@@ -42,397 +45,319 @@ 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
+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

+ +

Release schedule

+ +

+Releases should happen on Wednesdays. Delays can occur although those +should be kept to a minimum. +

-Releases should happen on Fridays. Delays can occur although those should be keep -to a minimum. +See our calendar +for information about how the release schedule is planned, and the +date and other details for individual releases.

Feature releases

Stable releases

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. +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 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. +This also involves that, as a final release may be delayed due to the +need of additional candidates to solve some blocking regression(s), +the release manager might have to update +the calendar with +additional bug fix releases of the current stable branch.

- -

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

+

Cherry-picking and testing

-

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

-

-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. +Commits nominated for the active branch are picked as based on the +criteria as +described in the same section.

- -

Making a branchpoint

-

-A branchpoint is made such that new development can continue in parallel to -stabilisation and bugfixing. +Nominations happen via special tags in the commit messages, and via gitlab +merge requests against the staging branches. There are special scripts used +to read the tags.

-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. +The maintainer should watch or be in contact with the Intel CI team, as well +as watch the gitlab CI for regressions.

-Check if the version number is going to remain as, alternatively - git mv docs/relnotes/{current,new}.html as appropriate. +Cherry picking should be done with the '-x' switch (to automatically add +"cherry picked from ..." to the commit message):

-

-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 checkout master
-	$EDITOR VERSION # bump the version number
-	git commit -as
-	cp docs/relnotes/{X.Y,X.Y+1}.html # copy/create relnotes template
-	git commit -as
-	git push origin X.Y-branchpoint X.Y
-
+ +git cherry-pick -x abcdef12345667890 +

-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. +Developers can request, as an exception, patches to be applied up-to +the last one hour 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.

-

Pre-release announcement

+

Following developers have requested permanent exception

+ + +

The gitlab CI must pass.

-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. +For Windows related changes, the main contact point is Brian +Paul. Jose Fonseca can also help as a fallback contact.

-

Terminology used

-

-Patch that is nominated but yet to to merged in the patch queue/branch. +For Android related changes, the main contact is Tapani +Pälli. Mauro Rossi is collaborating with android-x86 and may +provide feedback about the build status in that project.

-

-Patch is in the queue/branch and will feature in the next release. -Barring reported regressions or objections from developers. +For MacOSX related changes, Jeremy Huddleston Sequoia is currently a +good contact point.

-

-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. +Note: If a patch in the current queue needs any additional +fix(es), then they should be squashed together. The commit messages and the +"cherry picked from"-tags must be preserved.

-

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
+git show b10859ec41d09c57663a258f43fe57c12332698e
 
-Take a look at section "Mesa stable queue" for more information.
+commit b10859ec41d09c57663a258f43fe57c12332698e
+Author: Jonas Pfeil <pfeiljonas@gmx.de>
+Date:   Wed Mar 1 18:11:10 2017 +0100
 
+    ralloc: Make sure ralloc() allocations match malloc()'s alignment.
 
-Testing reports/general approval
---------------------------------
-Any testing reports (or general approval of the state of the branch) will be
-greatly appreciated.
+    The header of ralloc needs to be aligned, because the compiler assumes
+    ...
 
-The plan is to have X.Y.Z this DAY (DATE), around or shortly after TIME.
+    (cherry picked from commit cd2b55e536dc806f9358f71db438dd9c246cdb14)
 
-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:
+    Squashed with commit:
 
-commit 990f395e007c3204639daa34efc3049f350ee819
-Author: Emil Velikov <emil.velikov@collabora.com>
+    ralloc: don't leave out the alignment factor
 
-    anv: automake: cleanup the generated json file during make clean
-
-    (cherry picked from commit 8df581520a823564be0ab5af7dbb7d501b1c9670)
-
-
-Cheers,
-Emil
+    Experimentation shows that without alignment factor gcc and clang choose
+    ...
 
+    (cherry picked from commit ff494fe999510ea40e3ed5827e7818550b6de126)
+
-Mesa stable queue ------------------ +

Regression/functionality testing

-Nominated (NUMBER) -================== + -AUTHOR (NUMBER): - SHA COMMIT SUMMARY +

Staging branch

-For example: +

+A live branch, which contains the currently merge/rejected patches is available +in the main repository under staging/X.Y. For example: +

+
+staging/18.1 - WIP branch for the 18.1 series
+staging/18.2 - WIP branch for the 18.2 series
+
-Dave Airlie (1): - 2de85eb radv: fix texturesamples to handle single sample case +

+Notes: +

+ -Queued (NUMBER) -=============== +

Making a branchpoint

-AUTHOR (NUMBER): - COMMIT SUMMARY +

+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 meson test +testing is done and there are little to-no issues. Ideally all of those should +be tackled already. +

-Rejected (NUMBER) -================= +

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

-Rejected (11) -============= +

+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 checkout master
+$EDITOR VERSION # bump the version number
+git commit -as
+truncate docs/relnotes/new_features.txt
+git commit -a
+git push origin X.Y-branchpoint X.Y
+
-AUTHOR (NUMBER): - SHA COMMIT SUMMARY +

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

-Reason: ... - +

+Check that there are no distribution breaking changes and revert them if needed. +For example: files being overwritten on install, etc. Happens extremely rarely - +we had only one case so far (see commit 2ced8eb136528914e1bf4e000dea06a9d53c7e04). +

-

Making a new release

+

Making a new release

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

+

Perform basic testing

+

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

+

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

-	git clean -fXd; git clean -nxd
-	read # quick cross check any outstanding files
-	export __version=`cat VERSION`
-	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-$__version.tar.xz && cd mesa-$__version && scons && cd ..
-
-	# Test the automake binaries
-	rm -rf mesa-$__version
-	tar -xaf mesa-$__version.tar.xz && cd mesa-$__version
-	./configure \
-		--with-dri-drivers=i965,swrast \
-		--with-gallium-drivers=swrast \
-		--with-vulkan-drivers=intel \
-		--enable-llvm-shared-libs \
-		--enable-gallium-llvm \
-		--enable-glx-tls \
-		--enable-gbm \
-		--enable-egl \
-		--with-egl-platforms=x11,drm,wayland
-	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/
-	export LIBGL_DEBUG=verbose
-	glxinfo | egrep -o "Mesa.*"
-	glxgears
-	es2_info | egrep "GL_VERSION|GL_RENDERER"
-	es2gears_x11
-	export LIBGL_ALWAYS_SOFTWARE=1
-	glxinfo | egrep -o "Mesa.*|Gallium.*"
-	glxgears
-	es2_info | egrep "GL_VERSION|GL_RENDERER"
-	es2gears_x11
-	export LIBGL_ALWAYS_SOFTWARE=1
-	export GALLIUM_DRIVER=softpipe
-	glxinfo | egrep -o "Mesa.*|Gallium.*"
-	glxgears
-	es2_info | egrep "GL_VERSION|GL_RENDERER"
-	es2gears_x11
-	# Smoke test DOTA2
-	unset LD_LIBRARY_PATH
-	unset LIBGL_DRIVERS_PATH
-	unset LIBGL_DEBUG
-	unset LIBGL_ALWAYS_SOFTWARE
-	export VK_ICD_FILENAMES=`pwd`/src/intel/vulkan/dev_icd.json
-	steam steam://rungameid/570  -vconsole -vulkan
+__glxgears_cmd='glxgears 2>&1 | grep -v "configuration file"'
+__es2info_cmd='es2_info 2>&1 | egrep "GL_VERSION|GL_RENDERER|.*dri\.so"'
+__es2gears_cmd='es2gears_x11 2>&1 | grep -v "configuration file"'
+test "x$LD_LIBRARY_PATH" != 'x' && __old_ld="$LD_LIBRARY_PATH"
+export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/:"${__old_ld}"
+export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/
+export LIBGL_DEBUG=verbose
+eval $__glxinfo_cmd
+eval $__glxgears_cmd
+eval $__es2info_cmd
+eval $__es2gears_cmd
+export LIBGL_ALWAYS_SOFTWARE=true
+eval $__glxinfo_cmd
+eval $__glxgears_cmd
+eval $__es2info_cmd
+eval $__es2gears_cmd
+export LIBGL_ALWAYS_SOFTWARE=true
+export GALLIUM_DRIVER=softpipe
+eval $__glxinfo_cmd
+eval $__glxgears_cmd
+eval $__es2info_cmd
+eval $__es2gears_cmd
+# Smoke test DOTA2
+unset LD_LIBRARY_PATH
+test "x$__old_ld" != 'x' && export LD_LIBRARY_PATH="$__old_ld" && unset __old_ld
+unset LIBGL_DRIVERS_PATH
+unset LIBGL_DEBUG
+unset LIBGL_ALWAYS_SOFTWARE
+unset GALLIUM_DRIVER
+export VK_ICD_FILENAMES=`pwd`/test/usr/local/share/vulkan/icd.d/intel_icd.x86_64.json
+steam steam://rungameid/570  -vconsole -vulkan
+unset VK_ICD_FILENAMES
-

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: +The release notes are completely generated by the +bin/gen_release_notes.py script. Simply run this script before +bumping the version, and commit the results. -

-	./bin/bugzilla_mesa.sh
-	./bin/shortlog_mesa.sh
-
+The only thing left to do is add the sha256 sums. +

-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. +Increment the version contained in the file VERSION at Mesa's top-level, then +commit this change.

Commit these changes and push the branch.

+ 
-	git push origin HEAD
+git push origin HEAD
-

Use the release.sh script from xorg util-macros

+

Use the release.sh script from xorg util-modular

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

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

@@ -443,7 +368,7 @@ 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. +Edit docs/relnotes/X.Y.Z.html to add the sha256sum as available in the mesa-X.Y.Z.announce template. Commit this change.

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

@@ -453,55 +378,39 @@ Something like the following steps will do the trick: 

-	git cherry-pick -x X.Y~1
-	git cherry-pick -x X.Y
+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: +

Then run the 

./bin/post_version.py X.Y.Z
, where X.Y.Z is the +version you just made. This will updated docs/relnotes.html, +docs/index.html, and docs/release-calendar.html. It will then generate +a git commit automatically. Check that everything looks correct 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

+

Announce the release

-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. +Use the generated template during the releasing process.

-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 - +Again, pay attention to add a note to warn about a final release in a +series, if that is the case.

-

Update Bugzilla

+

Update gitlab issues

-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. +Parse through the bug reports 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.