docs/src/developer-release.asciidoc - tinkerpop - Git at Google

 ////
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 ////
 Release Process
 ===============

 This document describes the steps required to release a version of TinkerPop.  The release is handled by a "release
 manager" (a committer fulfills this role), who ensures that the steps in this document are executed. The process is
 multi-phased and can therefore take several weeks to complete given the time needed for Apache voting and community
 feedback.  Once a release point has been identified, the following phases represent the flow of "release":

 * Pre-flight check.
 * Optionally, produce a release candidate for community feedback.
 * Submit the official release for PMC vote.
 * Submit the official release for Incubator vote.
 * Release and promote.

 Pre-flight Check
 ----------------

 The "pre-flight check" is a list of things performed by the release manager during the weeks leading up to a scheduled
 day to release.  These checks will help to ensure that that release day goes smoothly by identifying problems up early
 and communicating with other members of the community.

 . Fourteen days before release, issue an email to the dev mailing list to remind the community of the pending release.
 .. Note any important issues open in JIRA in that post.
 .. Request review and update of the "upgrade documentation" and CHANGELOG.
 . Seven days before release, announce the code freeze on the dev mailing list to remind the community that the branch
 under release is protected. Tweaks to documentation and other odds and ends related to release are still allowed
 during this period.
 . At some point during the week:
 .. Run the full integration test suite: `mvn clean install -DskipIntegrationTests=false -DincludeNeo4j`
 .. Deploy a final SNAPSHOT to the snapshot repository.
 .. Review LICENSE and NOTICE files to make sure that no <<dependencies,changes are needed>>.
 .. Review javadoc filters on the "Core API" docs to be sure nothing needs to change.
 . When all documentation changes are in place, use `bin/publish-docs.sh` to deploy a final `SNAPSHOT` representation
 of the docs and thus validate that there are no issues with the documentation generation process. Request review
 of the published documentation on the dev mailing list.

 Release Candidate
 -----------------

 A release candidate is an unofficial release that is represented by a tagged version in the Git repository.  It is
 offered in cases where there is significant change in a particular version and the potential for upgrades and problems
 might be high.

 . `mvn clean install -DincludeNeo4j`
 .. `mvn verify -DskipIntegrationTests=false -DincludeNeo4j`
 .. `mvn verify -DskipPerformanceTests=false`
 . `bin/publish-docs.sh <username>` - note that under a release candidate the documentation is published as SNAPSHOT
 . `mvn versions:set -DnewVersion=x.y.z -DgenerateBackupPoms=false` to update the project files to reference a non-SNAPSHOT version
 . `git diff` and review the updated files (expect all `pom.xml` files and this README)
 . `git commit -a -m "TinkerPop x.y.z release"` and `git push`
 . `git tag -a -m "TinkerPop x.y.z release" x.y.z` and `git push --tags`
 . `mvn clean install -Dmaven.test.skip=true`
 . `mvn versions:set -DnewVersion=x.y.z-SNAPSHOT -DgenerateBackupPoms=false` to go back to SNAPSHOT
 . `git commit -a -m "Returned to x.y.z-SNAPSHOT"` and `git push`
 . Announce the release candidate to `dev` mailing list and await feedback
 . Repeat as required or proceed to the next phase

 PMC Vote
 --------

 A positive vote for a particular release from the TinkerPop PMC is required to move to the following phase.

 . `mvn clean install`
 .. `mvn verify -DskipIntegrationTests=false -DincludeNeo4j`
 .. `mvn verify -DskipPerformanceTests=false`
 . Perform manual tests:
 .. Execute `:remote connect conf/remote.yaml` and send some requests to a running Gremlin Server instance.
 .. Execute `:?` to display the help in the Console.
 . Update `CHANGELOG.asciidoc`:
 .. Update the release date
 .. Generate the JIRA release notes report for the current version and append them to the `CHANGELOG.asciidoc`
 .. Organize "breaking" changes to be clearly marked (use JIRA and the "breaking" label to identify those)
 . Update "upgrade documentation":
 .. Update the release date.
 .. Update the link to CHANGELOG.asciidoc
 . `mvn versions:set -DnewVersion=x.y.z -DgenerateBackupPoms=false` to update project files to reference the non-SNAPSHOT version
 . `git diff` and review the updated files (expect all `pom.xml` files and this README)
 . `git commit -a -m "TinkerPop x.y.z release"` and `git push`
 . `git tag -a -m "TinkerPop x.y.z release" x.y.z` and `git push --tags`
 . `mvn clean install -Dmaven.test.skip=true` - need to build first so that the right version of the console is used with `bin/publish-docs.sh`
 . `bin/publish-docs.sh <username>`
 . `mvn install -Papache-release -Djavadoc -DcreateChecksum=true -Dmaven.test.skip=true`
 . `mvn deploy -Papache-release -DcreateChecksum=true -Dmaven.test.skip=true`- deploy signed artifacts with checksums to link:https://repository.apache.org/[Apache Nexus]. Review (artifacts versions, file sizes, anything that might be out of place - request another committer to review as well) but do NOT close/release the staging repository at this time.
 . Review generated artifacts to be sure they have both javadocs and asciidocs present
 . Upload artifacts to `https://dist.apache.org/repos/dist/dev/incubator/tinkerpop` for `[VOTE]` review.
 .. `svn co --depth empty https://dist.apache.org/repos/dist/dev/incubator/tinkerpop/ dev` and `mkdir dev/x.y.z`
 .. `cp ~/.m2/repository/org/apache/tinkerpop/gremlin-console/x.y.z/gremlin-console-x.y.z-distribution.zip* dev/x.y.z`
 .. `cp ~/.m2/repository/org/apache/tinkerpop/gremlin-server/x.y.z/gremlin-server-x.y.z-distribution.zip* dev/x.y.z`
 .. `cp ~/.m2/repository/org/apache/tinkerpop/tinkerpop/x.y.z/tinkerpop-x.y.z-source-release.zip* dev/x.y.z`
 .. `cd dev/x.y.z`
 .. pass:[<code>ls * | xargs -n1 -I {} echo "mv apache-{} {}" | sed -e 's/distribution/bin/' -e 's/source-release/src/' -e s'/^\(.*\) \(.*\) \(.*\)$/\1 \3 \2/' | /bin/bash</code>]
 .. `cd ..; svn add x.y.z/; svn ci -m "TinkerPop x.y.z release"`
 . Execute `bin/validate-distribution.sh` and any other relevant testing.
 . Perform JIRA administration tasks:
 .. "Release" the current version and set the "release date"
 .. If there is to be a follow on release in the current line of code, create that new version specifying the "start date"
 .. Migrate the "Affected Version" of all unresolved issues to the next lowest common denominator version - if version 3.0.1 released then all 3.0.0 issues should move forward to 3.0.1 as they now "affect" that latest release
 . Submit for `[VOTE]` at `dev@tinkerpop.incubator.apache.org` (see email template below)
 . *Wait for vote acceptance* (72 hours)

 Incubator Vote
 --------------

 A positive vote for a particular release from the Apache Incubator is required to move to the following phase.

 . Submit for `[VOTE]` at `general@incubator.apache.org` (see email template below)
 .. Include the vote tally: "Apache TinkerPop (http://tinkerpop.incubator.apache.org/) would like to release TinkerPop x.y.z. We had a dev@ VOTE which resulted in a tally of +1 (3), 0 (0), and -1 (0). We now present our artifacts for vote by Incubator."
 . *Wait for vote acceptance* (72 hours)

 Release & Promote
 -----------------

 . Close the staging repository at link:https://repository.apache.org/[Apache Nexus]) and then release.
 . `svn co --depth empty https://dist.apache.org/repos/dist/dev/incubator/tinkerpop dev; svn up dev/x.y.z`
 . `svn co --depth empty https://dist.apache.org/repos/dist/release/incubator/tinkerpop release; mkdir release/x.y.z`
 . `cd release; svn add x.y.z/; svn ci -m "TinkerPop x.y.z release"`
 . Update homepage with references to latest distribution and to other internal links elsewhere on the page.
 . Wait for Apache Central to sync the jars and src (link:http://repo1.maven.org/maven2/org/apache/tinkerpop/tinkerpop/[http://repo1.maven.org/maven2/org/apache/tinkerpop/tinkerpop/]).
 . Announce release on `dev@`/`gremlin-users@` mailing lists and tweet from `@apachetinkerpop`

 Example `[VOTE]` email:

 ```
 [VOTE] TinkerPop x.y.z Release

 Hello,

 The release artifacts can be found at this location:
 	https://dist.apache.org/repos/dist/dev/incubator/tinkerpop/x.y.z/

 The source distribution is provided by:
 	apache-tinkerpop-x.y.z-source-release.zip

 Two binary distributions are provided for user convenience:
 	apache-gremlin-console-x.y.z-distribution.zip
 	apache-gremlin-server-x.y.z-distribution.zip

 The online docs can be found here:
 	http://tinkerpop.incubator.apache.org/docs/x.y.z/ (user docs)
 	http://tinkerpop.incubator.apache.org/docs/x.y.z/upgrade.html (upgrade docs)
 	http://tinkerpop.incubator.apache.org/javadocs/x.y.z/core/ (core javadoc)
 	http://tinkerpop.incubator.apache.org/javadocs/x.y.z/full/ (full javadoc)

 The tag in Apache Git can be found here:
 	https://git-wip-us.apache.org/repos/asf?p=incubator-tinkerpop.git;...

 The release notes are available here:
 	https://github.com/apache/incubator-tinkerpop/blob/master/CHANGELOG.asciidoc#...

 The [VOTE] will be open for the next 72 hours --- closing <DayOfTheWeek> (<Month> <Day> <Year>) at <Time> <TimeZone>.

 My vote is +1.

 Thank you very much,
 <TinkerPop Committer Name>
 ```
	////
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	////
	Release Process
	===============

	This document describes the steps required to release a version of TinkerPop. The release is handled by a "release
	manager" (a committer fulfills this role), who ensures that the steps in this document are executed. The process is
	multi-phased and can therefore take several weeks to complete given the time needed for Apache voting and community
	feedback. Once a release point has been identified, the following phases represent the flow of "release":

	* Pre-flight check.
	* Optionally, produce a release candidate for community feedback.
	* Submit the official release for PMC vote.
	* Submit the official release for Incubator vote.
	* Release and promote.

	Pre-flight Check
	----------------

	The "pre-flight check" is a list of things performed by the release manager during the weeks leading up to a scheduled
	day to release. These checks will help to ensure that that release day goes smoothly by identifying problems up early
	and communicating with other members of the community.

	. Fourteen days before release, issue an email to the dev mailing list to remind the community of the pending release.
	.. Note any important issues open in JIRA in that post.
	.. Request review and update of the "upgrade documentation" and CHANGELOG.
	. Seven days before release, announce the code freeze on the dev mailing list to remind the community that the branch
	under release is protected. Tweaks to documentation and other odds and ends related to release are still allowed
	during this period.
	. At some point during the week:
	.. Run the full integration test suite: `mvn clean install -DskipIntegrationTests=false -DincludeNeo4j`
	.. Deploy a final SNAPSHOT to the snapshot repository.
	.. Review LICENSE and NOTICE files to make sure that no <<dependencies,changes are needed>>.
	.. Review javadoc filters on the "Core API" docs to be sure nothing needs to change.
	. When all documentation changes are in place, use `bin/publish-docs.sh` to deploy a final `SNAPSHOT` representation
	of the docs and thus validate that there are no issues with the documentation generation process. Request review
	of the published documentation on the dev mailing list.

	Release Candidate
	-----------------

	A release candidate is an unofficial release that is represented by a tagged version in the Git repository. It is
	offered in cases where there is significant change in a particular version and the potential for upgrades and problems
	might be high.

	. `mvn clean install -DincludeNeo4j`
	.. `mvn verify -DskipIntegrationTests=false -DincludeNeo4j`
	.. `mvn verify -DskipPerformanceTests=false`
	. `bin/publish-docs.sh <username>` - note that under a release candidate the documentation is published as SNAPSHOT
	. `mvn versions:set -DnewVersion=x.y.z -DgenerateBackupPoms=false` to update the project files to reference a non-SNAPSHOT version
	. `git diff` and review the updated files (expect all `pom.xml` files and this README)
	. `git commit -a -m "TinkerPop x.y.z release"` and `git push`
	. `git tag -a -m "TinkerPop x.y.z release" x.y.z` and `git push --tags`
	. `mvn clean install -Dmaven.test.skip=true`
	. `mvn versions:set -DnewVersion=x.y.z-SNAPSHOT -DgenerateBackupPoms=false` to go back to SNAPSHOT
	. `git commit -a -m "Returned to x.y.z-SNAPSHOT"` and `git push`
	. Announce the release candidate to `dev` mailing list and await feedback
	. Repeat as required or proceed to the next phase

	PMC Vote
	--------

	A positive vote for a particular release from the TinkerPop PMC is required to move to the following phase.

	. `mvn clean install`
	.. `mvn verify -DskipIntegrationTests=false -DincludeNeo4j`
	.. `mvn verify -DskipPerformanceTests=false`
	. Perform manual tests:
	.. Execute `:remote connect conf/remote.yaml` and send some requests to a running Gremlin Server instance.
	.. Execute `:?` to display the help in the Console.
	. Update `CHANGELOG.asciidoc`:
	.. Update the release date
	.. Generate the JIRA release notes report for the current version and append them to the `CHANGELOG.asciidoc`
	.. Organize "breaking" changes to be clearly marked (use JIRA and the "breaking" label to identify those)
	. Update "upgrade documentation":
	.. Update the release date.
	.. Update the link to CHANGELOG.asciidoc
	. `mvn versions:set -DnewVersion=x.y.z -DgenerateBackupPoms=false` to update project files to reference the non-SNAPSHOT version
	. `git diff` and review the updated files (expect all `pom.xml` files and this README)
	. `git commit -a -m "TinkerPop x.y.z release"` and `git push`
	. `git tag -a -m "TinkerPop x.y.z release" x.y.z` and `git push --tags`
	. `mvn clean install -Dmaven.test.skip=true` - need to build first so that the right version of the console is used with `bin/publish-docs.sh`
	. `bin/publish-docs.sh <username>`
	. `mvn install -Papache-release -Djavadoc -DcreateChecksum=true -Dmaven.test.skip=true`
	. `mvn deploy -Papache-release -DcreateChecksum=true -Dmaven.test.skip=true`- deploy signed artifacts with checksums to link:https://repository.apache.org/[Apache Nexus]. Review (artifacts versions, file sizes, anything that might be out of place - request another committer to review as well) but do NOT close/release the staging repository at this time.
	. Review generated artifacts to be sure they have both javadocs and asciidocs present
	. Upload artifacts to `https://dist.apache.org/repos/dist/dev/incubator/tinkerpop` for `[VOTE]` review.
	.. `svn co --depth empty https://dist.apache.org/repos/dist/dev/incubator/tinkerpop/ dev` and `mkdir dev/x.y.z`
	.. `cp ~/.m2/repository/org/apache/tinkerpop/gremlin-console/x.y.z/gremlin-console-x.y.z-distribution.zip* dev/x.y.z`
	.. `cp ~/.m2/repository/org/apache/tinkerpop/gremlin-server/x.y.z/gremlin-server-x.y.z-distribution.zip* dev/x.y.z`
	.. `cp ~/.m2/repository/org/apache/tinkerpop/tinkerpop/x.y.z/tinkerpop-x.y.z-source-release.zip* dev/x.y.z`
	.. `cd dev/x.y.z`
	.. pass:[<code>ls * \| xargs -n1 -I {} echo "mv apache-{} {}" \| sed -e 's/distribution/bin/' -e 's/source-release/src/' -e s'/^\(.\) \(.\) \(.*\)$/\1 \3 \2/' \| /bin/bash</code>]
	.. `cd ..; svn add x.y.z/; svn ci -m "TinkerPop x.y.z release"`
	. Execute `bin/validate-distribution.sh` and any other relevant testing.
	. Perform JIRA administration tasks:
	.. "Release" the current version and set the "release date"
	.. If there is to be a follow on release in the current line of code, create that new version specifying the "start date"
	.. Migrate the "Affected Version" of all unresolved issues to the next lowest common denominator version - if version 3.0.1 released then all 3.0.0 issues should move forward to 3.0.1 as they now "affect" that latest release
	. Submit for `[VOTE]` at `dev@tinkerpop.incubator.apache.org` (see email template below)
	. Wait for vote acceptance (72 hours)

	Incubator Vote
	--------------

	A positive vote for a particular release from the Apache Incubator is required to move to the following phase.

	. Submit for `[VOTE]` at `general@incubator.apache.org` (see email template below)
	.. Include the vote tally: "Apache TinkerPop (http://tinkerpop.incubator.apache.org/) would like to release TinkerPop x.y.z. We had a dev@ VOTE which resulted in a tally of +1 (3), 0 (0), and -1 (0). We now present our artifacts for vote by Incubator."
	. Wait for vote acceptance (72 hours)

	Release & Promote
	-----------------

	. Close the staging repository at link:https://repository.apache.org/[Apache Nexus]) and then release.
	. `svn co --depth empty https://dist.apache.org/repos/dist/dev/incubator/tinkerpop dev; svn up dev/x.y.z`
	. `svn co --depth empty https://dist.apache.org/repos/dist/release/incubator/tinkerpop release; mkdir release/x.y.z`
	. `cd release; svn add x.y.z/; svn ci -m "TinkerPop x.y.z release"`
	. Update homepage with references to latest distribution and to other internal links elsewhere on the page.
	. Wait for Apache Central to sync the jars and src (link:http://repo1.maven.org/maven2/org/apache/tinkerpop/tinkerpop/[http://repo1.maven.org/maven2/org/apache/tinkerpop/tinkerpop/]).
	. Announce release on `dev@`/`gremlin-users@` mailing lists and tweet from `@apachetinkerpop`

	Example `[VOTE]` email:

	```
	[VOTE] TinkerPop x.y.z Release

	Hello,

	The release artifacts can be found at this location:
	https://dist.apache.org/repos/dist/dev/incubator/tinkerpop/x.y.z/

	The source distribution is provided by:
	apache-tinkerpop-x.y.z-source-release.zip

	Two binary distributions are provided for user convenience:
	apache-gremlin-console-x.y.z-distribution.zip
	apache-gremlin-server-x.y.z-distribution.zip

	The online docs can be found here:
	http://tinkerpop.incubator.apache.org/docs/x.y.z/ (user docs)
	http://tinkerpop.incubator.apache.org/docs/x.y.z/upgrade.html (upgrade docs)
	http://tinkerpop.incubator.apache.org/javadocs/x.y.z/core/ (core javadoc)
	http://tinkerpop.incubator.apache.org/javadocs/x.y.z/full/ (full javadoc)

	The tag in Apache Git can be found here:
	https://git-wip-us.apache.org/repos/asf?p=incubator-tinkerpop.git;...

	The release notes are available here:
	https://github.com/apache/incubator-tinkerpop/blob/master/CHANGELOG.asciidoc#...

	The [VOTE] will be open for the next 72 hours --- closing <DayOfTheWeek> (<Month> <Day> <Year>) at <Time> <TimeZone>.

	My vote is +1.

	Thank you very much,
	<TinkerPop Committer Name>
	```