Return-Path: X-Original-To: apmail-zest-commits-archive@minotaur.apache.org Delivered-To: apmail-zest-commits-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 55EDD177EF for ; Tue, 28 Jul 2015 12:54:59 +0000 (UTC) Received: (qmail 33538 invoked by uid 500); 28 Jul 2015 12:54:59 -0000 Delivered-To: apmail-zest-commits-archive@zest.apache.org Received: (qmail 33457 invoked by uid 500); 28 Jul 2015 12:54:59 -0000 Mailing-List: contact commits-help@zest.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@zest.apache.org Delivered-To: mailing list commits@zest.apache.org Received: (qmail 33139 invoked by uid 99); 28 Jul 2015 12:54:58 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 28 Jul 2015 12:54:58 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 789CAE188E; Tue, 28 Jul 2015 12:54:58 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit From: paulmerlin@apache.org To: commits@zest.apache.org Date: Tue, 28 Jul 2015 12:55:09 -0000 Message-Id: <2064c6f171a44541afdae6aa197cf930@git.apache.org> In-Reply-To: References: X-Mailer: ASF-Git Admin Mailer Subject: [12/50] zest-java git commit: ZEST-100 Release process documentation draft progress ZEST-100 Release process documentation draft progress Project: http://git-wip-us.apache.org/repos/asf/zest-java/repo Commit: http://git-wip-us.apache.org/repos/asf/zest-java/commit/83062452 Tree: http://git-wip-us.apache.org/repos/asf/zest-java/tree/83062452 Diff: http://git-wip-us.apache.org/repos/asf/zest-java/diff/83062452 Branch: refs/heads/master Commit: 83062452fe76449cd210232e2af97753157a6e73 Parents: 2e2bdbe Author: Paul Merlin Authored: Tue Jul 21 12:18:24 2015 +0200 Committer: Paul Merlin Committed: Tue Jul 21 12:18:24 2015 +0200 ---------------------------------------------------------------------- .../docs/tutorials/howto-releasing-apache.txt | 317 +++++++++++++++---- 1 file changed, 256 insertions(+), 61 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/zest-java/blob/83062452/manual/src/docs/tutorials/howto-releasing-apache.txt ---------------------------------------------------------------------- diff --git a/manual/src/docs/tutorials/howto-releasing-apache.txt b/manual/src/docs/tutorials/howto-releasing-apache.txt index f60dc3a..636a36c 100644 --- a/manual/src/docs/tutorials/howto-releasing-apache.txt +++ b/manual/src/docs/tutorials/howto-releasing-apache.txt @@ -29,57 +29,114 @@ The instructions provided here are consistent with, but not a replacement for th Before going further you obviously should have read the <> tutorial and already built Zest™ from source, signing included. -// Inspirations -// https://commons.apache.org/releases/prepare.html -// https://wiki.apache.org/logging/Log4j2ReleaseGuide -// https://accumulo.apache.org/releasing.html + +// TODOs +// - put the release notes on the website +// - review commands for managing dev/release dist uploads, they may be too greedy + == Preparing a release + === Select a Release Manager A Zest committer (normally one of the development team) should post an email to the development list proposing that a release be made and nominating a release manager. Typically, the proposer volunteers as the release manager and it passes by https://www.apache.org/foundation/glossary.html#LazyConsensus[lazy consensus]. -=== Ensure your setup is ready - +=== Clone/Checkout all repositories Clone/checkout all needed repositories, next to each other: - mkdir zest-repos - cd zest-repos - git clone .... zest-java - svn checkout https://... zest-svn - svn checkout https://... zest-dist-dev - svn checkout https://... zest-dist-release +[source,shell] +---- +mkdir zest-repos +cd zest-repos +git clone https://git-wip-us.apache.org/repos/asf/zest-qi4j.git zest-java +svn checkout https://svn.apache.org/repos/asf/zest/ zest-svn +svn checkout https://dist.apache.org/repos/dist/dev/zest/ zest-dist-dev +svn checkout https://dist.apache.org/repos/dist/release/zest/ zest-dist-release +---- You should then get the following directory tree: - . - └── zest-repos - ├── zest-java - ├── zest-svn - ├── zest-dist-dev # Release candidate distri - └── zest-dist-release +[source,text] +---- +. +└── zest-repos + ├── zest-java # Apache Zest™ (Java Edition) source + ├── zest-svn # https://zest.apache.org/ website + ├── zest-dist-dev # Releases candidate distributions + └── zest-dist-release # Releases distributions +---- + + +=== Build Apache Zest™ (Java Edition) Ensure you can test, build and sign Zest, including artifact signing, see the <> tutorial. + +=== Install Jekyll + Moreover, you will need to have a valid http://jekyllrb.com/[Jekyll] installation as the Apache Zest™ https://zest.apache.org/[website] is baked with it. + +=== Setup git flow + +`git-flow` is a git extension that add git commands to easily use the git flow branching model the Apache Zest™ project follows. +See the https://github.com/nvie/gitflow/wiki/Installation[installation instructions]. + + +=== Setup git signing + Ensure you can sign git tags. - TODO DOCUMENT! +[source,shell] +---- +git config --global user.signingkey +---- + +See the https://git-scm.com/book/tr/v2/Git-Tools-Signing-Your-Work[Git Tools - Signing Your Work] section of the Git book. + + +=== Setup Apache Nexus credentials + +See the Apache https://www.apache.org/dev/publishing-maven-artifacts.html[Publishing Maven Artifacts] guide and the Apache Zest™ (Java Edition) <> tutorial. === Update the `KEYS` file if needed. - TODO DOCUMENT! +The reference `KEYS` file can be found at the `zest-java` repository's root. + +Diff the ones present in the `dev` and `release` distribution areas: + +[source,shell] +---- +diff zest-java/KEYS zest-dist-dev/KEYS +diff zest-java/KEYS zest-dist-release/KEYS +---- + +And update them if needed: + +[source,shell] +---- +cp zest-java/KEYS zest-dist-dev/KEYS +cp zest-java/KEYS zest-dist-release/KEYS +cd zest-dist-dev +svn add KEYS +svn commit -m "zest: updating KEYS in dist/dev/zest" +cd .. +cd zest-dist-release +svn add KEYS +svn commit -m "zest: updating KEYS in dist/release/zest" +---- + == Creating a Release Candidate + === Resolve JIRA issues Resolve all issues on that version! @@ -98,97 +155,194 @@ Apache Zest™ release notes are generated from JIRA issues. Open the target Zest™ version's release notes in https://issues.apache.org/jira/browse/ZEST/?selectedTab=com.atlassian.jira.jira-projects-plugin:roadmap-panel[JIRA] and review them. - TODO DO SOMETHING WITH RELEASE NOTES!!!!! +JIRA can produces release notes as HTML or plain-text. +We will use plain-text release notes in e-mails and will need to convert the HTML releases notes to Asciidoc for use in the website. + +Prepare the two following files: +- `apache-zest-java--release-notes.txt` +- `apache-zest-java--release-notes.adoc` -=== Create a release branch +We will use them later. - git flow release start -RC# +=== Create a release candidate branch -=== Make a complete check +We use `-RC#` where `RELEASE-VERSION` is the target release version and `RC#` for Release Candidate and an incremental number in case the release process has to be done several times. + +[source,shell] +---- +git flow release start -RC# +---- + +This will eventually generates a `-RC#` tag that we will rename to `` if the vote passes, see below. + + +=== Build and audit distributions Make a complete build: - ./gradlew -Dversion= clean check buildAll +[source,shell] +---- +./gradlew -Dversion= clean check buildAll +---- Review the release distributions in `build/distributions`. If any, make the required changes, commit them and iterate. -=== Close the release branch - git flow release finish -RC# +=== Close the release candidate branch + +Once you are satisfied with the produced artifacts, close the release candidate branch: + +[source,shell] +---- +git flow release finish -RC# +---- + === Checkout the release candidate tag -This is necessary because built artifacts include git metadata. +To build the release candidate bits, we need to checkout the release candidate tag, that will eventually be promoted as a signed release tag, because the Apache Zest™ build system generates versionning information based on git metadata. + +[source,shell] +---- +git checkout -RC# +---- - git checkout -RC# === Build artifacts and distributions - ./gradlew -Dversion= clean check buildAll +[source,shell] +---- +./gradlew -Dversion= clean check buildAll +---- + === Stage maven artifacts Stage artifacts to https://repository.apache.org/[repository.apache.org] : - ./gradlew -Dversion= release - -Close the staging Nexus repository: +[source,shell] +---- +./gradlew -Dversion= release +---- - TODO DOCUMENT! +Close the staging Nexus repository by following the https://www.apache.org/dev/publishing-maven-artifacts.html#close-stage[Closing the staged repository] guide. === Upload distributions Upload source and binary distributions, checksums and signatures to https://dist.apache.org/repos/dist/dev/zest/[dist.apache.org/repos/dist/dev/zest]: - TODO DOCUMENT! +[source,shell] +---- +cp zest-java/build/distributions/* zest-dist-dev/ +cd zest-dist-dev +svn add --force +svn commit -m "zest: upload to dist/dev/zest" +---- + +Go grab some coffee/tea/beer, this will take some time. == Run the vote Send a "VOTE" to the mailto:dev@zest.apache.org[developer mailing list] including links to release artifacts. A VOTE always contains two parts. Send an email to the developer mailing list with the subject line: - [VOTE] Release Zest (Java Edition) version +[source,text] +---- +[VOTE] Release Zest (Java Edition) version +---- + +Here is a sample template: + +[source,text] +---- +Dear community, + +I am happy to start the VOTE thread for Apache Zest (Java Edition) ! + +The changelog for this release can be found here: https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12316820&version=12332997 + +Tag: https://git-wip-us.apache.org/repos/asf?p=zest-qi4j.git;a=tag;h=cc0f8211bf47b2df72a6239c9fdcd1d6906ea246 + +The artifacts to be voted on are located here: https://dist.apache.org/repos/dist/dev/zest/ + +Release artifacts are signed with the following key: https://dist.apache.org/repos/dist/dev/zest/KEYS + +Please vote on releasing this package as Apache Zest (Java Edition) . + +The vote is open for the next 72 hours and passes if a majority of at least three +1 PMC votes are cast and there must be more positive than negative votes. + +[ ] +1 Release Apache Zest (Java Edition) +[ ] 0 I don't have a strong opinion about this, but I assume it's ok +[ ] -1 Do not release Apache Zest (Java Edition) because... + +Here is my vote: + ++1 (binding) + +Cheers +---- After the vote is over, send a "RESULT" email to the list with the subject line: - [RESULT][VOTE] Release Zest (Java Edition) version +[source,text] +---- +[RESULT][VOTE] Release Zest (Java Edition) version +---- Votes on whether a package is ready to be released use majority approval -- i.e., at least three PMC members must vote affirmatively for release, and there must be more positive than negative votes. + == VOTE passes === Seal the release -Rename and sign the git tag +Create and sign the release git tag from the unsigned release candidate tag: - TODO DOCUMENT! +[source,shell] +---- +cd zest-java +git tag -s -RC# +---- Push all git changes: - cd zest-java - git checkout master - git push origin master - git checkout develop - git push origin master - git push --tags +[source,shell] +---- +cd zest-java +git checkout master +git push origin master +git checkout develop +git push origin master +git push origin --tags +---- === Publish -Publish the Nexus repository. - - TODO DOCUMENT! +Promote the staged Nexus repository so it gets synched to Maven Central by following the https://www.apache.org/dev/publishing-maven-artifacts.html#promote[Promoting a repo] guide. Move the release distributions, checksums and signatures from https://dist.apache.org/repos/dist/dev/zest/[dist.apache.org/repos/dist/dev/zest] to https://dist.apache.org/repos/dist/release/zest/[dist.apache.org/repos/dist/release/zest] - TODO DOCUMENT! - +[source,shell] +---- +mv zest-dist-dev/**.* zest-dist-release/ +cd zest-dist-dev +svn add --force +svn commit -m "zest: removing from dist/dev/zest as the VOTE passed" +cd .. +cd zest-dist-release +svn add --force +svn commit -m "zest: upload to dist/release/zest"" +---- + +Once again, go grab some coffee/tea/beer, this will take some time. + === Wait 24 hours @@ -202,34 +356,75 @@ Upmost is the latest. Then rebuild the website: - cd zest-svn - jekyll build +[source,shell] +---- +cd zest-svn +jekyll build +---- And publish it: - svn add --force - svn commit -m "zest: update website" +[source,shell] +---- +svn add --force +svn commit -m "zest: update website" +---- + === Register the release -Finally, register the new release at https://reporter.apache.org/[reporter.apache.org] +Register the new release at https://reporter.apache.org/[reporter.apache.org] === Announce -Send an announcement to mailto:dev@zest.apache.org[dev@] and mailto:users@zest.apache.org[users@] mailing lists. Email announcements should have the subject line: +Finally, send an announcement to mailto:dev@zest.apache.org[dev@] and mailto:users@zest.apache.org[users@] mailing lists. Email announcements should have the subject line: + +[source,text] +---- +[ANNOUNCE] Released Zest (Java Edition) version +---- + +The announcement email should contains the release notes as text, remember you prepared a `apache-zest-java--release-notes.txt` file with them. - [ANNOUNCE] Released Zest (Java Edition) version == VOTE fails -Drop the Nexus staging repository. - TODO DOCUMENT! +=== Drop artifacts and distributions + +Drop the Nexus staging repository by following the https://www.apache.org/dev/publishing-maven-artifacts.html#drop[Dropping a repo] guide. Drop distributions, checksums and signatures from https://dist.apache.org/repos/dist/dev/zest/[dist.apache.org/repos/dist/dev/zest] - TODO DOCUMENT! +[source,shell] +---- +cd zest-dist-dev/ +rm "**.*" +svn add --force +svn commit -m "zest: dropping from dist/dev/zest as the vote failed" +---- + + +=== Push git changes + +We keep the release candidate git history. +It can be useful for reviewers to have access to it. +Remember, we created a release candidate branch and tags, no signed release tag. + +[source,shell] +---- +cd zest-java +git checkout master +git push origin master +git checkout develop +git push origin master +git push origin --tags +---- + + +=== Start over + +If a new RC is to be created, restart the process as described above. -Drop your local `zest-java` clone and start over.