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 7056D177F1 for ; Tue, 28 Jul 2015 12:54:59 +0000 (UTC) Received: (qmail 33719 invoked by uid 500); 28 Jul 2015 12:54:59 -0000 Delivered-To: apmail-zest-commits-archive@zest.apache.org Received: (qmail 33577 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 33195 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 9985AE3621; 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:14 -0000 Message-Id: <2aa96dbd7dbf4c93ba74e0d0e435bd83@git.apache.org> In-Reply-To: References: X-Mailer: ASF-Git Admin Mailer Subject: [17/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/6e05a6f2 Tree: http://git-wip-us.apache.org/repos/asf/zest-java/tree/6e05a6f2 Diff: http://git-wip-us.apache.org/repos/asf/zest-java/diff/6e05a6f2 Branch: refs/heads/master Commit: 6e05a6f23c23bf5a18e6a48f5defd3729c3c39b5 Parents: 1e569f9 Author: Paul Merlin Authored: Tue Jul 21 17:51:44 2015 +0200 Committer: Paul Merlin Committed: Tue Jul 21 18:27:07 2015 +0200 ---------------------------------------------------------------------- .../src/docs/tutorials/howto-build-system.txt | 8 +- .../docs/tutorials/howto-releasing-apache.txt | 191 ++++++++++++++----- 2 files changed, 144 insertions(+), 55 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/zest-java/blob/6e05a6f2/manual/src/docs/tutorials/howto-build-system.txt ---------------------------------------------------------------------- diff --git a/manual/src/docs/tutorials/howto-build-system.txt b/manual/src/docs/tutorials/howto-build-system.txt index f5e3a2b..aa72a98 100644 --- a/manual/src/docs/tutorials/howto-build-system.txt +++ b/manual/src/docs/tutorials/howto-build-system.txt @@ -171,7 +171,7 @@ They can be run with the following Gradle command: Results will then be available in the test reports. -== Releasing the Zest™ SDK == +== Build for releases == IMPORTANT: Remember that if a +version+ property is not defined, the build system will refuse to make a release and upload. @@ -201,7 +201,7 @@ This can be relaxed by adding +-x checkReleaseSpec+ arguments to gradle invocati === Signing === Artifact signing is done using PGP. -You need to provide Gradle the following properties +You need to provide Gradle the following properties, `~/.gradle/gradle.properties` is a good place: signing.keyId=FB751943 signing.password=foobar @@ -233,7 +233,7 @@ For example here is how to deploy all artifacts as unsigned SNAPSHOTs to a given [source,bash] ----------- -./gradlew uploadArchives -Dversion=2.0-SNAPSHOT -PuploadReleaseSpec=false \ +./gradlew uploadArchives -Dversion=3.2.1-SNAPSHOT -PuploadReleaseSpec=false \ -PuploadWagon=what:ever:wagon -PuploadRepository=http://what.ever.repository/url \ -PuploadUsername=foo -PuploadPassword=bar ----------- @@ -242,7 +242,7 @@ And here is how to deploy a signed release to the local filesystem: [source,bash] ----------- -./gradlew uploadArchives -Dversion=2.0 -PuploadRepository=file:///path/to/local/repository +./gradlew uploadArchives -Dversion=3.2.1 -PuploadRepository=file:///path/to/local/repository ----------- See the http://www.gradle.org/docs/current/userguide/maven_plugin.html#wagonLibs[Gradle documentation] about http://git-wip-us.apache.org/repos/asf/zest-java/blob/6e05a6f2/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 636a36c..b7747a3 100644 --- a/manual/src/docs/tutorials/howto-releasing-apache.txt +++ b/manual/src/docs/tutorials/howto-releasing-apache.txt @@ -31,7 +31,6 @@ Before going further you obviously should have read the <-release-notes.txt` -- `apache-zest-java--release-notes.adoc` +First save the text-plain release-notes in a file named `apache-zest-java--release-notes.txt`. + +Convert to Asciidoc: + +[source,shell] +---- +cat apache-zest-java--release-notes.txt | \ + sed -e "s/* \[ZEST-\([0-9]\)*\]/- https:\/\/issues.apache.org\/jira\/browse\/ZEST-\1[ZEST-\1]/" | \ + sed -e "s/^\*\*/===/" > apache-zest-java--release-notes.adoc +---- + +Convert to Markdown: + +[source,shell] +---- +cat apache-zest-java--release-notes.txt | \ + sed -e "s/* \[ZEST-\([0-9]\)*\]/- [ZEST-\1](https:\/\/issues.apache.org\/jira\/browse\/ZEST-\1)/" | \ + sed -e "s/^\*\*/###/" > apache-zest-java--release-notes.md +---- + +You should then have the two following files: + +[source,shell] +---- +. +├── apache-zest-java--release-notes.txt +├── apache-zest-java--release-notes.adoc +└── apache-zest-java--release-notes.md +---- We will use them later. -=== Create a release candidate branch +=== Create a RC branch 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. @@ -178,21 +205,45 @@ 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 +=== Audit artifacts and distributions -Make a complete build: +Make a complete build, deploying maven artifacts locally: [source,shell] ---- -./gradlew -Dversion= clean check buildAll +./gradlew -Dversion= -PuploadRepository="file://$(pwd)/build/repositories/zest-java" \ + clean buildAll checkDists uploadArchives ---- -Review the release distributions in `build/distributions`. +Review maven artifacts in `build/repositories/zest-java`. + +Also review the release distributions in `build/distributions` where you should find the following files: + +[source,shell] +---- +. +├── apache-zest-java--bin.tgz +├── apache-zest-java--bin.tgz.MD5 +├── apache-zest-java--bin.tgz.SHA-512 +├── apache-zest-java--bin.tgz.asc +├── apache-zest-java--bin.zip +├── apache-zest-java--bin.zip.MD5 +├── apache-zest-java--bin.zip.SHA-512 +├── apache-zest-java--bin.zip.asc +├── apache-zest-java--src.tgz +├── apache-zest-java--src.tgz.MD5 +├── apache-zest-java--src.tgz.SHA-512 +├── apache-zest-java--src.tgz.asc +├── apache-zest-java--src.zip +├── apache-zest-java--src.zip.MD5 +├── apache-zest-java--src.zip.SHA-512 +└── apache-zest-java--src.zip.asc +---- If any, make the required changes, commit them and iterate. -=== Close the release candidate branch +=== Close the RC branch Once you are satisfied with the produced artifacts, close the release candidate branch: @@ -202,7 +253,7 @@ git flow release finish -RC# ---- -=== Checkout the release candidate tag +=== Checkout the RC tag 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. @@ -212,27 +263,27 @@ git checkout -RC# ---- -=== Build artifacts and distributions +=== Build RC artifacts and distributions [source,shell] ---- -./gradlew -Dversion= clean check buildAll +./gradlew -Dversion= clean check buildAll checkDists ---- -=== Stage maven artifacts +=== Stage RC maven artifacts Stage artifacts to https://repository.apache.org/[repository.apache.org] : [source,shell] ---- -./gradlew -Dversion= release +./gradlew -Dversion= uploadArchives ---- 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 RC 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]: @@ -240,12 +291,10 @@ Upload source and binary distributions, checksums and signatures to https://dist ---- cp zest-java/build/distributions/* zest-dist-dev/ cd zest-dist-dev -svn add --force +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 @@ -323,7 +372,7 @@ git push origin --tags ---- -=== Publish +=== Publish bits 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. @@ -333,28 +382,68 @@ Move the release distributions, checksums and signatures from https://dist.apach ---- mv zest-dist-dev/**.* zest-dist-release/ cd zest-dist-dev -svn add --force +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 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 For mirrors to pick up the new bits. -=== Update the download page +=== Prepare an announcement + +Coordinate a press release with press@apache.org. + + TODO + +You can reuse the release-notes content from the `txt`/`adoc`/`md` files created earlier. + +This annoucement will be used in a veriety of media like emails, websites etc... +Start with a text version and once satisfied produce at least a Markdown version for the website, see below. + + +=== Update the Zest™ website -Edit `zest-svn/site/src/_data/releases.yml` with the new release data. +Generate the documentation and javadoc minisite: + +[source,shell] +---- +cd zest-java +./gradlew -Dversion= archiveJavadocs manuals +---- + +This will automatically put all files into the `zest-svn` website repository. + +Create a new post on the Zest™ website by creating a new Markdown file: + +[source,shell] +---- +cd zest-svn +touch site/src/_posts/YYYY-MM-DD-apache-zest-java-.md +open !$ +---- + +You can reuse the Markdown formatted announcement content. + + +Finally, edit `zest-svn/site/src/_data/releases.yml` with the new release data. Upmost is the latest. -Then rebuild the website: +You can live-preview your changes to the Zest™ website: + +[source,shell] +---- +cd zest-svn +jekyll serve +---- + +Once you are satisfied with the changes, build the production website: [source,shell] ---- @@ -366,7 +455,7 @@ And publish it: [source,shell] ---- -svn add --force +svn add * --force svn commit -m "zest: update website" ---- @@ -385,29 +474,14 @@ Finally, send an announcement to mailto:dev@zest.apache.org[dev@] and mailto:use [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. +The announcement email should contains the release-notes as text, remember they are in the `apache-zest-java--release-notes.txt` file you created earlier. == VOTE fails -=== 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] - -[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 +=== Record failure We keep the release candidate git history. It can be useful for reviewers to have access to it. @@ -424,6 +498,21 @@ git push origin --tags ---- +=== Drop RC 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] + +[source,shell] +---- +cd zest-dist-dev/ +rm "**.*" +svn add * --force +svn commit -m "zest: dropping from dist/dev/zest as the vote failed" +---- + + === Start over If a new RC is to be created, restart the process as described above.