TinkerPop3

Documentation

• homepage

• user documentation

• core javadoc

• 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 and ZooKeeper must be running): bin/process-docs.sh

  • Process a single AsciiDoc file: 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

  • Execute with the -DincludeNeo4j option to include transactional tests.

• 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:

1. Build gremlin-shaded from the command line with mvn clean install.

2. Right-click on the gremlin-shaded module in the project viewer of Intellij and select "Remove module".

3. 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).

4. 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 GMavenPlus Intellij plugin.

Get Started

$ bin/gremlin.sh

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

Issue Tracker Conventions

TinkerPop3 uses Apache JIRA as its 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

1. mvn clean install

   1. mvn verify -DskipIntegrationTests=false -DincludeNeo4j

   2. mvn verify -DskipPerformanceTests=false

2. Perform manual tests:

   1. Execute :remote connect conf/remote.yaml and send some requests to a running Gremlin Server instance.

   2. Execute :? to display the help in the Console.

3. Update CHANGELOG.asciidoc with release date

4. bin/bump.sh "version" to update project files to reference the non-SNAPSHOT version

5. git diff and review the updated files (expect all pom.xml files and this README)

6. git commit -a -m "TinkerPop x.y.z release" and git push

7. git tag -a -m "TinkerPop x.y.z release" x.y.z and git push --tags

8. mvn clean install -Dmaven.test.skip=true

9. bin/publish-docs.sh <username>

10. mvn install -Papache-release -DcreateChecksum=true -Dmaven.test.skip=true

11. Upload artifacts to https://dist.apache.org/repos/dist/dev/incubator/tinkerpop for [VOTE] review.

    1. svn co --depth empty https://dist.apache.org/repos/dist/dev/incubator/tinkerpop/ dev and mkdir dev/x.y.z

    2. cp ~/.m2/repository/org/apache/tinkerpop/gremlin-console/x.y.z/gremlin-console-x.y.z-distribution.zip* dev/x.y.z

    3. cp ~/.m2/repository/org/apache/tinkerpop/gremlin-server/x.y.z/gremlin-server-x.y.z-distribution.zip* dev/x.y.z

    4. cp ~/.m2/repository/org/apache/tinkerpop/tinkerpop/x.y.z/tinkerpop-x.y.z-source-release.zip* dev/x.y.z

    5. cd dev/x.y.z and for f in .zip; do mv "$f" "apache-$f"; done

    6. cd ..; svn add x.y.z/; svn ci -m "TinkerPop x.y.z release"

12. Submit for [VOTE] at general@incubator.apache.org (see email template below).

13. Wait for vote acceptance (72 hours).

14. mvn clean install -Dmaven.test.skip=true; bin/process-docs.sh - rebuild source and docs of tagged release

15. mvn deploy -Papache-release -DcreateChecksum=true -Dmaven.test.skip=true- deploy signed artifacts with checksums to Apache Nexus

16. Review and close the staging repository (Apache Nexus at https://repository.apache.org/)

17. svn co --depth empty https://dist.apache.org/repos/dist/dev/incubator/tinkerpop dev; svn up dev/x.y.z

18. svn co --depth empty https://dist.apache.org/repos/dist/release/incubator/tinkerpop release; mkdir release/x.y.z

19. 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

20. cd release; svn add x.y.z/; svn ci -m "TinkerPop x.y.z release"

21. Update homepage with references to latest distribution and to other internal links elsewhere on the page.

22. Wait for Apache Central to sync the jars and src (http://repo1.maven.org/maven2/org/apache/tinkerpop/tinkerpop/).

23. 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>