You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@polygene.apache.org by pa...@apache.org on 2015/07/21 12:18:34 UTC
zest-qi4j git commit: ZEST-100 Release process documentation draft
progress
Repository: zest-qi4j
Updated Branches:
refs/heads/develop 2e2bdbe7f -> 83062452f
ZEST-100 Release process documentation draft progress
Project: http://git-wip-us.apache.org/repos/asf/zest-qi4j/repo
Commit: http://git-wip-us.apache.org/repos/asf/zest-qi4j/commit/83062452
Tree: http://git-wip-us.apache.org/repos/asf/zest-qi4j/tree/83062452
Diff: http://git-wip-us.apache.org/repos/asf/zest-qi4j/diff/83062452
Branch: refs/heads/develop
Commit: 83062452fe76449cd210232e2af97753157a6e73
Parents: 2e2bdbe
Author: Paul Merlin <pa...@apache.org>
Authored: Tue Jul 21 12:18:24 2015 +0200
Committer: Paul Merlin <pa...@apache.org>
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-qi4j/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 <<build-system, Build System>> 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 <<build-system, Build System>> 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 <YOUR-PGP-ID>
+----
+
+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) <<build-system,Build System>> 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-VERSION>-release-notes.txt`
+- `apache-zest-java-<RELEASE-VERSION>-release-notes.adoc`
-=== Create a release branch
+We will use them later.
- git flow release start <RELEASE-VERSION>-RC#
+=== Create a release candidate branch
-=== Make a complete check
+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.
+
+[source,shell]
+----
+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
Make a complete build:
- ./gradlew -Dversion=<RELEASE-VERSION> clean check buildAll
+[source,shell]
+----
+./gradlew -Dversion=<RELEASE-VERSION> 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 <RELEASE-VERSION>-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 <RELEASE-VERSION>-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 <RELEASE-VERSION>-RC#
+----
- git checkout <RELEASE-VERSION>-RC#
=== Build artifacts and distributions
- ./gradlew -Dversion=<RELEASE-VERSION> clean check buildAll
+[source,shell]
+----
+./gradlew -Dversion=<RELEASE-VERSION> clean check buildAll
+----
+
=== Stage maven artifacts
Stage artifacts to https://repository.apache.org/[repository.apache.org] :
- ./gradlew -Dversion=<RELEASE-VERSION> release
-
-Close the staging Nexus repository:
+[source,shell]
+----
+./gradlew -Dversion=<RELEASE-VERSION> 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 <RELEASE-VERSION> 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 <RELEASE-VERSION>
+[source,text]
+----
+[VOTE] Release Zest (Java Edition) version <RELEASE-VERSION>
+----
+
+Here is a sample template:
+
+[source,text]
+----
+Dear community,
+
+I am happy to start the VOTE thread for Apache Zest (Java Edition) <RELEASE-VERSION>!
+
+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) <RELEASE-VERSION>.
+
+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) <RELEASE-VERSION>
+[ ] 0 I don't have a strong opinion about this, but I assume it's ok
+[ ] -1 Do not release Apache Zest (Java Edition) <RELEASE-VERSION> 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 <RELEASE-VERSION>
+[source,text]
+----
+[RESULT][VOTE] Release Zest (Java Edition) version <RELEASE-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 <RELEASE-VERSION> <RELEASE-VERSION>-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/*<RELEASE-VERSION>*.* zest-dist-release/
+cd zest-dist-dev
+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 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
@@ -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 <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.
- [ANNOUNCE] Released Zest (Java Edition) version <RELEASE-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 "*<RELEASE-VERSION>*.*"
+svn add --force
+svn commit -m "zest: dropping <RELEASE-VERSION> 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.