Merge branch 'asciidoc-header' into asciidoc-header-master
Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/a297b0dd Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/a297b0dd Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/a297b0dd Branch: refs/heads/master Commit: a297b0dd94e6c1f9d2d9822eb09293f2ccff8815 Parents: be8a90f cff1277 Author: Daniel Kuppitz <daniel_kupp...@hotmail.com> Authored: Tue Sep 26 06:25:06 2017 -0700 Committer: Daniel Kuppitz <daniel_kupp...@hotmail.com> Committed: Tue Sep 26 06:25:06 2017 -0700 ---------------------------------------------------------------------- CHANGELOG.asciidoc | 217 +++------ CONTRIBUTING.asciidoc | 5 +- README.asciidoc | 12 +- docs/src/dev/developer/administration.asciidoc | 12 +- docs/src/dev/developer/contributing.asciidoc | 30 +- .../developer/development-environment.asciidoc | 27 +- docs/src/dev/developer/for-committers.asciidoc | 60 +-- docs/src/dev/developer/index.asciidoc | 6 +- docs/src/dev/developer/meetings.asciidoc | 11 +- docs/src/dev/developer/release.asciidoc | 33 +- docs/src/dev/future/index.asciidoc | 14 +- docs/src/dev/io/graphml.asciidoc | 5 +- docs/src/dev/io/graphson.asciidoc | 479 +++++++------------ docs/src/dev/io/gryo.asciidoc | 5 +- docs/src/dev/io/index.asciidoc | 5 +- docs/src/dev/provider/index.asciidoc | 75 +-- docs/src/index.asciidoc | 14 +- docs/src/recipes/appendix.asciidoc | 3 +- docs/src/recipes/between-vertices.asciidoc | 5 +- docs/src/recipes/centrality.asciidoc | 15 +- docs/src/recipes/connected-components.asciidoc | 5 +- docs/src/recipes/cycle-detection.asciidoc | 5 +- docs/src/recipes/duplicate-edge.asciidoc | 5 +- docs/src/recipes/duplicate-vertex.asciidoc | 3 +- .../src/recipes/if-then-based-grouping.asciidoc | 5 +- docs/src/recipes/index.asciidoc | 14 +- docs/src/recipes/pagination.asciidoc | 5 +- docs/src/recipes/recommendation.asciidoc | 5 +- docs/src/recipes/shortest-path.asciidoc | 3 +- docs/src/recipes/style-guide.asciidoc | 6 +- .../recipes/traversal-component-reuse.asciidoc | 5 +- .../recipes/traversal-induced-values.asciidoc | 5 +- docs/src/recipes/tree.asciidoc | 14 +- docs/src/reference/acknowledgements.asciidoc | 3 +- docs/src/reference/conclusion.asciidoc | 3 +- .../src/reference/gremlin-applications.asciidoc | 192 +++----- docs/src/reference/gremlin-variants.asciidoc | 56 +-- .../reference/implementations-giraph.asciidoc | 8 +- .../implementations-hadoop-end.asciidoc | 30 +- .../implementations-hadoop-start.asciidoc | 17 +- .../reference/implementations-intro.asciidoc | 5 +- .../reference/implementations-neo4j.asciidoc | 21 +- .../reference/implementations-spark.asciidoc | 20 +- .../implementations-tinkergraph.asciidoc | 6 +- docs/src/reference/intro.asciidoc | 21 +- docs/src/reference/preface.asciidoc | 15 +- docs/src/reference/the-graph.asciidoc | 39 +- docs/src/reference/the-graphcomputer.asciidoc | 33 +- docs/src/reference/the-traversal.asciidoc | 270 ++++------- .../tutorials/getting-started/index.asciidoc | 33 +- .../gremlin-language-variants/index.asciidoc | 30 +- .../the-gremlin-console/index.asciidoc | 17 +- docs/src/upgrade/index.asciidoc | 5 +- .../upgrade/release-3.0.x-incubating.asciidoc | 60 +-- .../upgrade/release-3.1.x-incubating.asciidoc | 288 ++++------- .../upgrade/release-3.2.x-incubating.asciidoc | 378 +++++---------- docs/src/upgrade/release-3.3.x.asciidoc | 108 ++--- .../archetype-resources/README.asciidoc | 11 +- .../archetype-resources/README.asciidoc | 11 +- .../archetype-resources/README.asciidoc | 11 +- gremlin-server/src/test/scripts/README.asciidoc | 2 +- 61 files changed, 948 insertions(+), 1858 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a297b0dd/CHANGELOG.asciidoc ---------------------------------------------------------------------- diff --cc CHANGELOG.asciidoc index 6002694,09f3543..93c2d53 --- a/CHANGELOG.asciidoc +++ b/CHANGELOG.asciidoc @@@ -14,233 -14,9 +14,230 @@@ WITHOUT WARRANTIES OR CONDITIONS OF AN See the License for the specific language governing permissions and limitations under the License. //// - TinkerPop3 CHANGELOG - ==================== + = TinkerPop3 CHANGELOG - TinkerPop 3.3.0 (Gremlin Symphony #40 in G Minor) - ------------------------------------------------- ++<<<<<<< HEAD ++== TinkerPop 3.3.0 (Gremlin Symphony #40 in G Minor) + +image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/images/gremlin-mozart.png[width=185] + +[[release-3-3-1]] - TinkerPop 3.3.1 (Release Date: NOT OFFICIALLY RELEASED YET) - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ++=== TinkerPop 3.3.1 (Release Date: NOT OFFICIALLY RELEASED YET) + +This release also includes changes from <<release-3-2-7, 3.2.7>>. + +* `PageRankVertexProgram` supports `maxIterations` but will break out early if epsilon-based convergence occurs. +* Added support for epsilon-based convergence in `PageRankVertexProgram`. +* Fixed two major bugs in how PageRank was being calculated in `PageRankVertexProgram`. +* Added `Io.requiresVersion(Object)` to allow graph providers a way to check the `Io` type and version being constructed. +* Defaulted `IoCore.gryo()` and `IoCore.graphson()` to both use their 3.0 formats which means that `Graph.io()` will use those by default. +* Bumped Neo4j 3.2.3 + + +[[release-3-3-0]] - TinkerPop 3.3.0 (Release Date: August 21, 2017) - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ++=== TinkerPop 3.3.0 (Release Date: August 21, 2017) + +This release also includes changes from <<release-3-2-6, 3.2.6>>. + +* Removed previously deprecated `ScriptElementFactory`. +* Added `GraphTraversalSource.addE(String)` in support of `g.addE().from().to()`. +* Added support for `to(Vertex)` and `from(Vertex)` as a shorthand for `to(V(a))` and `from(V(b))`. +* Bumped to support Spark 2.2.0. +* Detected if type checking was required in `GremlinGroovyScriptEngine` and disabled related infrastructure if not. +* Removed previously deprecated `GraphTraversal.selectV3d0()` step. +* Removed previously deprecated `DetachedEdge(Object,String,Map,Pair,Pair)` constructor. +* Removed previously deprecated `Bindings` constructor. It is now a private constructor. +* Removed previously deprecated `TraversalSource.withBindings()`. +* Removed previously deprecated `GraphTraversal.sack(BiFunction,String)`. +* `TraversalMetrics` and `Metrics` Gryo 1.0 formats changed given internal changes to their implementations. +* Made `TraversalMetrics` safe to write to from multiple threads. +* Removed previously deprecated `TraversalSideEffects` methods. +* Removed previously deprecated `finalization.LazyBarrierStrategy` (moved to `optimization.LazyBarrierStrategy`). +* Removed previously deprecated `Constants` in Hadoop. +* Removed previously deprecated `VertexComputing.generateComputer(Graph)`. +* Removed previously deprecated `ConfigurationTraversal`. +* Established the Gryo 3.0 format. +* `GryoVersion` now includes a default `ClassResolver` to supply to the `GryoMapper`. +* `GryoClassResolver` renamed to `GryoClassResolverV1d0` which has an abstract class that for providers to extend in `AbstractGryoClassResolver`. +* Removed previously deprecated `Order` enums of `keyIncr`, `keyDecr`, `valueIncr`, and `valueDecr.` +* Removed previously deprecated `GraphTraversal.mapKeys()` step. +* Removed previously deprecated `GraphTraversal.mapValues()` step. +* Removed previously deprecated `GraphTraversal#addV(Object...)`. +* Removed previously deprecated `GraphTraversal#addE(Direction, String, String, Object...)`. +* Removed previously deprecated `GraphTraversal#addOutE(String, String, Object...)`. +* Removed previously deprecated `GraphTraversal#addInV(String, String, Object...)`. +* Removed previously deprecated `GraphTraversal.groupV3d0()` and respective `GroupSideEffectStepV3d0` and `GroupStepV3d0`. +* Removed previously deprecated `TraversalSource.Builder` class. +* Removed previously deprecated `ConnectiveP`, `AndP`, `OrP` constructors. +* Removed previously deprecated `TraversalScriptFunction` class. +* Removed previously deprecated `TraversalScriptHelper` class. +* Removed previously deprecated `ScriptEngineCache` class. +* Removed previously deprecated `CoreImports` class. +* Removed previously deprecated `GremlinJythonScriptEngine#()` constructor. +* Removed access to previously deprecated `CoreGremlinPlugin#INSTANCE` field. +* `gremlin.sh` and `gremln.bat` no longer support the option to pass a script as an argument for execution mode without using the `-i` option. +* Graphite and Ganglia are no longer packaged with the Gremlin Server distribution. +* `TransactionException` is no longer a class of `AbstractTransaction` and it extends `RuntimeException`. +* Included an ellipse on long property names that are truncated. +* Renamed `RangeByIsCountStrategy` to `CountStrategy`. +* Added more specific typing to various `__` traversal steps. E.g. `<A,Vertex>out()` is `<Vertex,Vertex>out()`. +* Updated Docker build scripts to include Python dependencies (NOTE: users should remove any previously generated TinkerPop Docker images). +* Added "attachment requisite" `VertexProperty.element()` and `Property.element()` data in GraphSON serialization. +* GraphSON 3.0 is now the default serialization format in TinkerGraph and Gremlin Server. +* Changed `ServerGremlinExecutor` to not use generics since there really is no flexibility in the kind of `ScheduledExecutorService` that will be used. +* Removed support for passing a byte array on the `sasl` parameter. +* Removed previously deprecated `GraphSONMapper$Builder#embedTypes` option. +* Removed previously deprecated `:remote config timeout max`. +* Removed previously deprecated `ConnectionPoolSettings.sessionId` and `ConnectionPoolSettings.optionalSessionId()`. +* Removed previously deprecated `reconnectInitialDelay` setting from the Java driver. +* Removed previously deprecated `useMapperFromGraph` option. +* Established the GraphSON 3.0 format with new `g:Map`, `g:List` and `g:Set` types. +* Removed previously deprecated `Io.Builder#registry(IoRegistry)` method. +* Removed previously deprecated `GryoMessageSerializerV1d0(GryoMapper)` constructor. +* Removed previously deprecated `TinkerIoRegistry`. +* Removed previously deprecated `getInstance()` methods on all TinkerPop classes. +* Removed previously deprecated `VertexPropertyFeatures.supportsAddProperty()`. +* Removed previously deprecated TinkerGraph configuration member variables. +* Removed previously deprecated `Transaction.submit(Function)`. +* Removed previously deprecated `OpSelectorHandler.errorMeter` and `AbstractEvalOpProcessor.errorMeter` fields. +* Removed previously deprecated `AbstractEvalOpProcessor.validBindingName` field. +* Removed previously deprecated `SimpleAuthenticator.CONFIG_CREDENTIALS_LOCATION` field. +* Removed previously deprecated `IteratorHandler`, `NioGremlinResponseEncoder` and `WsGremlinResponseEncoder` classes. +* Removed previously deprecated `Session.kill()` and `Session.manualKill()`. +* Removed previously deprecated `Authenticator.newSaslNegotiator()` and its method implementations in classes that were assignable to that interface. +* Removed `gremlin-groovy-test`. +* Removed previously deprecated "G" functions in `gremlin-groovy` (i.e. `GFunction`). +* Removed references to the old `GremlinPlugin` system that was in `gremlin-groovy` - the revised `GremlinPlugin` system in `gremlin-core` is the only one now in use. +* `GremlinGroovyScriptEngine` no longer implements the now removed `DependencyManager`. +* Added `Vertex`, `Edge`, `VertexProperty`, and `Property` serializers to Gremlin-Python and exposed tests that use graph object arguments. +* `Bytecode.getSourceInstructions()` and `Bytecode.getStepInstructions()` now returns `List<Instruction>` instead of `Iterable<Instruction>`. +* Added various `TraversalStrategy` registrations with `GryoMapper`. +* Fixed a naming mistake in Gremlin-Python: `IdentityRemoveStrategy` is now called `IdentityRemovalStrategy`. +* Added `TranslationStrategy` test infrastructure that verifies `Bytecode` generated from a translation is equal to the original `Bytecode`. +* Moved `NumberHelper` into the `org.apache.tinkerpop.gremlin.util` package. +* Added `Pop.mixed` instead of using `null` to represent such semantics. +* `select()`-step now defaults to using `Pop.last` instead of `Pop.mixed`. +* Added `gremlin-io-test` module to validate IO formats. +* `RequestMessage` and `ResponseMessage` are now registered with `GryoMapper` as part of the TinkerPop range of type identifiers. +* Removed previously deprecated `Console` constructor that took a `String` as an argument from `gremlin-console`. +* Removed previously deprecated `ConcurrentBindings` from `gremlin-groovy`. +* Removed previously deprecated `ScriptExecutor` from `gremlin-groovy`. +* Removed previously deprecated `SandboxExtension` from `gremlin-groovy`. +* Removed previously deprecated `GremlinGroovyScriptEngine` constructor that took `ImportCustomizerProvider` as an argument from `gremlin-groovy`. +* Removed previously deprecated `GremlinGroovyScriptEngine#plugins()` from `gremlin-groovy`. +* Added `OptionalStep` for use with `optional()` to better handle issues associated with branch side-effects. +* `UnfoldStep` now supports unfolding of arrays. +* Removed all performance tests that were not part of `gremlin-benchmark`. +* Removed dependency on `junit-benchmarks` and it's related reference to `h2`. +* Moved the source for the "home page" into the repository under `/site` so that it easier to accept contributions. +* Added `UnshadedKryoShimService` as the new default serializer model for `SparkGraphComputer`. +* `GryoRegistrator` is more efficient than the previous `GryoSerializer` model in `SparkGraphComputer`. +* Added support for `IoRegistry` custom serialization in Spark/Giraph and provided a general `hadoop-gremlin` test suite. +* Replaced term `REST` with `HTTP` to remove any confusion as to the design of the API. +* Moved `gremlin-benchmark` under `gremlin-tools` module. +* Added `gremlin-tools` and its submodule `gremlin-coverage`. +* Removed `tryRandomCommit()` from `AbstractGremlinTest`. +* Changed `gremlin-benchmark` system property for the report location to `benchmarkReportDir` for consistency. +* Added SysV and systemd init scripts. +* `GraphTraversal.valueMap(includeTokens,propertyKeys...)` now returns a `Map<Object,E>` since keys could be `T.id` or `T.label`. +* Added `skip(long)` and `skip((Scope,long)` which call the `range(low,high)` equivalents with -1 as the high. +* Added Kerberos authentication to `gremlin-server` for websockets and nio transport. +* Added audit logging of authenticated users and gremlin queries to `gremlin-server`. + - Bugs - ^^^^ ++==== Bugs + +* TINKERPOP-1211 UnfoldStep should unfold arrays. *(breaking)* +* TINKERPOP-1426 GryoSerializer should implement Java serialization interface +* TINKERPOP-1465 Remove deprecated newSaslNegotiator *(breaking)* +* TINKERPOP-1483 PropertyMapStep returns Map<String,E> but puts non String keys in it! +* TINKERPOP-1520 Difference between 'has' step generated graphson2.0 in java and python glv implementation +* TINKERPOP-1533 Storage and IoRegistry +* TINKERPOP-1597 PathRetractionStrategy messing up certain traversals +* TINKERPOP-1635 gremlin-python: Duplicate serialization of element property in PropertySerializer +* TINKERPOP-1658 Graphson2 map keys are serialised as strings +* TINKERPOP-1716 Traversal strategies are not applied with remote in Gremlin Console + - Improvements - ^^^^^^^^^^^^ ++==== Improvements + +* TINKERPOP-832 Remove deprecated addV/E/InE/OutE methods *(breaking)* +* TINKERPOP-833 Remove deprecated GremlinGroovyScriptEngine constructor and plugins() *(breaking)* +* TINKERPOP-834 Remove deprecated sack() method *(breaking)* +* TINKERPOP-880 Remove deprecated GroupStepV3d0 and GroupSideEffectStepV3d0 *(breaking)* +* TINKERPOP-929 Remove Deprecated TinkerGraph public static methods. *(breaking)* +* TINKERPOP-980 Add a service script or daemon mode in the distribution *(breaking)* +* TINKERPOP-999 ServerGremlinExecutor construction need not use generics for ExecutorService *(breaking)* +* TINKERPOP-1004 Make Transaction.commit() failures consistent across implementations. *(breaking)* +* TINKERPOP-1010 Remove deprecated credentialsDbLocation for SimpleAuthenticator *(breaking)* +* TINKERPOP-1024 Remove deprecated tryRandomCommit() *(breaking)* +* TINKERPOP-1028 Remove deprecated ConnectionPoolSettings session settings *(breaking)* +* TINKERPOP-1040 Remove deprecated SandboxExtension *(breaking)* +* TINKERPOP-1046 Remove deprecated Gremlin Server handler implementations *(breaking)* +* TINKERPOP-1049 Remove deprecated error meter member variables in Gremlin Server handlers *(breaking)* +* TINKERPOP-1094 Remove deprecated VertexPropertyFeatures.FEATURE_ADD_PROPERTY *(breaking)* +* TINKERPOP-1116 Some anonymous traversal steps can be hard typed. *(breaking)* +* TINKERPOP-1130 Each release should store Kryo/GraphSON/GraphML versions to ensure future compatibility *(breaking)* +* TINKERPOP-1142 Remove deprecated valueIncr, valueDecr, keyIncr, keyDecr. *(breaking)* +* TINKERPOP-1169 Remove deprecated TraversalScriptFunction and TraversalScriptHelper *(breaking)* +* TINKERPOP-1170 Remove deprecated ConfigurationTraversal. *(breaking)* +* TINKERPOP-1171 Remove deprecated TraversalSource.Builder *(breaking)* +* TINKERPOP-1235 Remove deprecated ProcessPerformanceSuite and TraversalPerformanceTest *(breaking)* +* TINKERPOP-1275 Remove deprecated max setting for :remote *(breaking)* +* TINKERPOP-1283 Remove deprecated ScriptExecutor *(breaking)* +* TINKERPOP-1289 Remove deprecated ConnectiveP, AndP, and OrP constructors. *(breaking)* +* TINKERPOP-1291 Remove deprecated mapValues and mapKeys methods *(breaking)* +* TINKERPOP-1313 Rename RangeByIsCountStrategy *(breaking)* +* TINKERPOP-1316 Remove deprecated constructor from GryoMessageSerializers *(breaking)* +* TINKERPOP-1327 Bring GryoRegistrator to the forefront and deprecate GryoSerializer *(breaking)* +* TINKERPOP-1363 Cleanup Docker build script for next major release *(breaking)* +* TINKERPOP-1369 Replace REST API with HTTP API +* TINKERPOP-1389 Support Spark 2.0.0 +* TINKERPOP-1399 NumberHelper needs to go into util and have a private constructor *(breaking)* +* TINKERPOP-1404 Path/label optimization +* TINKERPOP-1408 Remove Deprecated Io.Builder.registry() *(breaking)* +* TINKERPOP-1414 Change default GraphSON version to 3.0 *(breaking)* +* TINKERPOP-1420 Remove deprecated ConcurrentBindings in gremlin-groovy *(breaking)* +* TINKERPOP-1421 Remove deprecated ControlOps *(breaking)* +* TINKERPOP-1427 GraphSON 3.0 needs collection types and consistent number typing. +* TINKERPOP-1443 Use an API checker during build +* TINKERPOP-1445 Large nested VertexProperties and Properties do not get printed well +* TINKERPOP-1454 Create Serializers for Graph objects in Gremlin-Python +* TINKERPOP-1481 Remove deprecated reconnectInitialDelay in Java driver *(breaking)* +* TINKERPOP-1485 Move source for TinkerPop site to source code repo +* TINKERPOP-1506 Optional/Coalesce should not allow sideEffect traversals. +* TINKERPOP-1514 Restructure for gremlin-tools module *(breaking)* +* TINKERPOP-1524 Bytecode.getXXXInstructions should return a List, not Iterable. +* TINKERPOP-1526 Remove deprecated Session kill() overloads *(breaking)* +* TINKERPOP-1536 Include GLVs in Docker build +* TINKERPOP-1541 Select should default to Pop.last semantics *(breaking)* +* TINKERPOP-1549 Implement skip() +* TINKERPOP-1550 Make Graphite and Ganglia optional dependencies +* TINKERPOP-1563 Remove deprecated getInstance() methods *(breaking)* +* TINKERPOP-1565 Setup GraphSON 3.0 +* TINKERPOP-1566 Kerberos authentication for gremlin-server +* TINKERPOP-1574 Get rid of untyped GraphSON in 3.0 +* TINKERPOP-1603 Remove support for SASL byte array in protocol *(breaking)* +* TINKERPOP-1612 Remove gremlin-groovy-test module *(breaking)* +* TINKERPOP-1621 Remove deprecated GremlnPlugin and related infrastructure *(breaking)* +* TINKERPOP-1622 Remove deprecated G functions in gremlin-groovy *(breaking)* +* TINKERPOP-1651 Remove deprecated gremlin.sh init syntax *(breaking)* +* TINKERPOP-1686 Make TraversalMetrics thread safe *(breaking)* +* TINKERPOP-1698 Gryo 3.0 +* TINKERPOP-1699 Remove deprecated userMapperFromGraph *(breaking)* +* TINKERPOP-1700 Remove deprecated embedTypes option +* TINKERPOP-1706 Remove deprecated ScriptEngineCache and related dead code *(breaking)* +* TINKERPOP-1715 Bump to Spark 2.2 +* TINKERPOP-1719 Remove deprecated Traversal related code *(breaking)* +* TINKERPOP-1720 Remove deprecated Hadoop code *(breaking)* +* TINKERPOP-1721 Remove deprecated Bindings related code *(breaking)* +* TINKERPOP-1724 Remove deprecated ScriptElementFactory +* TINKERPOP-1729 Remove deprecated select steps. +* TINKERPOP-1740 Add vertex parameter overload to to() and from() +* TINKERPOP-1747 Streamline inheritance for gremlin-python GraphSON serializer classes + - TinkerPop 3.2.0 (Nine Inch Gremlins) - ------------------------------------ ++== TinkerPop 3.2.0 (Nine Inch Gremlins) ++======= + == TinkerPop 3.2.0 (Nine Inch Gremlins) ++>>>>>>> asciidoc-header image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/images/nine-inch-gremlins.png[width=185] http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a297b0dd/docs/src/dev/developer/development-environment.asciidoc ---------------------------------------------------------------------- diff --cc docs/src/dev/developer/development-environment.asciidoc index 8c6d75d,c619e19..f7c9077 --- a/docs/src/dev/developer/development-environment.asciidoc +++ b/docs/src/dev/developer/development-environment.asciidoc @@@ -23,11 -22,10 +22,10 @@@ this complexity, it remains relatively configure a development environment for TinkerPop. [[system-configuration]] - System Configuration - -------------------- + == System Configuration At a minimum, development of TinkerPop requires link:http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html[Java 1.8.0_40+] -and link:https://maven.apache.org/download.cgi[Maven 3.0.5+]. Maven is used as the common build system, which even +and link:https://maven.apache.org/download.cgi[Maven 3.2.5+]. Maven is used as the common build system, which even controls the builds of non-JVM link:http://tinkerpop.apache.org/docs/current/tutorials/gremlin-language-variants/[GLVs] such as `gremlin-python`. Java and Maven are described as a "minimum" for a development environment, because they will only build JVM portions of TinkerPop and many integration tests will not fire with this simple setup. It is @@@ -205,17 -198,11 +198,16 @@@ mvn -Dmaven.javadoc.skip=true --project * Integration Tests: `mvn verify -DskipIntegrationTests=false` ** Execute with the `-DincludeNeo4j` option to include transactional tests. ** Execute with the `-DuseEpoll` option to try to use Netty native transport (works on Linux, but will fallback to Java NIO on other OS). -* Performance Tests: `mvn verify -DskipPerformanceTests=false` * Benchmarks: `mvn verify -DskipBenchmarks=false` +** Reports are generated to the console and to `gremlin-tools/gremlin-benchmark/target/reports/benchmark`. +* Test coverage report: `mvn clean install -Dcoverage` - note that the `install` is necessary because report aggregation is bound to that part of the lifecycle. +** Reports are generated to `gremlin-tools/gremlin-coverage/target/site`. +* `cd site` +** Generate web site locally: `bin/generate-home.sh` +** Publish web site: `bin/publish-home.sh <username>` [[docker-integration]] - Docker Integration - ------------------ + == Docker Integration TinkerPop provides a shell script, that can start several build tasks within a Docker container. The required Docker images will be built automatically if they don't exist yet. Thus the first invocation http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a297b0dd/docs/src/dev/developer/for-committers.asciidoc ---------------------------------------------------------------------- diff --cc docs/src/dev/developer/for-committers.asciidoc index 980d7b4,c62f1da..27fd06a --- a/docs/src/dev/developer/for-committers.asciidoc +++ b/docs/src/dev/developer/for-committers.asciidoc @@@ -439,24 -422,8 +421,22 @@@ uploaded to the server and should prese Please see the <<building-testing,Building and Testing>> section for more information on how to generate the documentation. +[[site]] - Site - ---- ++== Site + +The content for the TinkerPop home page and related pages that make up the web site at link://tinkerpop.apache.org[tinkerpop.apache.org] +is stored in the git repository under `/docs/site`. In this way, it becomes easier for the community to provide content +presented there, because the content can be accepted via the standard workflow of a pull request. To generate the site +for local viewing, run `bin/generate-home.sh`, which will build the site in `target/site/`. PMC members can officially +publish the site with `bin/publish-home.sh <username>`. + +"Publishing" does not publish documentation (e.g. reference docs, javadocs, etc) and only publishes what is generated +from the content in `/docs/site`. Publishing the site can be performed out of band with the release cycle and is no +way tied to a version. The `master` branch should always be considered the "current" web site and publishing should +only happen from that branch. + [[logging]] - Logging - ------- + == Logging TinkerPop uses SLF4j for logging and typically leans back on Log4j as the implementation. Configuring log outputs for debugging purposes within tests can be altered by editing the `log4j-test.properties` file in each module's test http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a297b0dd/docs/src/dev/developer/release.asciidoc ---------------------------------------------------------------------- diff --cc docs/src/dev/developer/release.asciidoc index e4e8967,dac28b3..1e33001 --- a/docs/src/dev/developer/release.asciidoc +++ b/docs/src/dev/developer/release.asciidoc @@@ -235,11 -222,10 +229,10 @@@ for generating javadoc and without tha . Submit for `[VOTE]` at `d...@tinkerpop.apache.org` (see email template below) . *Wait for vote acceptance* (72 hours) - Release & Promote - ----------------- + == Release & Promote . Login to link:https://repository.apache.org/[Apache Nexus] and release the previously closed repository. -. Deploy to link:https://pypi.python.org/pypi[pypi] +. Deploy the GLVs .. This build will likely occur from the tag for the release, so be sure to checkout the tag first before executing this step. .. `mvn clean install -DskipTests -Dnuget` .. `mvn deploy -pl gremlin-python -DskipTests -Dpypi` http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a297b0dd/docs/src/dev/future/index.asciidoc ---------------------------------------------------------------------- diff --cc docs/src/dev/future/index.asciidoc index 0bb7ca4,0000000..63900e8 mode 100644,000000..100644 --- a/docs/src/dev/future/index.asciidoc +++ b/docs/src/dev/future/index.asciidoc @@@ -1,124 -1,0 +1,120 @@@ +//// +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. +//// +image::apache-tinkerpop-logo.png[width=500,link="http://tinkerpop.apache.org";] + +*4.0.0* + +:toc-position: left + - TinkerPop 4.x Design Ideas - ========================== ++= TinkerPop 4.x Design Ideas + +TinkerPop 4.x is not a version considered on the immediate horizon, but there are often points in the day to day +development of TinkerPop 3.x where there are changes of importance, novelty and usefulness that are so big that they +could only be implemented under a major new version. This document is meant to track these concepts as they develop, +so that at some point in the future they can be referenced in a single place. + +There is no particular layout or style to this document. Simple bullet points, open questions posed as single +sentences, or fully structured document headers and content are all acceptable. The main point is to capture ideas +for future consideration when 4.x becomes the agenda of the day for The TinkerPop. + +image:tp4-think.png[] + - The Main Features - ----------------- ++== The Main Features + +TinkerPop4 should focus on the most successful aspects of TinkerPop3 and it should avoid the traps realized in TinkerPop3. +These items include: + +* The concept of Gremlin as both a virtual machine and language. +** A standard bytecode specification should be provided. +** A standard machine architecture should be provided. +* The concept of Gremlin language variants. +** It should be easy to create Gremlin variants in every major programming language. +** A standard template should be followed for all languages. +** Apache TinkerPop should provide variants in all major programming languges. +* The concept of `Traversal` as the sole means of interacting with the graph. +** The role of Blueprints should be significantly reduced. +** The role of Gremlin should be significantly increased. + + - Hiding Blueprints - ----------------- ++== Hiding Blueprints + +Originally from the link:https://lists.apache.org/thread.html/b4d80072ad36849b4e9cd3308f87115660574e3e7a4abb7ee68e959b@%3Cdev.tinkerpop.apache.org%3E[mailing list]: + +Throughout our documentation we show uses of the âBlueprints APIâ (i.e. Graph/Vertex/Edge/etc. classes & methods) as +well as the use of the Traversal API (i.e. Gremlin). + +Enabling users to have two ways of interacting with the graph system has its problems: + +1. The DetachedXXX problem â how much data should a returned vertex/edge/etc. have associated with it? +2. `graph.addVertex()` and `g.addV()` â which should I use? The first is faster but is not recommended. +3. `SubgraphStrategy` leaking â I get subgraphs with Gremlin, but can then directly interact with the vertex objects to see more than I should. +4. `VertexProgram` model â I write traversals with Traversal API, but then develop VertexPrograms with the Blueprints API. Thatâs weird. +5. GremlinServer returning fat objects â Serializers are created property-rich vertices and edges. The awkward HaltedTraversalStrategy solution. +6. ⦠various permutations of these source problems. + +In TinkerPop4 the solution might be as follows: + +There should be two âGraph APIs.â + +1. Provider Graph API: This is the current Blueprints API with `Graph.addVertex()`, `Vertex.edges()`, `Edge.inVertex()`, etc. +2. User Graph API: This is a ReferenceXXX API. + +The first API is well known, but the second bears further discussion. `ReferenceGraph` is simply a reference/dummy/proxy +to the provider Graph API. `ReferenceGraph` has the following API: + +* `ReferenceGraph.open()` +* `ReferenceGraph.close()` +* `ReferenceGraph.tx()` // assuming we like the current transaction model (??) +* `ReferenceGraph.traversal()` + +That is it. What does this entail? Assume the following traversal: + +[source,java] +---- +g = ReferenceGraph.open(config).traversal() +g.V(1).out(âknowsâ) +---- + +`ReferenceGraph` is almost like a `RemoteGraph` (`RemoteStrategy`) in that it makes a connection (remote or inter-JVM) +to the provider Graph API. When `g.V(1).out(âknowsâ)` executes, it is really sending the bytecode to the provider Graph +for execution (as specified by the config of `ReferenceGraph.open()`). Thus, once it hits the provider's graph, +`ProviderVertex`, `ProviderEdge`, etc. are the objects being processed. However, what the traversalâs `Iterator<Vertex>` +returns is `ReferenceVertex`! That is, it never returns `ProviderVertex`. In this way, regardless if the user is +going âover the wireâ or within the same JVM or against a different providerâs graph database or from +Gremlin-Python/C#/etc., all the vertices are simply âreference verticesâ (id + label). This makes it so that users +never interact with the graph element objects themselves directly. They can ONLY interact with the graph via +traversals! At most they can `ReferenceVertex.id()` and `ReferenceVertex.label()`. Thats it, â no mutations, not +walking edges, nada! And moreover, since ReferenceXXX has enough information to re-attach to the source graph, they +can always do the following to get more information: + +[source,java] +---- +v = g.V(1).out(âknowsâ).next() +g.V(v).values(ânameâ) +---- + +This split into two Graph APIs will enables us to make a hard boundary between what the provider (vendor) needs to +implement and what the user (developer) gets to access. + - Comments - ~~~~~~~~ ++=== Comments + +There is a question mark next to `ReferenceGraph.tx()` - Transactions are a bit of an open question for future versions +of TinkerPop and likely deserve their own section in this document. The model used for last three version of TinkerPop +now is rooted in the Neo4j approach to transactions and is often more trouble than it should be for us and providers. +Distributed transactions are a challenge and don't apply to every provider. Transactions are further complicated by +GLVs. The idea of local subgraphs for mutations and transaction management might be good but that goes against having - just `ReferenceGraph`. ++just `ReferenceGraph`.
