[tinkerpop] branch TINKERPOP-1568 updated: TINKERPOP-1568 Add some docs around TraversalStrategy application revisions

[sp...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

spmallette pushed a commit to branch TINKERPOP-1568
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git


The following commit(s) were added to refs/heads/TINKERPOP-1568 by this push:
     new 08219eb  TINKERPOP-1568 Add some docs around TraversalStrategy application revisions
08219eb is described below

commit 08219ebd2bb6923a8a85f2e8868d3bf81b9299f6
Author: Stephen Mallette <sp...@genoprime.com>
AuthorDate: Wed Oct 23 15:06:29 2019 -0400

    TINKERPOP-1568 Add some docs around TraversalStrategy application revisions
---
 CHANGELOG.asciidoc                      |  2 ++
 docs/src/upgrade/release-3.5.x.asciidoc | 50 +++++++++++++++++++++++++++++++++
 2 files changed, 52 insertions(+)

diff --git a/CHANGELOG.asciidoc b/CHANGELOG.asciidoc
index fd3339c..5d7c270 100644
--- a/CHANGELOG.asciidoc
+++ b/CHANGELOG.asciidoc
@@ -35,8 +35,10 @@ This release also includes changes from <<release-3-4-3, 3.4.3>>.
 * Upgraded to Neo4j 3.4.11.
 * Added a parameterized `TypeTranslator` for use with `GroovyTranslator` that should produce more cache hits.
 * Added support for `TextP` in Neo4j using its string search functions.
+* Changed `TraversalStrategy` application methodology to apply each strategy in turn to each level of the traversal hierarchy starting from root down to children.
 * Removed the "experimental" support for multi/meta-properties in Neo4j.
 * Removed Gryo serialization configurations from Gremlin Server sample configurations and default configurations.
+* Removed previously deprecated `TraversalStrategies.applyStrategies()`.
 * Removed previously deprecated `scriptEvaluationTimeout`.
 * Removed previously deprecated remote traversal side-effects.
 * Removed previously deprecated `Serializers.DEFAULT_RESULT_SERIALIZER` and `Serializers.DEFAULT_REQUEST_SERIALIZER`.
diff --git a/docs/src/upgrade/release-3.5.x.asciidoc b/docs/src/upgrade/release-3.5.x.asciidoc
index cd04b4e..7372107 100644
--- a/docs/src/upgrade/release-3.5.x.asciidoc
+++ b/docs/src/upgrade/release-3.5.x.asciidoc
@@ -192,6 +192,56 @@ link:http://tinkerpop.apache.org/docs/3.5.0/upgrade/#_ssl_security[3.2.10 Upgrad
 
 ==== Graph System Providers
 
+===== TraversalStrategy Application
+
+The methodology for strategy application has been altered and the change is most easily described by example. Given a
+traversal with the structure:
+
+[source,text]
+----
+a(b(),c(d()))
+----
+
+Strategies were formerly applied in the following order:
+
+[source,text]
+----
+StrategyA on a
+StrategyB on a
+StrategyA on b
+StrategyB on b
+StrategyA on c
+StrategyB on c
+StrategyA on d
+StrategyB on d
+----
+
+This approach has always prevented strategies from performing global operations across the traversal and all decedents
+effectively as children will not have been processed by preceding strategies yet. As of this release, the approach
+has been altered to apply strategies as follows:
+
+[source,text]
+----
+StrategyA on a
+StrategyA on b
+StrategyA on c
+StrategyA on d
+StrategyB on a
+StrategyB on b
+StrategyB on c
+StrategyB on d
+----
+
+In this way, strategy B can check if it is being applied to the root traversal and if it is it knows that A has been
+applied globally.
+
+This revised methodology could represent a breaking change for `TraversalStrategy` implementations if they somehow
+relied on the old ordering of application. It may also present an opportunity to revise how a `TraversalStrategy` is
+written to gain some processing benefit to the new order. Please be sure to review any custom strategies carefully
+when upgrading to this version.
+
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-1568[TINKERPOP-1568]
+
 ===== AbstractOpProcessor API Change
 
 The `generateMetaData()` method was removed as it was deprecated in a previous version. There already was a preferred