2014-01-04 04:52:18 +04:00
|
|
|
# Release Checklist
|
2013-08-17 03:05:16 +04:00
|
|
|
## A maintainer's guide to releasing Docker
|
|
|
|
|
|
|
|
So you're in charge of a Docker release? Cool. Here's what to do.
|
|
|
|
|
|
|
|
If your experience deviates from this document, please document the changes
|
|
|
|
to keep it up-to-date.
|
|
|
|
|
2014-03-07 10:26:18 +04:00
|
|
|
It is important to note that this document assumes that the git remote in your
|
2014-07-25 02:19:50 +04:00
|
|
|
repository that corresponds to "https://github.com/docker/docker" is named
|
2014-03-07 10:26:18 +04:00
|
|
|
"origin". If yours is not (for example, if you've chosen to name it "upstream"
|
|
|
|
or something similar instead), be sure to adjust the listed snippets for your
|
|
|
|
local environment accordingly. If you are not sure what your upstream remote is
|
|
|
|
named, use a command like `git remote -v` to find out.
|
|
|
|
|
|
|
|
If you don't have an upstream remote, you can add one easily using something
|
|
|
|
like:
|
|
|
|
|
|
|
|
```bash
|
2014-06-07 01:12:39 +04:00
|
|
|
export GITHUBUSER="YOUR_GITHUB_USER"
|
2014-07-25 02:19:50 +04:00
|
|
|
git remote add origin https://github.com/docker/docker.git
|
2014-06-07 01:12:39 +04:00
|
|
|
git remote add $GITHUBUSER git@github.com:$GITHUBUSER/docker.git
|
2014-03-07 10:26:18 +04:00
|
|
|
```
|
|
|
|
|
2013-08-17 03:05:16 +04:00
|
|
|
### 1. Pull from master and create a release branch
|
|
|
|
|
2014-06-07 01:12:39 +04:00
|
|
|
Note: Even for major releases, all of X, Y and Z in vX.Y.Z must be specified (e.g. v1.0.0).
|
|
|
|
|
2013-08-17 03:05:16 +04:00
|
|
|
```bash
|
2014-01-04 04:52:18 +04:00
|
|
|
export VERSION=vX.Y.Z
|
2014-06-07 01:12:39 +04:00
|
|
|
git fetch origin
|
|
|
|
git branch -D release || true
|
|
|
|
git checkout --track origin/release
|
2013-08-17 03:05:16 +04:00
|
|
|
git checkout -b bump_$VERSION
|
2014-07-09 03:09:22 +04:00
|
|
|
```
|
|
|
|
|
2014-07-09 05:53:08 +04:00
|
|
|
If it's a regular release, we usually merge master.
|
2014-07-09 03:09:22 +04:00
|
|
|
```bash
|
2013-11-22 22:39:40 +04:00
|
|
|
git merge origin/master
|
2013-08-17 03:05:16 +04:00
|
|
|
```
|
2014-07-09 05:53:08 +04:00
|
|
|
|
|
|
|
Otherwise, if it is a hotfix release, we cherry-pick only the commits we want.
|
2014-07-09 03:09:22 +04:00
|
|
|
```bash
|
2014-07-09 05:53:08 +04:00
|
|
|
# get the commits ids we want to cherry-pick
|
2014-07-09 03:09:22 +04:00
|
|
|
git log
|
2014-07-09 05:53:08 +04:00
|
|
|
# cherry-pick the commits starting from the oldest one, without including merge commits
|
2014-07-09 03:09:22 +04:00
|
|
|
git cherry-pick <commit-id>
|
|
|
|
git cherry-pick <commit-id>
|
|
|
|
...
|
|
|
|
```
|
2013-08-17 03:05:16 +04:00
|
|
|
|
|
|
|
### 2. Update CHANGELOG.md
|
|
|
|
|
2014-06-07 01:12:39 +04:00
|
|
|
You can run this command for reference with git 2.0:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
git fetch --tags
|
|
|
|
LAST_VERSION=$(git tag -l --sort=-version:refname "v*" | grep -E 'v[0-9\.]+$' | head -1)
|
|
|
|
git log --stat $LAST_VERSION..bump_$VERSION
|
|
|
|
```
|
2013-08-17 03:05:16 +04:00
|
|
|
|
2014-06-07 01:12:39 +04:00
|
|
|
If you don't have git 2.0 but have a sort command that supports `-V`:
|
2013-08-17 03:05:16 +04:00
|
|
|
```bash
|
2014-06-07 01:12:39 +04:00
|
|
|
git fetch --tags
|
|
|
|
LAST_VERSION=$(git tag -l | grep -E 'v[0-9\.]+$' | sort -rV | head -1)
|
|
|
|
git log --stat $LAST_VERSION..bump_$VERSION
|
2013-08-17 03:05:16 +04:00
|
|
|
```
|
|
|
|
|
2014-06-07 01:12:39 +04:00
|
|
|
If releasing a major version (X or Y increased in vX.Y.Z), simply listing notable user-facing features is sufficient.
|
|
|
|
```markdown
|
|
|
|
#### Notable features since <last major version>
|
|
|
|
* New docker command to do something useful
|
|
|
|
* Remote API change (deprecating old version)
|
|
|
|
* Performance improvements in some usecases
|
|
|
|
* ...
|
|
|
|
```
|
|
|
|
|
|
|
|
For minor releases (only Z increases in vX.Y.Z), provide a list of user-facing changes.
|
2014-01-04 04:52:18 +04:00
|
|
|
Each change should be listed under a category heading formatted as `#### CATEGORY`.
|
2013-08-17 03:05:16 +04:00
|
|
|
|
2014-01-04 04:52:18 +04:00
|
|
|
`CATEGORY` should describe which part of the project is affected.
|
2013-08-17 03:05:16 +04:00
|
|
|
Valid categories are:
|
|
|
|
* Builder
|
|
|
|
* Documentation
|
|
|
|
* Hack
|
|
|
|
* Packaging
|
|
|
|
* Remote API
|
|
|
|
* Runtime
|
2014-01-04 04:52:18 +04:00
|
|
|
* Other (please use this category sparingly)
|
|
|
|
|
|
|
|
Each change should be formatted as `BULLET DESCRIPTION`, given:
|
2013-08-17 03:05:16 +04:00
|
|
|
|
2014-01-04 04:52:18 +04:00
|
|
|
* BULLET: either `-`, `+` or `*`, to indicate a bugfix, new feature or
|
|
|
|
upgrade, respectively.
|
|
|
|
|
|
|
|
* DESCRIPTION: a concise description of the change that is relevant to the
|
|
|
|
end-user, using the present tense. Changes should be described in terms
|
|
|
|
of how they affect the user, for example "Add new feature X which allows Y",
|
|
|
|
"Fix bug which caused X", "Increase performance of Y".
|
2013-08-17 03:05:16 +04:00
|
|
|
|
|
|
|
EXAMPLES:
|
|
|
|
|
2014-01-04 04:52:18 +04:00
|
|
|
```markdown
|
|
|
|
## 0.3.6 (1995-12-25)
|
|
|
|
|
|
|
|
#### Builder
|
|
|
|
|
2014-05-08 17:11:17 +04:00
|
|
|
+ 'docker build -t FOO .' applies the tag FOO to the newly built image
|
2014-01-04 04:52:18 +04:00
|
|
|
|
|
|
|
#### Remote API
|
|
|
|
|
|
|
|
- Fix a bug in the optional unix socket transport
|
|
|
|
|
|
|
|
#### Runtime
|
|
|
|
|
|
|
|
* Improve detection of kernel version
|
2013-08-17 03:05:16 +04:00
|
|
|
```
|
|
|
|
|
2014-02-05 00:32:53 +04:00
|
|
|
If you need a list of contributors between the last major release and the
|
|
|
|
current bump branch, use something like:
|
|
|
|
```bash
|
|
|
|
git log --format='%aN <%aE>' v0.7.0...bump_v0.8.0 | sort -uf
|
|
|
|
```
|
|
|
|
Obviously, you'll need to adjust version numbers as necessary. If you just need
|
|
|
|
a count, add a simple `| wc -l`.
|
|
|
|
|
2013-08-17 03:05:16 +04:00
|
|
|
### 3. Change the contents of the VERSION file
|
|
|
|
|
2013-11-22 22:39:40 +04:00
|
|
|
```bash
|
|
|
|
echo ${VERSION#v} > VERSION
|
|
|
|
```
|
|
|
|
|
2014-06-07 01:12:39 +04:00
|
|
|
### 4. Test the docs
|
2013-10-16 02:52:21 +04:00
|
|
|
|
|
|
|
Make sure that your tree includes documentation for any modified or
|
2014-05-20 09:54:10 +04:00
|
|
|
new features, syntax or semantic changes.
|
|
|
|
|
|
|
|
To test locally:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
make docs
|
|
|
|
```
|
|
|
|
|
|
|
|
To make a shared test at http://beta-docs.docker.io:
|
|
|
|
|
|
|
|
(You will need the `awsconfig` file added to the `docs/` dir)
|
|
|
|
|
|
|
|
```bash
|
2014-07-22 13:05:18 +04:00
|
|
|
make AWS_S3_BUCKET=beta-docs.docker.io BUILD_ROOT=yes docs-release
|
2014-05-20 09:54:10 +04:00
|
|
|
```
|
2013-10-16 02:52:21 +04:00
|
|
|
|
2014-06-07 01:12:39 +04:00
|
|
|
### 5. Commit and create a pull request to the "release" branch
|
2013-08-17 03:05:16 +04:00
|
|
|
|
|
|
|
```bash
|
2013-10-30 02:28:12 +04:00
|
|
|
git add VERSION CHANGELOG.md
|
2013-08-17 03:05:16 +04:00
|
|
|
git commit -m "Bump version to $VERSION"
|
2014-06-07 01:12:39 +04:00
|
|
|
git push $GITHUBUSER bump_$VERSION
|
2014-07-25 02:19:50 +04:00
|
|
|
echo "https://github.com/$GITHUBUSER/docker/compare/docker:release...$GITHUBUSER:bump_$VERSION?expand=1"
|
2013-08-17 03:05:16 +04:00
|
|
|
```
|
|
|
|
|
2014-01-04 04:52:18 +04:00
|
|
|
That last command will give you the proper link to visit to ensure that you
|
|
|
|
open the PR against the "release" branch instead of accidentally against
|
|
|
|
"master" (like so many brave souls before you already have).
|
|
|
|
|
2014-06-07 01:12:39 +04:00
|
|
|
### 6. Get 2 other maintainers to validate the pull request
|
2013-08-17 03:05:16 +04:00
|
|
|
|
2014-06-07 01:12:39 +04:00
|
|
|
### 7. Publish binaries
|
2014-01-04 04:52:18 +04:00
|
|
|
|
2014-06-07 01:12:39 +04:00
|
|
|
To run this you will need access to the release credentials. Get them from the Core maintainers.
|
|
|
|
|
|
|
|
Replace "..." with the respective credentials:
|
2014-01-04 04:52:18 +04:00
|
|
|
|
|
|
|
```bash
|
|
|
|
docker build -t docker .
|
|
|
|
docker run \
|
2014-09-24 03:18:09 +04:00
|
|
|
-e AWS_S3_BUCKET=test.docker.com \
|
2014-06-07 01:12:39 +04:00
|
|
|
-e AWS_ACCESS_KEY="..." \
|
|
|
|
-e AWS_SECRET_KEY="..." \
|
|
|
|
-e GPG_PASSPHRASE="..." \
|
2014-03-13 21:46:02 +04:00
|
|
|
-i -t --privileged \
|
2014-01-04 04:52:18 +04:00
|
|
|
docker \
|
|
|
|
hack/release.sh
|
|
|
|
```
|
|
|
|
|
2014-06-07 01:12:39 +04:00
|
|
|
It will run the test suite, build the binaries and packages,
|
2014-09-24 03:18:09 +04:00
|
|
|
and upload to the specified bucket (you should use test.docker.com for
|
|
|
|
general testing, and once everything is fine, switch to get.docker.com as
|
2014-01-04 04:52:18 +04:00
|
|
|
noted below).
|
|
|
|
|
2014-09-24 03:18:09 +04:00
|
|
|
After the binaries and packages are uploaded to test.docker.com, make sure
|
2014-01-04 04:52:18 +04:00
|
|
|
they get tested in both Ubuntu and Debian for any obvious installation
|
|
|
|
issues or runtime issues.
|
|
|
|
|
|
|
|
Announcing on IRC in both `#docker` and `#docker-dev` is a great way to get
|
|
|
|
help testing! An easy way to get some useful links for sharing:
|
|
|
|
|
|
|
|
```bash
|
2014-09-24 03:18:09 +04:00
|
|
|
echo "Ubuntu/Debian: https://test.docker.com/ubuntu or curl -sSL https://test.docker.com/ | sh"
|
|
|
|
echo "Linux 64bit binary: https://test.docker.com/builds/Linux/x86_64/docker-${VERSION#v}"
|
|
|
|
echo "Darwin/OSX 64bit client binary: https://test.docker.com/builds/Darwin/x86_64/docker-${VERSION#v}"
|
|
|
|
echo "Darwin/OSX 32bit client binary: https://test.docker.com/builds/Darwin/i386/docker-${VERSION#v}"
|
|
|
|
echo "Linux 64bit tgz: https://test.docker.com/builds/Linux/x86_64/docker-${VERSION#v}.tgz"
|
2014-01-04 04:52:18 +04:00
|
|
|
```
|
|
|
|
|
|
|
|
Once they're tested and reasonably believed to be working, run against
|
2014-09-24 03:18:09 +04:00
|
|
|
get.docker.com:
|
2014-01-04 04:52:18 +04:00
|
|
|
|
|
|
|
```bash
|
|
|
|
docker run \
|
2014-09-24 03:18:09 +04:00
|
|
|
-e AWS_S3_BUCKET=get.docker.com \
|
2014-06-07 01:12:39 +04:00
|
|
|
-e AWS_ACCESS_KEY="..." \
|
|
|
|
-e AWS_SECRET_KEY="..." \
|
|
|
|
-e GPG_PASSPHRASE="..." \
|
2014-03-13 21:46:02 +04:00
|
|
|
-i -t --privileged \
|
2014-01-04 04:52:18 +04:00
|
|
|
docker \
|
|
|
|
hack/release.sh
|
|
|
|
```
|
|
|
|
|
2014-06-07 01:12:39 +04:00
|
|
|
### 8. Breakathon
|
2014-03-13 22:15:52 +04:00
|
|
|
|
|
|
|
Spend several days along with the community explicitly investing time and
|
|
|
|
resources to try and break Docker in every possible way, documenting any
|
|
|
|
findings pertinent to the release. This time should be spent testing and
|
|
|
|
finding ways in which the release might have caused various features or upgrade
|
|
|
|
environments to have issues, not coding. During this time, the release is in
|
|
|
|
code freeze, and any additional code changes will be pushed out to the next
|
|
|
|
release.
|
|
|
|
|
|
|
|
It should include various levels of breaking Docker, beyond just using Docker
|
|
|
|
by the book.
|
|
|
|
|
|
|
|
Any issues found may still remain issues for this release, but they should be
|
|
|
|
documented and give appropriate warnings.
|
|
|
|
|
2014-06-07 01:12:39 +04:00
|
|
|
### 9. Apply tag
|
|
|
|
|
|
|
|
It's very important that we don't make the tag until after the official
|
2014-09-24 03:18:09 +04:00
|
|
|
release is uploaded to get.docker.com!
|
2013-08-17 03:05:16 +04:00
|
|
|
|
|
|
|
```bash
|
2013-11-22 22:39:40 +04:00
|
|
|
git tag -a $VERSION -m $VERSION bump_$VERSION
|
|
|
|
git push origin $VERSION
|
2013-08-17 03:05:16 +04:00
|
|
|
```
|
|
|
|
|
2014-06-07 01:12:39 +04:00
|
|
|
### 10. Go to github to merge the `bump_$VERSION` branch into release
|
2014-01-04 04:52:18 +04:00
|
|
|
|
2014-03-07 10:16:26 +04:00
|
|
|
Don't forget to push that pretty blue button to delete the leftover
|
|
|
|
branch afterwards!
|
2014-02-13 23:42:14 +04:00
|
|
|
|
2014-06-07 01:12:39 +04:00
|
|
|
### 11. Update the docs branch
|
2014-02-13 23:42:14 +04:00
|
|
|
|
2014-07-22 12:04:48 +04:00
|
|
|
If this is a MAJOR.MINOR.0 release, you need to make an branch for the previous release's
|
|
|
|
documentation:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
git checkout -b docs-$PREVIOUS_MAJOR_MINOR docs
|
|
|
|
git fetch
|
|
|
|
git reset --hard origin/docs
|
|
|
|
git push -f origin docs-$PREVIOUS_MAJOR_MINOR
|
|
|
|
```
|
|
|
|
|
2014-05-20 09:54:10 +04:00
|
|
|
You will need the `awsconfig` file added to the `docs/` directory to contain the
|
|
|
|
s3 credentials for the bucket you are deploying to.
|
|
|
|
|
2014-03-07 10:16:26 +04:00
|
|
|
```bash
|
2014-06-07 01:12:39 +04:00
|
|
|
git checkout -b docs release || git checkout docs
|
2014-03-07 10:16:26 +04:00
|
|
|
git fetch
|
|
|
|
git reset --hard origin/release
|
|
|
|
git push -f origin docs
|
2014-07-22 13:05:18 +04:00
|
|
|
make AWS_S3_BUCKET=docs.docker.com BUILD_ROOT=yes docs-release
|
2014-03-07 10:16:26 +04:00
|
|
|
```
|
2013-10-30 02:28:12 +04:00
|
|
|
|
2014-07-22 12:04:48 +04:00
|
|
|
The docs will appear on http://docs.docker.com/ (though there may be cached
|
|
|
|
versions, so its worth checking http://docs.docker.com.s3-website-us-east-1.amazonaws.com/).
|
2014-05-20 09:54:10 +04:00
|
|
|
For more information about documentation releases, see `docs/README.md`.
|
2013-11-22 22:39:40 +04:00
|
|
|
|
2014-07-22 12:04:48 +04:00
|
|
|
Ask Sven, or JohnC to invalidate the cloudfront cache using the CND Planet chrome applet.
|
|
|
|
|
2014-06-07 01:12:39 +04:00
|
|
|
### 12. Create a new pull request to merge release back into master
|
2013-08-17 03:05:16 +04:00
|
|
|
|
|
|
|
```bash
|
2014-01-04 04:52:18 +04:00
|
|
|
git checkout master
|
2013-10-30 02:28:12 +04:00
|
|
|
git fetch
|
2014-01-04 04:52:18 +04:00
|
|
|
git reset --hard origin/master
|
|
|
|
git merge origin/release
|
|
|
|
git checkout -b merge_release_$VERSION
|
|
|
|
echo ${VERSION#v}-dev > VERSION
|
|
|
|
git add VERSION
|
|
|
|
git commit -m "Change version to $(cat VERSION)"
|
2014-06-07 01:12:39 +04:00
|
|
|
git push $GITHUBUSER merge_release_$VERSION
|
2014-07-25 02:19:50 +04:00
|
|
|
echo "https://github.com/$GITHUBUSER/docker/compare/docker:master...$GITHUBUSER:merge_release_$VERSION?expand=1"
|
2013-08-17 03:05:16 +04:00
|
|
|
```
|
|
|
|
|
2014-01-04 04:52:18 +04:00
|
|
|
Again, get two maintainers to validate, then merge, then push that pretty
|
|
|
|
blue button to delete your branch.
|
2013-08-17 03:05:16 +04:00
|
|
|
|
2014-06-07 01:12:39 +04:00
|
|
|
### 13. Rejoice and Evangelize!
|
2013-08-17 03:05:16 +04:00
|
|
|
|
|
|
|
Congratulations! You're done.
|
2013-11-22 22:39:40 +04:00
|
|
|
|
|
|
|
Go forth and announce the glad tidings of the new release in `#docker`,
|
|
|
|
`#docker-dev`, on the [mailing list](https://groups.google.com/forum/#!forum/docker-dev),
|
|
|
|
and on Twitter!
|