Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 1 | Releasing Process |
| 2 | ================= |
| 3 | |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 4 | Overview |
| 5 | -------- |
| 6 | |
| 7 | This document uses the convention X.Y.Z for the release number with X.Y |
| 8 | being the stable branch name. |
| 9 | |
| 10 | Mesa provides feature and bugfix releases. Former use zero as patch |
| 11 | version (Z), while the latter have a non-zero one. |
| 12 | |
| 13 | For example: |
| 14 | |
| 15 | :: |
| 16 | |
| 17 | Mesa 10.1.0 - 10.1 branch, feature |
| 18 | Mesa 10.1.4 - 10.1 branch, bugfix |
| 19 | Mesa 12.0.0 - 12.0 branch, feature |
| 20 | Mesa 12.0.2 - 12.0 branch, bugfix |
| 21 | |
| 22 | .. _schedule: |
| 23 | |
| 24 | Release schedule |
| 25 | ---------------- |
| 26 | |
| 27 | Releases should happen on Wednesdays. Delays can occur although those |
| 28 | should be kept to a minimum. |
| 29 | |
Erik Faye-Lund | 9be0e2d | 2020-06-15 12:31:36 +0200 | [diff] [blame] | 30 | See our :doc:`calendar <release-calendar>` for information about how |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 31 | the release schedule is planned, and the date and other details for |
| 32 | individual releases. |
| 33 | |
| 34 | Feature releases |
| 35 | ---------------- |
| 36 | |
| 37 | - Available approximately every three months. |
Erik Faye-Lund | 2dccdb1 | 2020-09-25 15:00:39 +0200 | [diff] [blame^] | 38 | - Initial time plan available 2-4 weeks before the planned branchpoint |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 39 | (rc1) on the mesa-announce@ mailing list. |
| 40 | - Typically, the final release will happen after 4 candidates. |
| 41 | Additional ones may be needed in order to resolve blocking |
| 42 | regressions, though. |
| 43 | |
| 44 | Stable releases |
| 45 | --------------- |
| 46 | |
| 47 | - Normally available once every two weeks. |
| 48 | - Only the latest branch has releases. See note below. |
| 49 | |
Erik Faye-Lund | bf3f0f7 | 2019-06-04 10:39:58 +0200 | [diff] [blame] | 50 | .. note:: |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 51 | |
Erik Faye-Lund | bf3f0f7 | 2019-06-04 10:39:58 +0200 | [diff] [blame] | 52 | There is one or two releases overlap when changing branches. For |
| 53 | example: |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 54 | |
Erik Faye-Lund | bf3f0f7 | 2019-06-04 10:39:58 +0200 | [diff] [blame] | 55 | The final release from the 12.0 series Mesa 12.0.5 will be out around |
| 56 | the same time (or shortly after) 13.0.1 is out. |
| 57 | |
| 58 | This also involves that, as a final release may be delayed due to the |
| 59 | need of additional candidates to solve some blocking regression(s), the |
| 60 | release manager might have to update the |
Erik Faye-Lund | 9be0e2d | 2020-06-15 12:31:36 +0200 | [diff] [blame] | 61 | :doc:`calendar <release-calendar>` with additional bug fix releases of |
Erik Faye-Lund | bf3f0f7 | 2019-06-04 10:39:58 +0200 | [diff] [blame] | 62 | the current stable branch. |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 63 | |
| 64 | .. _pickntest: |
| 65 | |
| 66 | Cherry-picking and testing |
| 67 | -------------------------- |
| 68 | |
| 69 | Commits nominated for the active branch are picked as based on the |
Erik Faye-Lund | 9be0e2d | 2020-06-15 12:31:36 +0200 | [diff] [blame] | 70 | :ref:`criteria <criteria>` as described in the same |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 71 | section. |
| 72 | |
| 73 | Nominations happen via special tags in the commit messages, and via |
| 74 | gitlab merge requests against the staging branches. There are special |
| 75 | scripts used to read the tags. |
| 76 | |
| 77 | The maintainer should watch or be in contact with the Intel CI team, as |
| 78 | well as watch the gitlab CI for regressions. |
| 79 | |
| 80 | Cherry picking should be done with the '-x' switch (to automatically add |
| 81 | "cherry picked from ..." to the commit message): |
| 82 | |
| 83 | ``git cherry-pick -x abcdef12345667890`` |
| 84 | |
| 85 | Developers can request, *as an exception*, patches to be applied up-to |
| 86 | the last one hour before the actual release. This is made **only** with |
| 87 | explicit permission/request, and the patch **must** be very well |
| 88 | contained. Thus it cannot affect more than one driver/subsystem. |
| 89 | |
| 90 | Following developers have requested permanent exception |
| 91 | |
| 92 | - *Ilia Mirkin* |
| 93 | - *AMD team* |
| 94 | |
| 95 | The gitlab CI must pass. |
| 96 | |
| 97 | For Windows related changes, the main contact point is Brian Paul. Jose |
| 98 | Fonseca can also help as a fallback contact. |
| 99 | |
| 100 | For Android related changes, the main contact is Tapani Pรคlli. Mauro |
| 101 | Rossi is collaborating with android-x86 and may provide feedback about |
| 102 | the build status in that project. |
| 103 | |
| 104 | For MacOSX related changes, Jeremy Huddleston Sequoia is currently a |
| 105 | good contact point. |
| 106 | |
Erik Faye-Lund | bf3f0f7 | 2019-06-04 10:39:58 +0200 | [diff] [blame] | 107 | .. note:: |
| 108 | |
| 109 | If a patch in the current queue needs any additional fix(es), |
| 110 | then they should be squashed together. The commit messages and the |
| 111 | "``cherry picked from``"-tags must be preserved. |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 112 | |
| 113 | :: |
| 114 | |
| 115 | git show b10859ec41d09c57663a258f43fe57c12332698e |
| 116 | |
| 117 | commit b10859ec41d09c57663a258f43fe57c12332698e |
| 118 | Author: Jonas Pfeil <pfeiljonas@gmx.de> |
| 119 | Date: Wed Mar 1 18:11:10 2017 +0100 |
| 120 | |
| 121 | ralloc: Make sure ralloc() allocations match malloc()'s alignment. |
| 122 | |
| 123 | The header of ralloc needs to be aligned, because the compiler assumes |
| 124 | ... |
| 125 | |
| 126 | (cherry picked from commit cd2b55e536dc806f9358f71db438dd9c246cdb14) |
| 127 | |
| 128 | Squashed with commit: |
| 129 | |
| 130 | ralloc: don't leave out the alignment factor |
| 131 | |
| 132 | Experimentation shows that without alignment factor gcc and clang choose |
| 133 | ... |
| 134 | |
| 135 | (cherry picked from commit ff494fe999510ea40e3ed5827e7818550b6de126) |
| 136 | |
| 137 | Regression/functionality testing |
| 138 | -------------------------------- |
| 139 | |
| 140 | - *no regressions should be observed for Piglit/dEQP/CTS/Vulkan on |
| 141 | Intel platforms* |
| 142 | - *no regressions should be observed for Piglit using the swrast, |
| 143 | softpipe and llvmpipe drivers* |
| 144 | |
| 145 | .. _stagingbranch: |
| 146 | |
| 147 | Staging branch |
| 148 | -------------- |
| 149 | |
| 150 | A live branch, which contains the currently merge/rejected patches is |
| 151 | available in the main repository under ``staging/X.Y``. For example: |
| 152 | |
| 153 | :: |
| 154 | |
| 155 | staging/18.1 - WIP branch for the 18.1 series |
| 156 | staging/18.2 - WIP branch for the 18.2 series |
| 157 | |
| 158 | Notes: |
| 159 | |
| 160 | - People are encouraged to test the staging branch and report |
| 161 | regressions. |
| 162 | - The branch history is not stable and it **will** be rebased, |
| 163 | |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 164 | Making a branchpoint |
| 165 | -------------------- |
| 166 | |
| 167 | A branchpoint is made such that new development can continue in parallel |
| 168 | to stabilisation and bugfixing. |
| 169 | |
Erik Faye-Lund | bf3f0f7 | 2019-06-04 10:39:58 +0200 | [diff] [blame] | 170 | .. note:: |
| 171 | |
| 172 | Before doing a branch ensure that basic build and ``meson test`` |
| 173 | testing is done and there are little to-no issues. Ideally all of those |
| 174 | should be tackled already. |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 175 | |
| 176 | Check if the version number is going to remain as, alternatively |
Erik Faye-Lund | f1fe74a | 2020-04-20 13:10:12 +0200 | [diff] [blame] | 177 | ``git mv docs/relnotes/{current,new}.rst`` as appropriate. |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 178 | |
| 179 | To setup the branchpoint: |
| 180 | |
| 181 | :: |
| 182 | |
| 183 | git checkout master # make sure we're in master first |
| 184 | git tag -s X.Y-branchpoint -m "Mesa X.Y branchpoint" |
| 185 | git checkout -b X.Y |
| 186 | git checkout master |
| 187 | $EDITOR VERSION # bump the version number |
| 188 | git commit -as |
| 189 | truncate docs/relnotes/new_features.txt |
| 190 | git commit -a |
| 191 | git push origin X.Y-branchpoint X.Y |
| 192 | |
| 193 | Now go to |
| 194 | `gitlab <https://gitlab.freedesktop.org/mesa/mesa/-/milestones>`__ and |
| 195 | add the new Mesa version X.Y. |
| 196 | |
| 197 | Check that there are no distribution breaking changes and revert them if |
| 198 | needed. For example: files being overwritten on install, etc. Happens |
| 199 | extremely rarely - we had only one case so far (see commit |
| 200 | 2ced8eb136528914e1bf4e000dea06a9d53c7e04). |
| 201 | |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 202 | Making a new release |
| 203 | -------------------- |
| 204 | |
| 205 | These are the instructions for making a new Mesa release. |
| 206 | |
| 207 | Get latest source files |
| 208 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 209 | |
| 210 | Ensure the latest code is available - both in your local master and the |
| 211 | relevant branch. |
| 212 | |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 213 | Perform basic testing |
| 214 | ~~~~~~~~~~~~~~~~~~~~~ |
| 215 | |
| 216 | Most of the testing should already be done during the |
Erik Faye-Lund | 9be0e2d | 2020-06-15 12:31:36 +0200 | [diff] [blame] | 217 | :ref:`cherry-pick <pickntest>` So we do a quick 'touch test' |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 218 | |
| 219 | - meson dist |
| 220 | - scons (from release tarball) |
| 221 | - the produced binaries work |
| 222 | |
| 223 | Here is one solution: |
| 224 | |
| 225 | :: |
| 226 | |
| 227 | __glxgears_cmd='glxgears 2>&1 | grep -v "configuration file"' |
| 228 | __es2info_cmd='es2_info 2>&1 | egrep "GL_VERSION|GL_RENDERER|.*dri\.so"' |
| 229 | __es2gears_cmd='es2gears_x11 2>&1 | grep -v "configuration file"' |
| 230 | test "x$LD_LIBRARY_PATH" != 'x' && __old_ld="$LD_LIBRARY_PATH" |
| 231 | export LD_LIBRARY_PATH=`pwd`/test/usr/local/lib/:"${__old_ld}" |
| 232 | export LIBGL_DRIVERS_PATH=`pwd`/test/usr/local/lib/dri/ |
| 233 | export LIBGL_DEBUG=verbose |
| 234 | eval $__glxinfo_cmd |
| 235 | eval $__glxgears_cmd |
| 236 | eval $__es2info_cmd |
| 237 | eval $__es2gears_cmd |
| 238 | export LIBGL_ALWAYS_SOFTWARE=true |
| 239 | eval $__glxinfo_cmd |
| 240 | eval $__glxgears_cmd |
| 241 | eval $__es2info_cmd |
| 242 | eval $__es2gears_cmd |
| 243 | export LIBGL_ALWAYS_SOFTWARE=true |
| 244 | export GALLIUM_DRIVER=softpipe |
| 245 | eval $__glxinfo_cmd |
| 246 | eval $__glxgears_cmd |
| 247 | eval $__es2info_cmd |
| 248 | eval $__es2gears_cmd |
| 249 | # Smoke test DOTA2 |
| 250 | unset LD_LIBRARY_PATH |
| 251 | test "x$__old_ld" != 'x' && export LD_LIBRARY_PATH="$__old_ld" && unset __old_ld |
| 252 | unset LIBGL_DRIVERS_PATH |
| 253 | unset LIBGL_DEBUG |
| 254 | unset LIBGL_ALWAYS_SOFTWARE |
| 255 | unset GALLIUM_DRIVER |
| 256 | export VK_ICD_FILENAMES=`pwd`/test/usr/local/share/vulkan/icd.d/intel_icd.x86_64.json |
| 257 | steam steam://rungameid/570 -vconsole -vulkan |
| 258 | unset VK_ICD_FILENAMES |
| 259 | |
| 260 | Create release notes for the new release |
| 261 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 262 | |
| 263 | The release notes are completely generated by the |
Eric Engestrom | 0338db5 | 2020-07-09 01:26:31 +0200 | [diff] [blame] | 264 | ``bin/gen_release_notes.py`` script. Simply run this script **before** |
| 265 | bumping the version. You'll need to come back to this file once the |
| 266 | tarball is generated to add its ``sha256sum``. |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 267 | |
Eric Engestrom | 0338db5 | 2020-07-09 01:26:31 +0200 | [diff] [blame] | 268 | Increment the version contained in the file ``VERSION`` at Mesa's top-level, |
| 269 | then commit this change and **push the branch** (if you forget to do |
| 270 | this, ``release.sh`` below will fail). |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 271 | |
| 272 | Use the release.sh script from xorg `util-modular <https://cgit.freedesktop.org/xorg/util/modular/>`__ |
| 273 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 274 | |
| 275 | Start the release process. |
| 276 | |
| 277 | :: |
| 278 | |
| 279 | ../relative/path/to/release.sh . # append --dist if you've already done distcheck above |
| 280 | |
| 281 | Pay close attention to the prompts as you might be required to enter |
| 282 | your GPG and SSH passphrase(s) to sign and upload the files, |
| 283 | respectively. |
| 284 | |
Eric Engestrom | 31a66cb | 2019-11-22 14:21:05 +0000 | [diff] [blame] | 285 | Ensure that you do sign the tarballs, that your key is mentioned in the |
Eric Engestrom | 677c1bd | 2020-06-20 00:35:58 +0200 | [diff] [blame] | 286 | release notes, and is published in `release-maintainers-keys.asc |
| 287 | <release-maintainers-keys.asc>`__. |
Eric Engestrom | 31a66cb | 2019-11-22 14:21:05 +0000 | [diff] [blame] | 288 | |
| 289 | |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 290 | Add the sha256sums to the release notes |
| 291 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 292 | |
Eric Engestrom | 0338db5 | 2020-07-09 01:26:31 +0200 | [diff] [blame] | 293 | Edit ``docs/relnotes/X.Y.Z.rst`` to add the ``sha256sum`` as available in the |
| 294 | ``mesa-X.Y.Z.announce`` template. Commit this change. |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 295 | |
| 296 | Back on mesa master, add the new release notes into the tree |
| 297 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 298 | |
| 299 | Something like the following steps will do the trick: |
| 300 | |
| 301 | :: |
| 302 | |
| 303 | git cherry-pick -x X.Y~1 |
| 304 | git cherry-pick -x X.Y |
| 305 | |
| 306 | Then run the |
| 307 | |
| 308 | :: |
| 309 | |
| 310 | ./bin/post_version.py X.Y.Z |
| 311 | |
Eric Engestrom | f5353e0 | 2020-06-23 02:16:57 +0200 | [diff] [blame] | 312 | , where X.Y.Z is the version you just made. This will update |
| 313 | docs/relnotes.rst and docs/release-calendar.rst. It will then generate |
| 314 | a git commit automatically. Check that everything looks correct and |
| 315 | push: |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 316 | |
| 317 | :: |
| 318 | |
| 319 | git push origin master X.Y |
| 320 | |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 321 | Announce the release |
| 322 | -------------------- |
| 323 | |
| 324 | Use the generated template during the releasing process. |
| 325 | |
| 326 | Again, pay attention to add a note to warn about a final release in a |
| 327 | series, if that is the case. |
| 328 | |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 329 | Update gitlab issues |
| 330 | -------------------- |
| 331 | |
Erik Faye-Lund | f1fe74a | 2020-04-20 13:10:12 +0200 | [diff] [blame] | 332 | Parse through the bug reports as listed in the docs/relnotes/X.Y.Z.rst |
Erik Faye-Lund | 4d06683 | 2020-06-12 20:09:42 +0200 | [diff] [blame] | 333 | document. If there's outstanding action, close the bug referencing the |
| 334 | commit ID which addresses the bug and mention the Mesa version that has |
| 335 | the fix. |
| 336 | |
Erik Faye-Lund | bf3f0f7 | 2019-06-04 10:39:58 +0200 | [diff] [blame] | 337 | .. note: the above is not applicable to all the reports, so use common sense. |