This document describes how to release Apache Omid from trunk.
It is a work in progress and should be refined by the Release Manager (RM) as they come across aspects of the release process not yet documented here.
NOTE: For the purpose of illustration, this document assumes that the version being released is 0.10.0.0 and the following development version will become 0.10.1.0
NOTE: that only Omid committers can create a release.
Software
You might need
- gpg2
- git client
- svn client (yes, svn to push to dist, don't ask me why )
- jdk7 (not 8)
- maven
Setting up the signing keys
Before you do a release you'll need a signing key that is registered with apache. If you already have one, you can skip this section. Otherwise, here are the steps to do:
Use
gpg2 --gen-key
to generate a new key. Make sure that the key size is 4096 bits, the key doesn't expire
Now you need to register your key at http://pgp.mit.edu/ using the output of
gpg --armor --export <keyid>
- Add your key to the KEYS file, commit, push to git
- Upload digest to your account on id.apache.org (gpg2 --fingerprint)
Prerequisites
- Prepare release plan in the wiki, notifying the community the overall plan and goals for the release (For example: Release Plan 0.10.0). Use release template on confluence. Make sure to use JIRA filter there to display relevant issues.
Vote on release plan: Release manager should start a vote in dev@omid.incubator.apache.org, asking the community to approve the release plan.
To: dev@omid.incubator.apache.org Subject: [VOTE] Release plan - Omid 0.10.0 We are starting the process to prepare for Omid $release release. I have created release plan ($link) to cover the tasks under this release. If you have any JIRA in progress and would like to include it in this release, please follow the process to do so. Feel free to comment on the JIRA if you have any comments/suggestions.
- Go over JIRA for the release and make sure that blockers are marked as blockers and non-blockers are non-blockers.
- It is important that between the time that the release plan is voted to the time when the release branch is created, no experimental or potentially destabilizing work is checked into the trunk. While it is acceptable to introduce major changes, they must be thoroughly reviewed and have good test coverage to ensure that the release branch does not start of being unstable. If necessary the RM can discuss if certain issues should be fixed on the trunk in this time, and if so what is the gating criteria for accepting them.
Create Release Branch
- Make sure you are working with a clean repo (i.e. identical to upstream - no changes in progress). If needed clone a fresh copy
git checkout master
Check that current HEAD points to commit on which you want to base new release branch. Checkout particular commit if not.
git branch 0.10.0 git push apache 0.10.0
- Check that the branch was correctly propagated to Apache using the web UI
Switch back to master
git checkout master
Modify the version in trunk to bump version to the next one "0.10.1.0-SNAPSHOT" in pom.xml-s. Either search-replace or use maven
mvn versions:set -DnewVersion=0.10.1.0-SNAPSHOT
Commit and push to master in apache
git commit -m"[ci skip] prepare for next development iteration" git push apache
- Build to validates the new branch
git checkout 0.10.0 mvn clean site
- Send email announcing the new branch
To: dev@omid.incubator.apache.org Subject: New release branch 0.10.0 Hello Omid developers and friends, We now have a release branch for 0.10.0 release (with 0.10.0.0 as the version). Trunk has been bumped to 0.10.1.0-SNAPSHOT. I'll be going over the JIRAs to move every non-blocker from this release to the next release. From this point, most changes should go to trunk. * Blockers (existing and new that we discover while testing the release) will be double-committed. * Please discuss with your reviewer whether your PR should go to trunk or to trunk+release so they can merge accordingly.
Create Release Artifacts
Because our release branch is still 0.10.0.0-SNAPSHOT but our release artifact needs to be 0.10.0.0, we'll make the change in a tag:
Modify the version in 0.10.0 branch to remove "-SNAPSHOT" in pom.xml-s. Either search-replace or use maven
mvn versions:set -DnewVersion=0.10.0.0
Commit locally, but don't push to Apache
git commit -m"[ci skip] prepare release omid-0.10.0.0"
Prepare an release candidate (RC) tag. This will tag the version change commit, get the rc part to match the actual rc number
git tag -a 0.10.0.0-rc0
Move the branch head back, so future commits will still have "-SNAPSHOT"
git reset --hard HEAD~1
Push the tag to Apache
git push --tags
Prepare a public release staging area
Binary artifacts are stored in Dist. You need an SVN client to manipulate Apache Dist. Use your apache account username. If you have not done so before, create a folder for binary staging area.
svn co https://dist.apache.org/repos/dist/release/incubator/omid <path_to>omid-dist --username ikatkov
Create sub-folder matching to current release number
mkdir <path_to>omid-dist/0.10.0.0_RELEASE cd 0.10.0.0_RELEASE/ git clone https://git-wip-us.apache.org/repos/asf/incubator-omid.git/ omid cd omid git checkout -b 0.10.0 tags/0.10.0.0-rc0 cp KEYS ..
Important: checkout the tag, or you'll be releasing SNAPSHOT accidentally.
RELEASE_NOTES
- Go to JIRA, move all unresolved jiras with "Fix versions" of 0.10.0.0 to future releases.
- Select roadmap from left panel, click on "release notes" next to the release version and prepare/format the html release notes. The html version shows up at the bottom of the page. Save the release notes as RELEASE_NOTES.html
Sources
Now prepare the source (after getting your keys local to the box)
prepare archive
git archive --format tar.gz --prefix apache-omid-incubating-0.10.0.0-src/ -o ../apache-omid-incubating-0.10.0.0-src 0.10.0.0-rc0
sign the artifact
gpg --armor --output apache-omid-incubating-0.10.0.0-src.tgz.asc --detach-sig apache-omid-incubating-0.10.0.0-src.tgz gpg --print-md MD5 apache-omid-incubating-0.10.0.0-src.tgz > apache-omid-incubating-0.10.0.0-src.tgz.md5
upload the artifacts to dist
cd <path_to>omid-dist rm -rf <path_to>omid-dist/0.10.0.0_RELEASE/omid svn add 0.10.0.0_RELEASE/ --force svn commit --message "Omid Release 0.10.0.0-rc0" --username ikatkov
- Check that they are there, see Dist
Validate the signatures, download the files you signed and uploaded
mkdir temp cd temp/ wget -r https://dist.apache.org/repos/dist/release/incubator/omid/0.10.0.0_RELEASE cd 0.10.0.0_RELEASE gpg --verify apache-omid-incubating-0.10.0.0-src.tgz.asc apache-omid-incubating-0.10.0.0-src.tgz
Update website
Stage the release artifacts to the Apache Nexus repository
Make sure that you can login to https://repository.apache.org/ with your apache id/passwd. The value for signing.keyId can be found by running "gpg --list-secret-keys --fingerprint". The number after the / in the first line is your signing.keyId.
Edit or create ~/.m2/settings.xml introducing the values that are specific to you:
<settings> <servers> <server> <id>apache.snapshots.https</id> <username>your apache id</username> <password>your apache password</password> </server> <server> <id>apache.staging.https</id> <username>your apache id</username> <password>your apache password</password> </server> </servers> <profiles> <profile> <id>gpg</id> <properties> <gpg.passphrase>your GPG password</gpg.passphrase> </properties> </profile> </profiles> </settings>
See http://maven.apache.org/guides/mini/guide-encryption.html for details on encrypting the passwords rather than leaving them in the clear.
Run the following on the release branch
mvn deploy -Dstaging=true
Apache Nexus
Enter Apache Nexus and do the following:
- Click on Log In in the upper right corner. Log in using your apache user name and password.
- In the left navigation pane, select Staging Repositories.
- Identify the release candidate you just pushed, by your user name (in parentheses as part of the "Repository" name) and the "Created On" date.
- Click on the check box to the left of your Repository name to select it.
- [Optional] If you accidentally click on the Repository name itself, another tab will pop open. If so, just close it.
- Click the Close button above the Repository names. This makes your release candidate available at the Staging level.
- The artifacts should show up under https://repository.apache.org/content/groups/staging/org/apache/omid with correct file modification dates.
- If you have previously staged an older release candidate with the same version number, and it is still showing in the Repository list, you must select and Drop the old one now.
Voting
Send out a voting email to dev@omid.incubator.apache.org
To: dev@omid.incubator.apache.org Subject: [VOTE] Omid release branch 0.10.0.0 Here's the Apache Omid 0.10.0.0 release candidate #0 now available for a vote within dev community. Links to various release artifacts are given below. Please review and vote. The vote will be open for at least 72 hours or until necessary number of votes are reached. [ ] +1 approve [ ] +0 no opinion [ ] -1 disapprove (and reason why) Here is my +1 Release notes for the 0.10.0.0 release: https://dist.apache.org/repos/dist/release/incubator/omid/0.10.0.0-rc0/RELEASE_NOTES.HTML Git tag for the release: https://git-wip-us.apache.org/repos/asf/incubator-omid.git/?p=incubator-omid-site.git;a=tag;h=72fd542633a95a8bd5bdc9fdca56042b643cb4b0 Sources for the release: https://dist.apache.org/repos/dist/release/incubator/omid/0.10.0.0-rc0/apache-omid-incubating-0.10.0.0-src.tgz Source release verification: PGP Signature: https://dist.apache.org/repos/dist/release/incubator/omid/0.10.0.0-rc0/apache-omid-incubating-0.10.0.0-src.tgz.asc MD5 Hash: https://dist.apache.org/repos/dist/release/incubator/omid/0.10.0.0-rc0/apache-omid-incubating-0.10.0.0-src.tgz.md5 Keys to verify the signature of the release artifact are available at: https://dist.apache.org/repos/dist/release/incubator/omid/0.10.0.0-rc0/KEYS
Verification for voters:
gpg --import KEYS (KEYS can be obtained from KEYS
)- gpg --verify foo-1.0.tar.gz.asc foo-1.0.tar.gz
- Run at least unit tests
If need to roll a new RC
- Go back to the beginning - don't forget to bump the RC number.
After the vote passes:
- Remember: at least 3 days, 3 +1 from PMC members (committers are not enough!) and no -1.
- Merge the last version change / rc tag into the release branch
- Update version on the branch to 0.10.0.1
Send a vote closing email
To: dev@omid.incubator.apache.org Subject: [RESULTS] [VOTE] Omid release branch 0.10.0.0 This vote passes with 8 +1 votes (4 bindings) and no 0 or -1 votes. +1 votes PMC Members: * $Name * $Name * $Name Committers: * $Name * $Name Community: * $Name * $Name 0 votes * No votes -1 votes * No votes Vote thread: <link> I'll continue in the release process and announce a release in the next few days. $RM