Release Guide
This guide describes the process of doing an official release of Mesos.
Prerequisites
-
Ensure that you have a GPG key or generate a new one, e.g., using
gpg --gen-key
. -
Add your GPG public key to the Apache Mesos dist repository in the KEYS file.
-
Fetch the svn repository:
svn co https://dist.apache.org/repos/dist/release/mesos
-
Append your public key using one of methods described in KEYS, e.g.,
(gpg --list-sigs <your name> && gpg --armor --export <your name>) >> KEYS
. -
Push the commit:
svn ci
-
-
Submit your GPG public key to a keyserver, e.g., MIT PGP Public Key Server.
-
Add your GPG fingerprint (
gpg --fingerprint <your name>
) to your Apache account. -
Create a Maven settings file (
~/.m2/settings.xml
) for the Apache servers where you must copy your encrypted Apache password which you can get from runningmvn --encrypt-password
(NOTE: you may need to first generate a master password.<settings> <servers> <server> <id>apache.snapshots.https</id> <username>APACHE USERNAME</username> <password>APACHE ENCRYPTED PASSWORD</password> </server> <server> <id>apache.releases.https</id> <username>APACHE USERNAME</username> <password>APACHE ENCRYPTED PASSWORD</password> </server> </servers> </settings>
-
Use
gpg-agent
to avoid typing your passphrase repeatedly.
Preparation
-
Go to Apache Jira and make sure that the CHANGELOG for the release version is up to date.
NOTE: You should move all Unresolved tickets marked with
Fix Version
orTarget Version
as the release version to the next release version.PROTIP: Use a JIRA dashboard (example) to track the progress of targeted issues as the release date approaches.
PROTIP: Use
bulk edit
option in JIRA to move the tickets and make sure to uncheck the option that emails everyone about the move. -
Update and commit the
CHANGELOG
for the release. For major releases we like to call out any major features, API changes, or deprecations.NOTE: You should use JIRA to generate the CHANGELOG for you. Click on the release version in JIRA and click on the
Release Notes
. Make sure to configure the release notes in text format.NOTE: The JIRA Release Notes will list only tickets with
Fix Version
set to that version. You should check for any Resolved tickets that haveTarget Version
set but notFix Version
. Also check for any Unresolved orDuplicate
/Invalid
tickets that incorrectly set theFix Version
. -
If not already done, update and commit
configure.ac
andCMakeLists.txt
for the release. -
Run
support/generate-endpoint-help.py
and commit any resulting changes. -
Update and commit
docs/configuration.md
to reflect the current state of the master, agent, and configure flags. -
Update and commit
docs/upgrades.md
with instructions about how to upgrade a live cluster from the previous release version to this release version. -
If this is a major release, please ensure that user documentation has been added for any new features.
-
Make sure that for any updates of the API, specifically the scheduler API, the public mesos protobuf definitions are part of both,
include/mesos
as well asinclude/mesos/v1
. NOTE: This might actually demand code updates if any omissions were identified.
Tagging the release candidate
-
Ensure that you can build and pass all the tests.
$ sudo make -j<cores> distcheck
-
Run the benchmarks and compare with the previous release for any performance regressions:
$ make bench -j<cores> GTEST_FILTER="*BENCHMARK*"
-
First tag the required SHA locally.
$ git tag <X.Y.Z-rcR>
NOTE:
X.Y.Z
is based on semantic versioning scheme.R
is release candidate version that starts with 1. -
Tag the release externally and deploy the corresponding JAR to the Apache maven repository. It is recommended to use the
support/tag.sh
script to accomplish this.$ ./support/tag.sh X.Y.Z R
NOTE: This script assumes that you have the requisite permissions to deploy the JAR. For instructions on how to set it up, please refer to
src/java/MESOS-MAVEN-README
.NOTE: gnu-sed (Linux) requires
-i''
instead of the-i ''
(space-separated) that default OSX uses. You may need to modify your local copy of tag.sh for it to complete successfully. -
It is not uncommon to release multiple release candidates, with increasing release candidate version, if there are bugs found.
-
Update to the next Mesos version in
configure.ac
: changeAC_INIT([mesos], [X.Y.Z]))
, as well as inCMakeLists.txt
: changeset(MESOS_MAJOR_VERSION X)
,set(MESOS_MINOR_VERSION Y)
,set(MESOS_PATCH_VERSION Z)
and then commit.
Voting the release candidate
-
Once a release candidate is deemed worthy to be officially released you should call a vote on the
dev@mesos.apache.org
(and optionallyuser@mesos.apache.org
) mailing list. -
It is recommended to use the
support/vote.sh
script to vote the release candidate.$ ./support/vote.sh X.Y.Z R
-
The release script also spits out an email template that you could use to send the vote email.
NOTE: The
date -v+3d
command does not work on some platforms (e.g. Ubuntu), so you may need to fill in the vote end date manually. The vote should last for 3 business days instead of 3 calendar days anyway. Sometimes we prefer a weeklong vote, to allow more time for integration testing.
Preparing a new release candidate
-
If the vote does not pass (any -1s or showstopper bugs), track the issues as new JIRAs for the release.
-
When all known issues are resolved, update the CHANGELOG with the newly fixed JIRAs.
-
Once all patches are committed to master, cherry-pick them on top of the previous release candidate tag. This is the same process used for point releases (e.g. 0.22.1) as well.
$ git checkout X.Y.Z-rcR $ git cherry-pick abcdefgh...
-
Now go back up to the "Tagging the release candidate" section and repeat.
Releasing the release candidate
-
You should only release an official version if the vote passes with at least 3 +1 binding votes and no -1 votes. For more information, please refer to Apache release guidelines.
-
It is recommended to use
support/release.sh
script to release the candidate.$ ./support/release.sh X.Y.Z R
-
The release script also spits out an email template that you could use to notify the mailing lists about the result of the vote and the release.
NOTE: Make sure you fill the email template with the names of binding voters.
Updating the wiki
Update the wiki entry, Mesos Release Planning.
Updating the website
-
After a successful release, add the information associated with the release in
site/data/releases.yml
. It is used to generate the release information on the website. -
Update the Getting Started guide to use the latest release link.
-
Check out the website from svn.
$ svn co https://svn.apache.org/repos/asf/mesos/site mesos-site
See our website README for details on how to build the website. See the general Apache project website guide for details on how to publish the website.
- Write a blog post announcing the new release and its features and major bug fixes. Include a link to the updated website.
Remove old releases from svn
Per the guidelines when to archive, we should only keep the latest release in each version under development.
-
Checkout the mesos distribution folder:
svn co https://dist.apache.org/repos/dist/release/mesos
-
Remove all minor versions that are no longer under development and commit the change.
Release the version on JIRA
- Find the released Mesos version on https://issues.apache.org/jira/plugins/servlet/project-config/MESOS/versions, and "release" it (click on "settings" --> "Release") with the correct release date.
Update external tooling
Upload the mesos.interface package to PyPi.
- Create/use a PyPi account with access to the mesos.interface submit form. You may need to ask a current package owner to add you as an owner/maintainer.
- Setup your
~/.pypirc
with your PyPi username and password. - After a successful Mesos
make
(any architecture), cd tobuild/src/python/interface
. - Run
python setup.py register
to register this package. - Run
python setup.py sdist bdist_egg upload
to upload the source distribution and egg for this package.
Update the Mesos Homebrew package.
- Update the Homebrew formula for Mesos and test.
- Submit a PR to the Homebrew repo.
- Once accepted, verify that
brew install mesos
works.