Update release checklist with more information, more commands, and more correct flow (test, upload to test.docker.io, test, upload to get.docker.io, THEN tag&merge)
Docker-DCO-1.0-Signed-off-by: Andrew Page <admwiggin@gmail.com> (github: tianon)
This commit is contained in:
parent
bb76985d39
commit
b57051a724
|
@ -1,3 +1,4 @@
|
||||||
|
# Release Checklist
|
||||||
## A maintainer's guide to releasing Docker
|
## A maintainer's guide to releasing Docker
|
||||||
|
|
||||||
So you're in charge of a Docker release? Cool. Here's what to do.
|
So you're in charge of a Docker release? Cool. Here's what to do.
|
||||||
|
@ -8,9 +9,10 @@ to keep it up-to-date.
|
||||||
### 1. Pull from master and create a release branch
|
### 1. Pull from master and create a release branch
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
export VERSION=vXXX
|
export VERSION=vX.Y.Z
|
||||||
git checkout release
|
git checkout release
|
||||||
git pull
|
git fetch
|
||||||
|
git reset --hard origin/release
|
||||||
git checkout -b bump_$VERSION
|
git checkout -b bump_$VERSION
|
||||||
git merge origin/master
|
git merge origin/master
|
||||||
```
|
```
|
||||||
|
@ -20,16 +22,13 @@ git merge origin/master
|
||||||
You can run this command for reference:
|
You can run this command for reference:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
LAST_VERSION=$(git tag | grep -E "v[0-9\.]+$" | sort -nr | head -n 1)
|
LAST_VERSION=$(git tag | grep -E 'v[0-9\.]+$' | sort -nr | head -n 1)
|
||||||
git log $LAST_VERSION..HEAD
|
git log --stat $LAST_VERSION..HEAD
|
||||||
```
|
```
|
||||||
|
|
||||||
Each change should be formatted as ```BULLET CATEGORY: DESCRIPTION```
|
Each change should be listed under a category heading formatted as `#### CATEGORY`.
|
||||||
|
|
||||||
* BULLET is either ```-```, ```+``` or ```*```, to indicate a bugfix,
|
`CATEGORY` should describe which part of the project is affected.
|
||||||
new feature or upgrade, respectively.
|
|
||||||
|
|
||||||
* CATEGORY should describe which part of the project is affected.
|
|
||||||
Valid categories are:
|
Valid categories are:
|
||||||
* Builder
|
* Builder
|
||||||
* Documentation
|
* Documentation
|
||||||
|
@ -37,19 +36,34 @@ Each change should be formatted as ```BULLET CATEGORY: DESCRIPTION```
|
||||||
* Packaging
|
* Packaging
|
||||||
* Remote API
|
* Remote API
|
||||||
* Runtime
|
* Runtime
|
||||||
|
* Other (please use this category sparingly)
|
||||||
|
|
||||||
|
Each change should be formatted as `BULLET DESCRIPTION`, given:
|
||||||
|
|
||||||
|
* BULLET: either `-`, `+` or `*`, to indicate a bugfix, new feature or
|
||||||
|
upgrade, respectively.
|
||||||
|
|
||||||
* DESCRIPTION: a concise description of the change that is relevant to the
|
* DESCRIPTION: a concise description of the change that is relevant to the
|
||||||
end-user, using the present tense. Changes should be described in terms
|
end-user, using the present tense. Changes should be described in terms
|
||||||
of how they affect the user, for example "new feature X which allows Y",
|
of how they affect the user, for example "Add new feature X which allows Y",
|
||||||
"fixed bug which caused X", "increased performance of Y".
|
"Fix bug which caused X", "Increase performance of Y".
|
||||||
|
|
||||||
EXAMPLES:
|
EXAMPLES:
|
||||||
|
|
||||||
```
|
```markdown
|
||||||
+ Builder: 'docker build -t FOO' applies the tag FOO to the newly built
|
## 0.3.6 (1995-12-25)
|
||||||
container.
|
|
||||||
* Runtime: improve detection of kernel version
|
#### Builder
|
||||||
- Remote API: fix a bug in the optional unix socket transport
|
|
||||||
|
+ 'docker build -t FOO .' applies the tag FOO to the newly built container
|
||||||
|
|
||||||
|
#### Remote API
|
||||||
|
|
||||||
|
- Fix a bug in the optional unix socket transport
|
||||||
|
|
||||||
|
#### Runtime
|
||||||
|
|
||||||
|
* Improve detection of kernel version
|
||||||
```
|
```
|
||||||
|
|
||||||
### 3. Change the contents of the VERSION file
|
### 3. Change the contents of the VERSION file
|
||||||
|
@ -61,14 +75,14 @@ echo ${VERSION#v} > VERSION
|
||||||
### 4. Run all tests
|
### 4. Run all tests
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
docker run -privileged docker hack/make.sh test
|
make test
|
||||||
```
|
```
|
||||||
|
|
||||||
### 5. Test the docs
|
### 5. Test the docs
|
||||||
|
|
||||||
Make sure that your tree includes documentation for any modified or
|
Make sure that your tree includes documentation for any modified or
|
||||||
new features, syntax or semantic changes. Instructions for building
|
new features, syntax or semantic changes. Instructions for building
|
||||||
the docs are in ``docs/README.md``
|
the docs are in `docs/README.md`.
|
||||||
|
|
||||||
### 6. Commit and create a pull request to the "release" branch
|
### 6. Commit and create a pull request to the "release" branch
|
||||||
|
|
||||||
|
@ -76,44 +90,32 @@ the docs are in ``docs/README.md``
|
||||||
git add VERSION CHANGELOG.md
|
git add VERSION CHANGELOG.md
|
||||||
git commit -m "Bump version to $VERSION"
|
git commit -m "Bump version to $VERSION"
|
||||||
git push origin bump_$VERSION
|
git push origin bump_$VERSION
|
||||||
|
echo "https://github.com/dotcloud/docker/compare/release...bump_$VERSION"
|
||||||
```
|
```
|
||||||
|
|
||||||
|
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).
|
||||||
|
|
||||||
### 7. Get 2 other maintainers to validate the pull request
|
### 7. Get 2 other maintainers to validate the pull request
|
||||||
|
|
||||||
### 8. Apply tag
|
### 8. Publish binaries
|
||||||
|
|
||||||
```bash
|
|
||||||
git tag -a $VERSION -m $VERSION bump_$VERSION
|
|
||||||
git push origin $VERSION
|
|
||||||
```
|
|
||||||
|
|
||||||
Merging the pull request to the release branch will automatically
|
|
||||||
update the documentation on the "latest" revision of the docs. You
|
|
||||||
should see the updated docs 5-10 minutes after the merge. The docs
|
|
||||||
will appear on http://docs.docker.io/. For more information about
|
|
||||||
documentation releases, see ``docs/README.md``
|
|
||||||
|
|
||||||
### 9. Go to github to merge the bump_$VERSION into release
|
|
||||||
|
|
||||||
Don't forget to push that pretty blue button to delete the leftover
|
|
||||||
branch afterwards!
|
|
||||||
|
|
||||||
### 10. Publish binaries
|
|
||||||
|
|
||||||
To run this you will need access to the release credentials.
|
To run this you will need access to the release credentials.
|
||||||
Get them from [the infrastructure maintainers](
|
Get them from [the infrastructure maintainers](
|
||||||
https://github.com/dotcloud/docker/blob/master/hack/infrastructure/MAINTAINERS).
|
https://github.com/dotcloud/docker/blob/master/hack/infrastructure/MAINTAINERS).
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git checkout release
|
|
||||||
git fetch
|
|
||||||
git reset --hard origin/release
|
|
||||||
docker build -t docker .
|
docker build -t docker .
|
||||||
|
export AWS_S3_BUCKET="test.docker.io"
|
||||||
|
export AWS_ACCESS_KEY="$(cat ~/.aws/access_key)"
|
||||||
|
export AWS_SECRET_KEY="$(cat ~/.aws/secret_key)"
|
||||||
|
export GPG_PASSPHRASE=supersecretsesame
|
||||||
docker run \
|
docker run \
|
||||||
-e AWS_S3_BUCKET=test.docker.io \
|
-e AWS_S3_BUCKET=test.docker.io \
|
||||||
-e AWS_ACCESS_KEY=$(cat ~/.aws/access_key) \
|
-e AWS_ACCESS_KEY \
|
||||||
-e AWS_SECRET_KEY=$(cat ~/.aws/secret_key) \
|
-e AWS_SECRET_KEY \
|
||||||
-e GPG_PASSPHRASE=supersecretsesame \
|
-e GPG_PASSPHRASE \
|
||||||
-i -t -privileged \
|
-i -t -privileged \
|
||||||
docker \
|
docker \
|
||||||
hack/release.sh
|
hack/release.sh
|
||||||
|
@ -121,9 +123,78 @@ docker run \
|
||||||
|
|
||||||
It will run the test suite one more time, build the binaries and packages,
|
It will run the test suite one more time, build the binaries and packages,
|
||||||
and upload to the specified bucket (you should use test.docker.io for
|
and upload to the specified bucket (you should use test.docker.io for
|
||||||
general testing, and once everything is fine, switch to get.docker.io).
|
general testing, and once everything is fine, switch to get.docker.io as
|
||||||
|
noted below).
|
||||||
|
|
||||||
### 11. Rejoice and Evangelize!
|
After the binaries and packages are uploaded to test.docker.io, make sure
|
||||||
|
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
|
||||||
|
echo "Ubuntu/Debian install script: curl -sLS https://test.docker.io/ | sh"
|
||||||
|
echo "Linux 64bit binary: https://test.docker.io/builds/Linux/x86_64/docker-${VERSION#v}"
|
||||||
|
echo "Darwin/OSX 64bit client binary: https://test.docker.io/builds/Darwin/x86_64/docker-${VERSION#v}"
|
||||||
|
echo "Darwin/OSX 32bit client binary: https://test.docker.io/builds/Darwin/i386/docker-${VERSION#v}"
|
||||||
|
echo "Linux 64bit tgz: https://test.docker.io/builds/Linux/x86_64/docker-${VERSION#v}.tgz"
|
||||||
|
```
|
||||||
|
|
||||||
|
Once they're tested and reasonably believed to be working, run against
|
||||||
|
get.docker.io:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run \
|
||||||
|
-e AWS_S3_BUCKET=get.docker.io \
|
||||||
|
-e AWS_ACCESS_KEY \
|
||||||
|
-e AWS_SECRET_KEY \
|
||||||
|
-e GPG_PASSPHRASE \
|
||||||
|
-i -t -privileged \
|
||||||
|
docker \
|
||||||
|
hack/release.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Apply tag
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git tag -a $VERSION -m $VERSION bump_$VERSION
|
||||||
|
git push origin $VERSION
|
||||||
|
```
|
||||||
|
|
||||||
|
It's very important that we don't make the tag until after the official
|
||||||
|
release is uploaded to get.docker.io!
|
||||||
|
|
||||||
|
### 10. Go to github to merge the `bump_$VERSION` into release
|
||||||
|
|
||||||
|
Merging the pull request to the release branch will automatically
|
||||||
|
update the documentation on the "latest" revision of the docs. You
|
||||||
|
should see the updated docs 5-10 minutes after the merge. The docs
|
||||||
|
will appear on http://docs.docker.io/. For more information about
|
||||||
|
documentation releases, see `docs/README.md`.
|
||||||
|
|
||||||
|
Don't forget to push that pretty blue button to delete the leftover
|
||||||
|
branch afterwards!
|
||||||
|
|
||||||
|
### 11. Create a new pull request to merge release back into master
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git checkout master
|
||||||
|
git fetch
|
||||||
|
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)"
|
||||||
|
git push origin merge_release_$VERSION
|
||||||
|
echo "https://github.com/dotcloud/docker/compare/master...merge_release_$VERSION"
|
||||||
|
```
|
||||||
|
|
||||||
|
Again, get two maintainers to validate, then merge, then push that pretty
|
||||||
|
blue button to delete your branch.
|
||||||
|
|
||||||
|
### 12. Rejoice and Evangelize!
|
||||||
|
|
||||||
Congratulations! You're done.
|
Congratulations! You're done.
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue