project/RELEASE-CHECKLIST.md

   1 # Release Checklist
   2 ## A maintainer's guide to releasing Docker
   3
   4 So you're in charge of a Docker release? Cool. Here's what to do.
   5
   6 If your experience deviates from this document, please document the changes
   7 to keep it up-to-date.
   8
   9 It is important to note that this document assumes that the git remote in your
  10 repository that corresponds to "https://github.com/docker/docker" is named
  11 "origin".  If yours is not (for example, if you've chosen to name it "upstream"
  12 or something similar instead), be sure to adjust the listed snippets for your
  13 local environment accordingly.  If you are not sure what your upstream remote is
  14 named, use a command like `git remote -v` to find out.
  15
  16 If you don't have an upstream remote, you can add one easily using something
  17 like:
  18
  19 ```bash
  20 export GITHUBUSER="YOUR_GITHUB_USER"
  21 git remote add origin https://github.com/docker/docker.git
  22 git remote add $GITHUBUSER git@github.com:$GITHUBUSER/docker.git
  23 ```
  24
  25 ### 1. Pull from master and create a release branch
  26
  27 All releases version numbers will be of the form: vX.Y.Z  where X is the major
  28 version number, Y is the minor version number and Z is the patch release version number.
  29
  30 #### Major releases
  31
  32 The release branch name is just vX.Y because it's going to be the basis for all .Z releases.
  33
  34 ```bash
  35 export BASE=vX.Y
  36 export VERSION=vX.Y.Z
  37 git fetch origin
  38 git checkout --track origin/master
  39 git checkout -b release/$BASE
  40 ```
  41
  42 This new branch is going to be the base for the release. We need to push it to origin so we
  43 can track the cherry-picked changes and the version bump:
  44
  45 ```bash
  46 git push origin release/$BASE
  47 ```
  48
  49 When you have the major release branch in origin, we need to create the bump fork branch
  50 that we'll push to our fork:
  51
  52 ```bash
  53 git checkout -b bump_$VERSION
  54 ```
  55
  56 #### Patch releases
  57
  58 If we have the release branch in origin, we can create the forked bump branch from it directly:
  59
  60 ```bash
  61 export VERSION=vX.Y.Z
  62 export PATCH=vX.Y.Z+1
  63 git fetch origin
  64 git checkout --track origin/release/$BASE
  65 git checkout -b bump_$PATCH
  66 ```
  67
  68 We cherry-pick only the commits we want into the bump branch:
  69
  70 ```bash
  71 # get the commits ids we want to cherry-pick
  72 git log
  73 # cherry-pick the commits starting from the oldest one, without including merge commits
  74 git cherry-pick -s -x <commit-id>
  75 git cherry-pick -s -x <commit-id>
  76 ...
  77 ```
  78
  79 ### 2. Update the VERSION files and API version on master
  80
  81 We don't want to stop contributions to master just because we are releasing.
  82 So, after the release branch is up, we bump the VERSION and API version to mark
  83 the start of the "next" release.
  84
  85 #### 2.1 Update the VERSION files
  86
  87 Update the content of the `VERSION` file to be the next minor (incrementing Y)
  88 and add the `-dev` suffix. For example, after the release branch for 1.5.0 is
  89 created, the `VERSION` file gets updated to `1.6.0-dev` (as in "1.6.0 in the
  90 making").
  91
  92 #### 2.2 Update API version on master
  93
  94 We don't want API changes to go to the now frozen API version. Create a new
  95 entry in `docs/reference/api/` by copying the latest and bumping the version
  96 number (in both the file's name and content), and submit this in a PR against
  97 master.
  98
  99 ### 3. Update CHANGELOG.md
 100
 101 You can run this command for reference with git 2.0:
 102
 103 ```bash
 104 git fetch --tags
 105 LAST_VERSION=$(git tag -l --sort=-version:refname "v*" | grep -E 'v[0-9\.]+$' | head -1)
 106 git log --stat $LAST_VERSION..bump_$VERSION
 107 ```
 108
 109 If you don't have git 2.0 but have a sort command that supports `-V`:
 110 ```bash
 111 git fetch --tags
 112 LAST_VERSION=$(git tag -l | grep -E 'v[0-9\.]+$' | sort -rV | head -1)
 113 git log --stat $LAST_VERSION..bump_$VERSION
 114 ```
 115
 116 If releasing a major version (X or Y increased in vX.Y.Z), simply listing notable user-facing features is sufficient.
 117 ```markdown
 118 #### Notable features since <last major version>
 119 * New docker command to do something useful
 120 * Engine API change (deprecating old version)
 121 * Performance improvements in some usecases
 122 * ...
 123 ```
 124
 125 For minor releases (only Z increases in vX.Y.Z), provide a list of user-facing changes.
 126 Each change should be listed under a category heading formatted as `#### CATEGORY`.
 127
 128 `CATEGORY` should describe which part of the project is affected.
 129   Valid categories are:
 130   * Builder
 131   * Documentation
 132   * Hack
 133   * Packaging
 134   * Engine API
 135   * Runtime
 136   * Other (please use this category sparingly)
 137
 138 Each change should be formatted as `BULLET DESCRIPTION`, given:
 139
 140 * BULLET: either `-`, `+` or `*`, to indicate a bugfix, new feature or
 141   upgrade, respectively.
 142
 143 * DESCRIPTION: a concise description of the change that is relevant to the
 144   end-user, using the present tense. Changes should be described in terms
 145   of how they affect the user, for example "Add new feature X which allows Y",
 146   "Fix bug which caused X", "Increase performance of Y".
 147
 148 EXAMPLES:
 149
 150 ```markdown
 151 ## 0.3.6 (1995-12-25)
 152
 153 #### Builder
 154
 155 + 'docker build -t FOO .' applies the tag FOO to the newly built image
 156
 157 #### Engine API
 158
 159 - Fix a bug in the optional unix socket transport
 160
 161 #### Runtime
 162
 163 * Improve detection of kernel version
 164 ```
 165
 166 If you need a list of contributors between the last major release and the
 167 current bump branch, use something like:
 168 ```bash
 169 git log --format='%aN <%aE>' v0.7.0...bump_v0.8.0 | sort -uf
 170 ```
 171 Obviously, you'll need to adjust version numbers as necessary.  If you just need
 172 a count, add a simple `| wc -l`.
 173
 174 ### 4. Change the contents of the VERSION file
 175
 176 Before the big thing, you'll want to make successive release candidates and get
 177 people to test. The release candidate number `N` should be part of the version:
 178
 179 ```bash
 180 export RC_VERSION=${VERSION}-rcN
 181 echo ${RC_VERSION#v} > VERSION
 182 ```
 183
 184 ### 5. Test the docs
 185
 186 Make sure that your tree includes documentation for any modified or
 187 new features, syntax or semantic changes.
 188
 189 To test locally:
 190
 191 ```bash
 192 make docs
 193 ```
 194
 195 To make a shared test at https://beta-docs.docker.io:
 196
 197 (You will need the `awsconfig` file added to the `docs/` dir)
 198
 199 ```bash
 200 make AWS_S3_BUCKET=beta-docs.docker.io BUILD_ROOT=yes docs-release
 201 ```
 202
 203 ### 6. Commit and create a pull request to the "release" branch
 204
 205 ```bash
 206 git add VERSION CHANGELOG.md
 207 git commit -m "Bump version to $VERSION"
 208 git push $GITHUBUSER bump_$VERSION
 209 echo "https://github.com/$GITHUBUSER/docker/compare/docker:release/$BASE...$GITHUBUSER:bump_$VERSION?expand=1"
 210 ```
 211
 212 That last command will give you the proper link to visit to ensure that you
 213 open the PR against the "release" branch instead of accidentally against
 214 "master" (like so many brave souls before you already have).
 215
 216 ### 7. Create a PR to update the AUTHORS file for the release
 217
 218 Update the AUTHORS file, by running the `hack/generate-authors.sh` on the
 219 release branch. To prevent duplicate entries, you may need to update the
 220 `.mailmap` file accordingly.
 221
 222 ### 8. Build release candidate rpms and debs
 223
 224 **NOTE**: It will be a lot faster if you pass a different graphdriver with
 225 `DOCKER_GRAPHDRIVER` than `vfs`.
 226
 227 ```bash
 228 docker build -t docker .
 229 docker run \
 230     --rm -t --privileged \
 231     -e DOCKER_GRAPHDRIVER=aufs \
 232     -v $(pwd)/bundles:/go/src/github.com/docker/docker/bundles \
 233     docker \
 234     hack/make.sh binary build-deb build-rpm
 235 ```
 236
 237 ### 9. Publish release candidate rpms and debs
 238
 239 With the rpms and debs you built from the last step you can release them on the
 240 same server, or ideally, move them to a dedicated release box via scp into
 241 another docker/docker directory in bundles. This next step assumes you have
 242 a checkout of the docker source code at the same commit you used to build, with
 243 the artifacts from the last step in `bundles`.
 244
 245 **NOTE:** If you put a space before the command your `.bash_history` will not
 246 save it. (for the `GPG_PASSPHRASE`).
 247
 248 ```bash
 249 docker build -t docker .
 250 docker run --rm -it --privileged \
 251     -v /volumes/repos:/volumes/repos \
 252     -v $(pwd)/bundles:/go/src/github.com/docker/docker/bundles \
 253     -v $HOME/.gnupg:/root/.gnupg \
 254     -e DOCKER_RELEASE_DIR=/volumes/repos \
 255     -e GPG_PASSPHRASE \
 256     -e KEEPBUNDLE=1 \
 257     docker \
 258     hack/make.sh release-deb release-rpm sign-repos generate-index-listing
 259 ```
 260
 261 ### 10. Upload the changed repos to wherever you host
 262
 263 For example, above we bind mounted `/volumes/repos` as the storage for
 264 `DOCKER_RELEASE_DIR`. In this case `/volumes/repos/apt` can be synced with
 265 a specific s3 bucket for the apt repo and `/volumes/repos/yum` can be synced with
 266 a s3 bucket for the yum repo.
 267
 268 ### 11. Publish release candidate binaries
 269
 270 To run this you will need access to the release credentials. Get them from the
 271 Core maintainers.
 272
 273 ```bash
 274 docker build -t docker .
 275
 276 # static binaries are still pushed to s3
 277 docker run \
 278     -e AWS_S3_BUCKET=test.docker.com \
 279     -e AWS_ACCESS_KEY_ID \
 280     -e AWS_SECRET_ACCESS_KEY \
 281     -e AWS_DEFAULT_REGION \
 282     -i -t --privileged \
 283     docker \
 284     hack/release.sh
 285 ```
 286
 287 It will run the test suite, build the binaries and upload to the specified bucket,
 288 so this is a good time to verify that you're running against **test**.docker.com.
 289
 290 ### 12. Purge the cache!
 291
 292 After the binaries are uploaded to test.docker.com and the packages are on
 293 apt.dockerproject.org and yum.dockerproject.org, make sure
 294 they get tested in both Ubuntu and Debian for any obvious installation
 295 issues or runtime issues.
 296
 297 If everything looks good, it's time to create a git tag for this candidate:
 298
 299 ```bash
 300 git tag -a $RC_VERSION -m $RC_VERSION bump_$VERSION
 301 git push origin $RC_VERSION
 302 ```
 303
 304 Announcing on multiple medias is the best way to get some help testing! An easy
 305 way to get some useful links for sharing:
 306
 307 ```bash
 308 echo "Ubuntu/Debian: curl -sSL https://test.docker.com/ | sh"
 309 echo "Linux 64bit binary: https://test.docker.com/builds/Linux/x86_64/docker-${VERSION#v}"
 310 echo "Darwin/OSX 64bit client binary: https://test.docker.com/builds/Darwin/x86_64/docker-${VERSION#v}"
 311 echo "Linux 64bit tgz: https://test.docker.com/builds/Linux/x86_64/docker-${VERSION#v}.tgz"
 312 echo "Windows 64bit client binary: https://test.docker.com/builds/Windows/x86_64/docker-${VERSION#v}.exe"
 313 echo "Windows 32bit client binary: https://test.docker.com/builds/Windows/i386/docker-${VERSION#v}.exe"
 314 ```
 315 ### 13. Announce the release candidate
 316
 317 The release candidate should be announced on:
 318
 319 - IRC on #docker, #docker-dev, #docker-maintainers
 320 - In a comment on the pull request to notify subscribed people on GitHub
 321 - The [docker-dev](https://groups.google.com/forum/#!forum/docker-dev) group
 322 - The [docker-maintainers](https://groups.google.com/a/dockerproject.org/forum/#!forum/maintainers) group
 323 - (Optional) Any social media that can bring some attention to the release candidate
 324
 325 ### 14. Iterate on successive release candidates
 326
 327 Spend several days along with the community explicitly investing time and
 328 resources to try and break Docker in every possible way, documenting any
 329 findings pertinent to the release.  This time should be spent testing and
 330 finding ways in which the release might have caused various features or upgrade
 331 environments to have issues, not coding.  During this time, the release is in
 332 code freeze, and any additional code changes will be pushed out to the next
 333 release.
 334
 335 It should include various levels of breaking Docker, beyond just using Docker
 336 by the book.
 337
 338 Any issues found may still remain issues for this release, but they should be
 339 documented and give appropriate warnings.
 340
 341 During this phase, the `bump_$VERSION` branch will keep evolving as you will
 342 produce new release candidates. The frequency of new candidates is up to the
 343 release manager: use your best judgement taking into account the severity of
 344 reported issues, testers availability, and time to scheduled release date.
 345
 346 Each time you'll want to produce a new release candidate, you will start by
 347 adding commits to the branch, usually by cherry-picking from master:
 348
 349 ```bash
 350 git cherry-pick -s -x -m0 <commit_id>
 351 ```
 352
 353 You want your "bump commit" (the one that updates the CHANGELOG and VERSION
 354 files) to remain on top, so you'll have to `git rebase -i` to bring it back up.
 355
 356 Now that your bump commit is back on top, you will need to update the CHANGELOG
 357 file (if appropriate for this particular release candidate), and update the
 358 VERSION file to increment the RC number:
 359
 360 ```bash
 361 export RC_VERSION=$VERSION-rcN
 362 echo $RC_VERSION > VERSION
 363 ```
 364
 365 You can now amend your last commit and update the bump branch:
 366
 367 ```bash
 368 git commit --amend
 369 git push -f $GITHUBUSER bump_$VERSION
 370 ```
 371
 372 Repeat steps 6 to 14 to tag the code, publish new binaries, announce availability, and
 373 get help testing.
 374
 375 ### 15. Finalize the bump branch
 376
 377 When you're happy with the quality of a release candidate, you can move on and
 378 create the real thing.
 379
 380 You will first have to amend the "bump commit" to drop the release candidate
 381 suffix in the VERSION file:
 382
 383 ```bash
 384 echo $VERSION > VERSION
 385 git add VERSION
 386 git commit --amend
 387 ```
 388
 389 You will then repeat step 6 to publish the binaries to test
 390
 391 ### 16. Get 2 other maintainers to validate the pull request
 392
 393 ### 17. Build final rpms and debs
 394
 395 ```bash
 396 docker build -t docker .
 397 docker run \
 398     --rm -t --privileged \
 399     -v $(pwd)/bundles:/go/src/github.com/docker/docker/bundles \
 400     docker \
 401     hack/make.sh binary build-deb build-rpm
 402 ```
 403
 404 ### 18. Publish final rpms and debs
 405
 406 With the rpms and debs you built from the last step you can release them on the
 407 same server, or ideally, move them to a dedicated release box via scp into
 408 another docker/docker directory in bundles. This next step assumes you have
 409 a checkout of the docker source code at the same commit you used to build, with
 410 the artifacts from the last step in `bundles`.
 411
 412 **NOTE:** If you put a space before the command your `.bash_history` will not
 413 save it. (for the `GPG_PASSPHRASE`).
 414
 415 ```bash
 416 docker build -t docker .
 417 docker run --rm -it --privileged \
 418     -v /volumes/repos:/volumes/repos \
 419     -v $(pwd)/bundles:/go/src/github.com/docker/docker/bundles \
 420     -v $HOME/.gnupg:/root/.gnupg \
 421     -e DOCKER_RELEASE_DIR=/volumes/repos \
 422     -e GPG_PASSPHRASE \
 423     -e KEEPBUNDLE=1 \
 424     docker \
 425     hack/make.sh release-deb release-rpm sign-repos generate-index-listing
 426 ```
 427
 428 ### 19. Upload the changed repos to wherever you host
 429
 430 For example, above we bind mounted `/volumes/repos` as the storage for
 431 `DOCKER_RELEASE_DIR`. In this case `/volumes/repos/apt` can be synced with
 432 a specific s3 bucket for the apt repo and `/volumes/repos/yum` can be synced with
 433 a s3 bucket for the yum repo.
 434
 435 ### 20. Publish final binaries
 436
 437 Once they're tested and reasonably believed to be working, run against
 438 get.docker.com:
 439
 440 ```bash
 441 docker build -t docker .
 442 # static binaries are still pushed to s3
 443 docker run \
 444     -e AWS_S3_BUCKET=get.docker.com \
 445     -e AWS_ACCESS_KEY_ID \
 446     -e AWS_SECRET_ACCESS_KEY \
 447     -e AWS_DEFAULT_REGION \
 448     -i -t --privileged \
 449     docker \
 450     hack/release.sh
 451 ```
 452
 453 ### 21. Purge the cache!
 454
 455 ### 22. Apply tag and create release
 456
 457 It's very important that we don't make the tag until after the official
 458 release is uploaded to get.docker.com!
 459
 460 ```bash
 461 git tag -a $VERSION -m $VERSION bump_$VERSION
 462 git push origin $VERSION
 463 ```
 464
 465 Once the tag is pushed, go to GitHub and create a [new release](https://github.com/docker/docker/releases/new).
 466 If the tag is for an RC make sure you check `This is a pre-release` at the bottom of the form.
 467
 468 Select the tag that you just pushed as the version and paste the changelog in the description of the release.
 469 You can see examples in this two links:
 470
 471 https://github.com/docker/docker/releases/tag/v1.8.0
 472 https://github.com/docker/docker/releases/tag/v1.8.0-rc3
 473
 474 ### 23. Go to github to merge the `bump_$VERSION` branch into release
 475
 476 Don't forget to push that pretty blue button to delete the leftover
 477 branch afterwards!
 478
 479 ### 24. Update the docs branch
 480
 481 You will need to point the docs branch to the newly created release tag:
 482
 483 ```bash
 484 git checkout origin/docs
 485 git reset --hard origin/$VERSION
 486 git push -f origin docs
 487 ```
 488
 489 The docs will appear on https://docs.docker.com/ (though there may be cached
 490 versions, so its worth checking http://docs.docker.com.s3-website-us-east-1.amazonaws.com/).
 491 For more information about documentation releases, see `docs/README.md`.
 492
 493 Note that the new docs will not appear live on the site until the cache (a complex,
 494 distributed CDN system) is flushed. The `make docs-release` command will do this
 495 _if_ the `DISTRIBUTION_ID` is set correctly - this will take at least 15 minutes to run
 496 and you can check its progress with the CDN Cloudfront Chrome addon.
 497
 498 ### 25. Create a new pull request to merge your bump commit back into master
 499
 500 ```bash
 501 git checkout master
 502 git fetch
 503 git reset --hard origin/master
 504 git cherry-pick -s -x $VERSION
 505 git push $GITHUBUSER merge_release_$VERSION
 506 echo "https://github.com/$GITHUBUSER/docker/compare/docker:master...$GITHUBUSER:merge_release_$VERSION?expand=1"
 507 ```
 508
 509 Again, get two maintainers to validate, then merge, then push that pretty
 510 blue button to delete your branch.
 511
 512 ### 26. Rejoice and Evangelize!
 513
 514 Congratulations! You're done.
 515
 516 Go forth and announce the glad tidings of the new release in `#docker`,
 517 `#docker-dev`, on the [dev mailing list](https://groups.google.com/forum/#!forum/docker-dev),
 518 the [announce mailing list](https://groups.google.com/forum/#!forum/docker-announce),
 519 and on Twitter!