github.com/lazyboychen7/engine@v17.12.1-ce-rc2+incompatible/project/RELEASE-CHECKLIST.md (about) 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!