mirror of
https://github.com/docker/compose.git
synced 2026-07-02 22:26:55 +00:00
Document new release process
Signed-off-by: Joffrey F <joffrey@docker.com>
This commit is contained in:
Joffrey F
parent
62fc24eb27
commit
7536c331e0
2 changed files with 185 additions and 148 deletions
184
script/release/README.md
Normal file
184
script/release/README.md
Normal file
|
|
@ -0,0 +1,184 @@
|
|||
# Release HOWTO
|
||||
|
||||
This file describes the process of making a public release of `docker-compose`.
|
||||
Please read it carefully before proceeding!
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The following things are required to bring a release to a successful conclusion
|
||||
|
||||
### Local Docker engine (Linux Containers)
|
||||
|
||||
The release script runs inside a container and builds images that will be part
|
||||
of the release.
|
||||
|
||||
### Docker Hub account
|
||||
|
||||
You should be logged into a Docker Hub account that allows pushing to the
|
||||
following repositories:
|
||||
|
||||
- docker/compose
|
||||
- docker/compose-tests
|
||||
|
||||
### A Github account and Github API token
|
||||
|
||||
Your Github account needs to have write access on the `docker/compose` repo.
|
||||
To generate a Github token, head over to the
|
||||
[Personal access tokens](https://github.com/settings/tokens) page in your
|
||||
Github settings and select "Generate new token". Your token should include
|
||||
(at minimum) the following scopes:
|
||||
|
||||
- `repo:status`
|
||||
- `public_repo`
|
||||
|
||||
This API token should be exposed to the release script through the
|
||||
`GITHUB_TOKEN` environment variable.
|
||||
|
||||
### A Bintray account and Bintray API key
|
||||
|
||||
Your Bintray account will need to be an admin member of the
|
||||
[docker-compose organization](https://github.com/settings/tokens).
|
||||
Additionally, you should generate a personal API key. To do so, click your
|
||||
username in the top-right hand corner and select "Edit profile" ; on the new
|
||||
page, select "API key" in the left-side menu.
|
||||
|
||||
This API key should be exposed to the release script through the
|
||||
`BINTRAY_TOKEN` environment variable.
|
||||
|
||||
### A PyPi account
|
||||
|
||||
Said account needs to be a member of the maintainers group for the
|
||||
[`docker-compose` project](https://pypi.org/project/docker-compose/).
|
||||
|
||||
Moreover, the `~/.pypirc` file should exist on your host and contain the
|
||||
relevant pypi credentials.
|
||||
|
||||
## Start a feature release
|
||||
|
||||
A feature release is a release that includes all changes present in the
|
||||
`master` branch when initiated. It's typically versioned `X.Y.0-rc1`, where
|
||||
Y is the minor version of the previous release incremented by one. A series
|
||||
of one or more Release Candidates (RCs) should be made available to the public
|
||||
to find and squash potential bugs.
|
||||
|
||||
From the root of the Compose repository, run the following command:
|
||||
```
|
||||
./script/release/release.sh -b <BINTRAY_USERNAME> start X.Y.0-rc1
|
||||
```
|
||||
|
||||
After a short initialization period, the script will invite you to edit the
|
||||
`CHANGELOG.md` file. Do so by being careful to respect the same format as
|
||||
previous releases. Once done, the script will display a `diff` of the staged
|
||||
changes for the bump commit. Once you validate these, a bump commit will be
|
||||
created on the newly created release branch and pushed remotely.
|
||||
|
||||
The release tool then waits for the CI to conclude before proceeding.
|
||||
If failures are reported, the release will be aborted until these are fixed.
|
||||
Please refer to the "Resume a draft release" section below for more details.
|
||||
|
||||
Once all resources have been prepared, the release script will exit with a
|
||||
message resembling this one:
|
||||
|
||||
```
|
||||
You're almost done! Please verify that everything is in order and you are ready
|
||||
to make the release public, then run the following command:
|
||||
./script/release/release.sh -b user finalize X.Y.0-rc1
|
||||
```
|
||||
|
||||
Once you are ready to finalize the release (making binaries and other versioned
|
||||
assets public), proceed to the "Finalize a release" section of this guide.
|
||||
|
||||
## Start a patch release
|
||||
|
||||
A patch release is a release that builds off a previous release with discrete
|
||||
additions. This can be an RC release after RC1 (`X.Y.0-rcZ`, `Z > 1`), a GA release
|
||||
based off the final RC (`X.Y.0`), or a bugfix release based off a previous
|
||||
GA release (`X.Y.Z`, `Z > 0`).
|
||||
|
||||
From the root of the Compose repository, run the following command:
|
||||
```
|
||||
./script/release/release.sh -b <BINTRAY_USERNAME> start --patch=BASE_VERSION RELEASE_VERSION
|
||||
```
|
||||
|
||||
The process of starting a patch release is identical to starting a feature
|
||||
release except for one difference ; at the beginning, the script will ask for
|
||||
PR numbers you wish to cherry-pick into the release. These numbers should
|
||||
correspond to existing PRs on the docker/compose repository. Multiple numbers
|
||||
should be separated by whitespace.
|
||||
|
||||
Once you are ready to finalize the release (making binaries and other versioned
|
||||
assets public), proceed to the "Finalize a release" section of this guide.
|
||||
|
||||
## Finalize a release
|
||||
|
||||
Once you're ready to make your release public, you may execute the following
|
||||
command from the root of the Compose repository:
|
||||
```
|
||||
./script/release/release.sh -b <BINTRAY_USERNAME> finalize RELEAE_VERSION
|
||||
```
|
||||
|
||||
Note that this command will create and publish versioned assets to the public.
|
||||
As a result, it can not be reverted. The command will perform some basic
|
||||
sanity checks before doing so, but it is your responsibility to ensure
|
||||
everything is in order before pushing the button.
|
||||
|
||||
After the command exits, you should make sure:
|
||||
|
||||
- The `docker/compose:VERSION` image is available on Docker Hub and functional
|
||||
- The `pip install -U docker-compose==VERSION` command correctly installs the
|
||||
specified version
|
||||
- The install command on the Github release page installs the new release
|
||||
|
||||
## Resume a draft release
|
||||
|
||||
"Resuming" a release lets you address the following situations occurring before
|
||||
a release is made final:
|
||||
|
||||
- Cherry-pick additional PRs to include in the release
|
||||
- Resume a release that was aborted because of CI failures after they've been
|
||||
addressed
|
||||
- Rebuild / redownload assets after manual changes have been made to the
|
||||
release branch
|
||||
- etc.
|
||||
|
||||
From the root of the Compose repository, run the following command:
|
||||
```
|
||||
./script/release/release.sh -b <BINTRAY_USERNAME> resume RELEASE_VERSION
|
||||
```
|
||||
|
||||
The release tool will attempt to determine what steps it's already been through
|
||||
for the specified release and pick up where it left off. Some steps are
|
||||
executed again no matter what as it's assumed they'll produce different
|
||||
results, like building images or downloading binaries.
|
||||
|
||||
## Cancel a draft release
|
||||
|
||||
If issues snuck into your release branch, it is sometimes easier to start from
|
||||
scratch. Before a release has been finalized, it is possible to cancel it using
|
||||
the following command:
|
||||
```
|
||||
./script/release/release.sh -b <BINTRAY_USERNAME> cancel RELEASE_VERSION
|
||||
```
|
||||
|
||||
This will remove the release branch with this release (locally and remotely),
|
||||
close the associated PR, remove the release page draft on Github and delete
|
||||
the Bintray repository for it, allowing you to start fresh.
|
||||
|
||||
## Manual operations
|
||||
|
||||
Some common, release-related operations are not covered by this tool and should
|
||||
be handled manually by the operator:
|
||||
|
||||
- After any release:
|
||||
- Announce new release on Slack
|
||||
- After a GA release:
|
||||
- Close the release milestone
|
||||
- Merge back `CHANGELOG.md` changes from the `release` branch into `master`
|
||||
- Bump the version in `compose/__init__.py` to the *next* minor version
|
||||
number with `dev` appended. For example, if you just released `1.4.0`,
|
||||
update it to `1.5.0dev`
|
||||
|
||||
## Advanced options
|
||||
|
||||
You can consult the full list of options for the release tool by executing
|
||||
`./script/release/release.sh --help`.
|
||||
Loading…
Add table
Add a link
Reference in a new issue