@@ -17,30 +17,51 @@ If you don't have an upstream remote, you can add one easily using something

 like:

 ```bash

+export GITHUBUSER="YOUR_GITHUB_USER"

 git remote add origin https://github.com/dotcloud/docker.git

-git remote add YOURUSER git@github.com:YOURUSER/docker.git

+git remote add $GITHUBUSER git@github.com:$GITHUBUSER/docker.git

 ```

 ### 1. Pull from master and create a release branch

+Note: Even for major releases, all of X, Y and Z in vX.Y.Z must be specified (e.g. v1.0.0).

+

 ```bash

 export VERSION=vX.Y.Z

-git checkout release

-git fetch

-git reset --hard origin/release

+git fetch origin

+git branch -D release || true

+git checkout --track origin/release

 git checkout -b bump_$VERSION

 git merge origin/master

 ```

 ### 2. Update CHANGELOG.md

-You can run this command for reference:

+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

+```

+If you don't have git 2.0 but have a sort command that supports `-V`:

 ```bash

-LAST_VERSION=$(git tag | grep -E 'v[0-9\.]+$' | sort -nr | head -n 1)

-git log --stat $LAST_VERSION..HEAD

+git fetch --tags

+LAST_VERSION=$(git tag -l | grep -E 'v[0-9\.]+$' | sort -rV | head -1)

+git log --stat $LAST_VERSION..bump_$VERSION

 ```

+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.

 Each change should be listed under a category heading formatted as `#### CATEGORY`.

 `CATEGORY` should describe which part of the project is affected.

@@ -95,13 +116,7 @@ a count, add a simple `| wc -l`.

 echo ${VERSION#v} > VERSION

 ```

-### 4. Run all tests

-

-```bash

-make test

-```

-

-### 5. Test the docs

+### 4. Test the docs

 Make sure that your tree includes documentation for any modified or

 new features, syntax or semantic changes.

@@ -120,44 +135,41 @@ To make a shared test at http://beta-docs.docker.io:

 make AWS_S3_BUCKET=beta-docs.docker.io docs-release

 ```

-### 6. Commit and create a pull request to the "release" branch

+### 5. Commit and create a pull request to the "release" branch

 ```bash

+export GITHUBUSER="YOUR_GITHUB_USER"

 git add VERSION CHANGELOG.md

 git commit -m "Bump version to $VERSION"

-git push origin bump_$VERSION

-echo "https://github.com/dotcloud/docker/compare/release...bump_$VERSION"

+git push $GITHUBUSER bump_$VERSION

+echo "https://github.com/$GITHUBUSER/docker/compare/dotcloud:master...$GITHUBUSER:bump_$VERSION?expand=1"

 ```

 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

+### 6. Get 2 other maintainers to validate the pull request

-### 8. Publish binaries

+### 7. Publish binaries

-To run this you will need access to the release credentials.

-Get them from [the infrastructure maintainers](

-https://github.com/dotcloud/docker/blob/master/hack/infrastructure/MAINTAINERS).

+To run this you will need access to the release credentials. Get them from the Core maintainers.

+

+Replace "..." with the respective credentials:

 ```bash

 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 \

        -e AWS_S3_BUCKET=test.docker.io \

-       -e AWS_ACCESS_KEY \

-       -e AWS_SECRET_KEY \

-       -e GPG_PASSPHRASE \

+       -e AWS_ACCESS_KEY="..." \

+       -e AWS_SECRET_KEY="..." \

+       -e GPG_PASSPHRASE="..." \

        -i -t --privileged \

        docker \

        hack/release.sh

 ```

-It will run the test suite one more time, build the binaries and packages,

+It will run the test suite, build the binaries and packages,

 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 as

 noted below).

@@ -183,15 +195,15 @@ get.docker.io:

 ```bash

 docker run \

        -e AWS_S3_BUCKET=get.docker.io \

-       -e AWS_ACCESS_KEY \

-       -e AWS_SECRET_KEY \

-       -e GPG_PASSPHRASE \

+       -e AWS_ACCESS_KEY="..." \

+       -e AWS_SECRET_KEY="..." \

+       -e GPG_PASSPHRASE="..." \

        -i -t --privileged \

        docker \

        hack/release.sh

 ```

-### 9. Breakathon

+### 8. Breakathon

 Spend several days along with the community explicitly investing time and

 resources to try and break Docker in every possible way, documenting any

@@ -207,28 +219,28 @@ by the book.

 Any issues found may still remain issues for this release, but they should be

 documented and give appropriate warnings.

-### 10. Apply tag

+### 9. Apply tag

+

+It's very important that we don't make the tag until after the official

+release is uploaded to get.docker.io!

 ```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!

-

-### 11. Go to github to merge the `bump_$VERSION` branch into release

+### 10. Go to github to merge the `bump_$VERSION` branch into release

 Don't forget to push that pretty blue button to delete the leftover

 branch afterwards!

-### 12. Update the docs branch

+### 11. Update the docs branch

 You will need the `awsconfig` file added to the `docs/` directory to contain the

 s3 credentials for the bucket you are deploying to.

 ```bash

-git checkout docs

+git checkout -b docs release || git checkout docs

 git fetch

 git reset --hard origin/release

 git push -f origin docs

@@ -239,7 +251,7 @@ The docs will appear on http://docs.docker.io/ (though there may be cached

 versions, so its worth checking http://docs.docker.io.s3-website-us-west-2.amazonaws.com/).

 For more information about documentation releases, see `docs/README.md`.

-### 13. Create a new pull request to merge release back into master

+### 12. Create a new pull request to merge release back into master

 ```bash

 git checkout master

@@ -250,14 +262,14 @@ 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"

+git push $GITHUBUSER merge_release_$VERSION

+echo "https://github.com/$GITHUBUSER/docker/compare/dotcloud:master...$GITHUBUSER:merge_release_$VERSION?expand=1"

 ```

 Again, get two maintainers to validate, then merge, then push that pretty

 blue button to delete your branch.

-### 14. Rejoice and Evangelize!

+### 13. Rejoice and Evangelize!

 Congratulations! You're done.