polygene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From paulmer...@apache.org
Subject [17/50] zest-java git commit: ZEST-100 Release process documentation draft progress
Date Tue, 28 Jul 2015 12:55:14 GMT
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 <paulmerlin@apache.org>
Authored: Tue Jul 21 17:51:44 2015 +0200
Committer: Paul Merlin <paulmerlin@apache.org>
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 <<build-system,
Build Sy
 
 
 // TODOs
-// - put the release notes on the website
 // - review commands for managing dev/release dist uploads, they may be too greedy
 
 
@@ -79,7 +78,7 @@ Ensure you can test, build and sign Zest, including artifact signing, see
the <<
 
 === 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.
+Moreover, you will need to have a valid http://jekyllrb.com/[Jekyll] installation as the
Apache Zest™ https://zest.apache.org/[website] is generated using it.
 
 
 === Setup git flow
@@ -149,24 +148,52 @@ They can be resolved by:
 See the https://issues.apache.org/jira/browse/ZEST[ZEST] project on JIRA.
 
 
-=== Prepare Release Notes
+=== Prepare Release-Notes
 
-Apache Zest™ release notes are generated from JIRA issues.
+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.
+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.
 
-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.
+JIRA can produces release-notes as HTML or plain-text.
+Set it up to generate plain-text release-notes.
 
-Prepare the two following files:
+We will need these in several formats.
+Starting from the plain-text one we will generate the others.
 
-- `apache-zest-java-<RELEASE-VERSION>-release-notes.txt`
-- `apache-zest-java-<RELEASE-VERSION>-release-notes.adoc`
+First save the text-plain release-notes in a file named `apache-zest-java-<RELEASE-VERSION>-release-notes.txt`.
+
+Convert to Asciidoc:
+
+[source,shell]
+----
+cat apache-zest-java-<RELEASE-VERSION>-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-VERSION>-release-notes.adoc
+----
+
+Convert to Markdown:
+
+[source,shell]
+----
+cat apache-zest-java-<RELEASE-VERSION>-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-VERSION>-release-notes.md
+----
+
+You should then have the two following files:
+
+[source,shell]
+----
+.
+├── apache-zest-java-<RELEASE-VERSION>-release-notes.txt
+├── apache-zest-java-<RELEASE-VERSION>-release-notes.adoc
+└── apache-zest-java-<RELEASE-VERSION>-release-notes.md
+----
 
 We will use them later.
 
 
-=== Create a release candidate branch
+=== Create a RC branch
 
 We use `<RELEASE-VERSION>-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 <RELEASE-VERSION>-RC#
 This will eventually generates a `<RELEASE-VERSION>-RC#` tag that we will rename to
`<RELEASE-VERSION>` 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=<RELEASE-VERSION> clean check buildAll
+./gradlew -Dversion=<RELEASE-VERSION> -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-<RELEASE-VERSION>-bin.tgz
+├── apache-zest-java-<RELEASE-VERSION>-bin.tgz.MD5
+├── apache-zest-java-<RELEASE-VERSION>-bin.tgz.SHA-512
+├── apache-zest-java-<RELEASE-VERSION>-bin.tgz.asc
+├── apache-zest-java-<RELEASE-VERSION>-bin.zip
+├── apache-zest-java-<RELEASE-VERSION>-bin.zip.MD5
+├── apache-zest-java-<RELEASE-VERSION>-bin.zip.SHA-512
+├── apache-zest-java-<RELEASE-VERSION>-bin.zip.asc
+├── apache-zest-java-<RELEASE-VERSION>-src.tgz
+├── apache-zest-java-<RELEASE-VERSION>-src.tgz.MD5
+├── apache-zest-java-<RELEASE-VERSION>-src.tgz.SHA-512
+├── apache-zest-java-<RELEASE-VERSION>-src.tgz.asc
+├── apache-zest-java-<RELEASE-VERSION>-src.zip
+├── apache-zest-java-<RELEASE-VERSION>-src.zip.MD5
+├── apache-zest-java-<RELEASE-VERSION>-src.zip.SHA-512
+└── apache-zest-java-<RELEASE-VERSION>-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 <RELEASE-VERSION>-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 <RELEASE-VERSION>-RC#
 ----
 
 
-=== Build artifacts and distributions
+=== Build RC artifacts and distributions
 
 [source,shell]
 ----
-./gradlew -Dversion=<RELEASE-VERSION> clean check buildAll
+./gradlew -Dversion=<RELEASE-VERSION> 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-VERSION> release
+./gradlew -Dversion=<RELEASE-VERSION> 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 <RELEASE-VERSION> 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/*<RELEASE-VERSION>*.* zest-dist-release/
 cd zest-dist-dev
-svn add --force
+svn add * --force
 svn commit -m "zest: removing <RELEASE-VERSION> from dist/dev/zest as the VOTE passed"
 cd ..
 cd zest-dist-release
-svn add --force
+svn add * --force
 svn commit -m "zest: upload <RELEASE-VERSION> 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=<RELEASE-VERSION> 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-<RELEASE-VERSION>.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 <RELEASE-VERSION>
 ----
 
-The announcement email should contains the release notes as text, remember you prepared a
`apache-zest-java-<RELEASE-VERSION>-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-VERSION>-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 "*<RELEASE-VERSION>*.*"
-svn add --force
-svn commit -m "zest: dropping <RELEASE-VERSION> 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 "*<RELEASE-VERSION>*.*"
+svn add * --force
+svn commit -m "zest: dropping <RELEASE-VERSION> from dist/dev/zest as the vote failed"
+----
+
+
 === Start over
 
 If a new RC is to be created, restart the process as described above.


Mime
View raw message