README.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.
 ////
 TinkerPop3
 ----------

 image:https://raw.githubusercontent.com/apache/incubator-tinkerpop/master/docs/static/images/tinkerpop3-splash.png[TinkerPop3, link="http://tinkerpop.incubator.apache.org"]

 Documentation
 ~~~~~~~~~~~~~

 * link:http://tinkerpop.incubator.apache.org/[homepage]
 * link:http://tinkerpop.incubator.apache.org/docs/3.0.0-SNAPSHOT/[user documentation]
 * link:http://tinkerpop.incubator.apache.org/javadocs/3.0.0-SNAPSHOT/core/[core javadoc]
 * link:http://tinkerpop.incubator.apache.org/javadocs/3.0.0-SNAPSHOT/full/[full javadoc]

 Building and Testing
 ~~~~~~~~~~~~~~~~~~~~

 TinkerPop requires `Java 1.8.0_40+` for proper building and proper operations.

 * Build Project: `mvn clean install`
 ** Specify specific tests in a TinkerPop Suite to run with the `GREMLIN_TESTS` environment variable, along with the Maven project list argument, e.g.:
 +
 ----
 export GREMLIN_TESTS='org.apache.tinkerpop.gremlin.process.traversal.step.map.PathTest$Traversals,org.apache.tinkerpop.gremlin.process.traversal.PathTest'
 mvn -Dmaven.javadoc.skip=true --projects tinkergraph-gremlin test
 ----
 ** Clean the `.groovy/grapes/org.apache.tinkerpop` directory on build: `mvn clean install -DcleanGrapes`
 ** Turn off "heavy" logging in the "process" tests: `mvn clean install -DargLine="-DmuteTestLogs=true"`
 ** The test suite for `neo4j-gremlin` is disabled by default - to turn it on: `mvn clean install -DincludeNeo4j`
 * Regenerate test data (only necessary given changes to IO classes): `mvn clean install -Dio` from `tinkergraph-gremlin` directory
 ** If there are changes to the Gryo format, it may be necessary to generate the Grateful Dead dataset from GraphSON (see `IoDataGenerationTest.shouldWriteGratefulDead`)
 * Check license headers are present: `mvn apache-rat:check`
 * Build AsciiDocs (Hadoop must be running): `bin/process-docs.sh`
 ** Process a single AsciiDoc file: +pass:[docs/preprocessor/preprocess-file.sh `pwd`/gremlin-console/target/apache-gremlin-console-*-standalone `pwd`/docs/src/xyz.asciidoc]+
 * Build JavaDocs: `mvn process-resources -Djavadoc`
 * Check for Apache License headers: `mvn apache-rat:check`
 * Check for newer dependencies: `mvn versions:display-dependency-updates` or `mvn versions:display-plugin-updates`
 * Deploy JavaDocs/AsciiDocs: `bin/publish-docs.sh svn-username`
 * Integration Tests: `mvn verify -DskipIntegrationTests=false`
 * Performance Tests: `mvn verify -DskipPerformanceTests=false`

 IDE Setup
 ^^^^^^^^^

 This section refers specifically to setup within Intellij.  TinkerPop has a module called `gremlin-shaded` which contains shaded dependencies for some libraries that are widely used and tend to introduce conflicts.  To ensure that Intellij properly interprets this module after importing the Maven `pom.xml` perform the following steps:

 . Build `gremlin-shaded` from the command line with `mvn clean install`.
 . Right-click on the `gremlin-shaded` module in the project viewer of Intellij and select "Remove module".
 . In the "Maven Projects" Tool window and click the tool button for "Reimport All Maven projects" (go to `View | Tool Windows | Maven Projects` on the main menu if this panel is not activated).
 . At this point it should be possible to compile and run the tests within Intellij, but in the worst case, use `File | Invalidate Caches/Restart` to ensure that indices properly rebuild.

 Note that it maybe be necessary to re-execute these steps if the `gremlin-shaded` `pom.xml` is ever updated.

 Developers working on the `neo4j-gremlin` module should enabled the `include-neo4j` Maven profile in Intellij.  This will ensure that tests will properly execute within the IDE.

 If Intellij complains about "duplicate sources" for the Groovy files when attempting to compile/run tests, then install the link:http://plugins.jetbrains.com/plugin/7442?pr=idea[GMavenPlus Intellij plugin].

 Get Started
 ~~~~~~~~~~~

 [source,bash]
 ----
 $ bin/gremlin.sh

          \,,,/
          (o o)
 -----oOOo-(3)-oOOo-----
 gremlin>
 ----

 Issue Tracker Conventions
 ~~~~~~~~~~~~~~~~~~~~~~~~~

 TinkerPop3 uses Apache JIRA as its link:https://issues.apache.org/jira/browse/TINKERPOP3[issue tracker].  JIRA is a very robust piece of software with many options and configurations.  To simplify usage and ensure consistency across issues, the following conventions should be adhered to:

 * An issue's "status" should generally be in one of two states: `open` or `closed` (`reopened` is equivalent to `open` for our purposes).
 ** An `open` issue is newly created, under consideration or otherwise in progress.
 ** A `closed` issue is completed for purposes of release (i.e. code, testing, and documentation complete).
 ** Issues in a `resolved` state should immediately be evaluated for movement to `closed` - issue become `resolved` by those who don't have the permissions to `close`.
 * An issue's "type" should be one of two options: `bug` or `improvement`.
 ** A `bug` has a very specific meaning, referring to an error that prevents usage of TinkerPop AND does not have a reasonable workaround.  Given that definition, a `bug` should generally have very high priority for a fix.
 ** Everything else is an `improvement` in the sense that any other work is an enhancement to the current codebase.
 * The "component" should be representative of the primary area of code that it applies to and all issues should have this property set.
 * Issues are not assigned "labels".
 * Until there is an official release "affected version" should be left empty.

 Release Process
 ~~~~~~~~~~~~~~~

 . `mvn clean install`
 .. `mvn verify -DskipIntegrationTests=false`
 .. `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` with release date
 . `bin/bump.sh "version"` 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`
 . `bin/publish-docs.sh <username>`
 . `mvn install -Papache-release -DcreateChecksum=true -Dmaven.test.skip=true`
 . 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` and `for f in *.zip*; do  mv "$f" "apache-$f"; done`
 .. `cd ..; svn add x.y.z/; svn ci -m "TinkerPop x.y.z release"`
 . Submit for `[VOTE]` at `general@incubator.apache.org` (see email template below).
 . *Wait for vote acceptance* (72 hours).
 . `mvn clean install -Dmaven.test.skip=true; bin/process-docs.sh` - rebuild source and docs of tagged release
 . `mvn deploy -Papache-release -DcreateChecksum=true -Dmaven.test.skip=true`- deploy signed artifacts with checksums to Apache Nexus
 . Review and close the staging repository (Apache Nexus at link:https://repository.apache.org/[https://repository.apache.org/])
 . `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`
 . `ls dev/x.y.z/ | grep '\-\(distribution\|source\-release\)\.zip' | sed -e 's/\(^[^ ]*\)-distribution\([^ ]*\)/cp dev\/x.y.z\/\0 release\/x.y.z\/\1-bin\2/' -e 's/\(^[^ ]*\)-source-release\([^ ]*\)/cp dev\/x.y.z\/\0 release\/x.y.z\/\1-src\2/' | /bin/sh`
 . `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/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.
	////
	TinkerPop3
	----------

	image:https://raw.githubusercontent.com/apache/incubator-tinkerpop/master/docs/static/images/tinkerpop3-splash.png[TinkerPop3, link="http://tinkerpop.incubator.apache.org"]

	Documentation
	~~~~~~~~~~~~~

	* link:http://tinkerpop.incubator.apache.org/[homepage]
	* link:http://tinkerpop.incubator.apache.org/docs/3.0.0-SNAPSHOT/[user documentation]
	* link:http://tinkerpop.incubator.apache.org/javadocs/3.0.0-SNAPSHOT/core/[core javadoc]
	* link:http://tinkerpop.incubator.apache.org/javadocs/3.0.0-SNAPSHOT/full/[full javadoc]

	Building and Testing
	~~~~~~~~~~~~~~~~~~~~

	TinkerPop requires `Java 1.8.0_40+` for proper building and proper operations.

	* Build Project: `mvn clean install`
	** Specify specific tests in a TinkerPop Suite to run with the `GREMLIN_TESTS` environment variable, along with the Maven project list argument, e.g.:
	+
	----
	export GREMLIN_TESTS='org.apache.tinkerpop.gremlin.process.traversal.step.map.PathTest$Traversals,org.apache.tinkerpop.gremlin.process.traversal.PathTest'
	mvn -Dmaven.javadoc.skip=true --projects tinkergraph-gremlin test
	----
	** Clean the `.groovy/grapes/org.apache.tinkerpop` directory on build: `mvn clean install -DcleanGrapes`
	** Turn off "heavy" logging in the "process" tests: `mvn clean install -DargLine="-DmuteTestLogs=true"`
	** The test suite for `neo4j-gremlin` is disabled by default - to turn it on: `mvn clean install -DincludeNeo4j`
	* Regenerate test data (only necessary given changes to IO classes): `mvn clean install -Dio` from `tinkergraph-gremlin` directory
	** If there are changes to the Gryo format, it may be necessary to generate the Grateful Dead dataset from GraphSON (see `IoDataGenerationTest.shouldWriteGratefulDead`)
	* Check license headers are present: `mvn apache-rat:check`
	* Build AsciiDocs (Hadoop must be running): `bin/process-docs.sh`
	** Process a single AsciiDoc file: +pass:[docs/preprocessor/preprocess-file.sh `pwd`/gremlin-console/target/apache-gremlin-console-*-standalone `pwd`/docs/src/xyz.asciidoc]+
	* Build JavaDocs: `mvn process-resources -Djavadoc`
	* Check for Apache License headers: `mvn apache-rat:check`
	* Check for newer dependencies: `mvn versions:display-dependency-updates` or `mvn versions:display-plugin-updates`
	* Deploy JavaDocs/AsciiDocs: `bin/publish-docs.sh svn-username`
	* Integration Tests: `mvn verify -DskipIntegrationTests=false`
	* Performance Tests: `mvn verify -DskipPerformanceTests=false`

	IDE Setup
	^^^^^^^^^

	This section refers specifically to setup within Intellij. TinkerPop has a module called `gremlin-shaded` which contains shaded dependencies for some libraries that are widely used and tend to introduce conflicts. To ensure that Intellij properly interprets this module after importing the Maven `pom.xml` perform the following steps:

	. Build `gremlin-shaded` from the command line with `mvn clean install`.
	. Right-click on the `gremlin-shaded` module in the project viewer of Intellij and select "Remove module".
	. In the "Maven Projects" Tool window and click the tool button for "Reimport All Maven projects" (go to `View \| Tool Windows \| Maven Projects` on the main menu if this panel is not activated).
	. At this point it should be possible to compile and run the tests within Intellij, but in the worst case, use `File \| Invalidate Caches/Restart` to ensure that indices properly rebuild.

	Note that it maybe be necessary to re-execute these steps if the `gremlin-shaded` `pom.xml` is ever updated.

	Developers working on the `neo4j-gremlin` module should enabled the `include-neo4j` Maven profile in Intellij. This will ensure that tests will properly execute within the IDE.

	If Intellij complains about "duplicate sources" for the Groovy files when attempting to compile/run tests, then install the link:http://plugins.jetbrains.com/plugin/7442?pr=idea[GMavenPlus Intellij plugin].

	Get Started
	~~~~~~~~~~~

	[source,bash]
	----
	$ bin/gremlin.sh

	\,,,/
	(o o)
	-----oOOo-(3)-oOOo-----
	gremlin>
	----

	Issue Tracker Conventions
	~~~~~~~~~~~~~~~~~~~~~~~~~

	TinkerPop3 uses Apache JIRA as its link:https://issues.apache.org/jira/browse/TINKERPOP3[issue tracker]. JIRA is a very robust piece of software with many options and configurations. To simplify usage and ensure consistency across issues, the following conventions should be adhered to:

	* An issue's "status" should generally be in one of two states: `open` or `closed` (`reopened` is equivalent to `open` for our purposes).
	** An `open` issue is newly created, under consideration or otherwise in progress.
	** A `closed` issue is completed for purposes of release (i.e. code, testing, and documentation complete).
	** Issues in a `resolved` state should immediately be evaluated for movement to `closed` - issue become `resolved` by those who don't have the permissions to `close`.
	* An issue's "type" should be one of two options: `bug` or `improvement`.
	** A `bug` has a very specific meaning, referring to an error that prevents usage of TinkerPop AND does not have a reasonable workaround. Given that definition, a `bug` should generally have very high priority for a fix.
	** Everything else is an `improvement` in the sense that any other work is an enhancement to the current codebase.
	* The "component" should be representative of the primary area of code that it applies to and all issues should have this property set.
	* Issues are not assigned "labels".
	* Until there is an official release "affected version" should be left empty.

	Release Process
	~~~~~~~~~~~~~~~

	. `mvn clean install`
	.. `mvn verify -DskipIntegrationTests=false`
	.. `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` with release date
	. `bin/bump.sh "version"` 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`
	. `bin/publish-docs.sh <username>`
	. `mvn install -Papache-release -DcreateChecksum=true -Dmaven.test.skip=true`
	. 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` and `for f in .zip; do mv "$f" "apache-$f"; done`
	.. `cd ..; svn add x.y.z/; svn ci -m "TinkerPop x.y.z release"`
	. Submit for `[VOTE]` at `general@incubator.apache.org` (see email template below).
	. Wait for vote acceptance (72 hours).
	. `mvn clean install -Dmaven.test.skip=true; bin/process-docs.sh` - rebuild source and docs of tagged release
	. `mvn deploy -Papache-release -DcreateChecksum=true -Dmaven.test.skip=true`- deploy signed artifacts with checksums to Apache Nexus
	. Review and close the staging repository (Apache Nexus at link:https://repository.apache.org/[https://repository.apache.org/])
	. `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`
	. `ls dev/x.y.z/ \| grep '\-\(distribution\\|source\-release\)\.zip' \| sed -e 's/\(^[^ ]\)-distribution\([^ ]\)/cp dev\/x.y.z\/\0 release\/x.y.z\/\1-bin\2/' -e 's/\(^[^ ]\)-source-release\([^ ]\)/cp dev\/x.y.z\/\0 release\/x.y.z\/\1-src\2/' \| /bin/sh`
	. `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/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>
	```