[21/50] tinkerpop git commit: TINKERPOP-1996 Added upgrade docs

[sp...@apache.org]

TINKERPOP-1996 Added upgrade docs


Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/ded7c187
Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/ded7c187
Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/ded7c187

Branch: refs/heads/TINKERPOP-1967
Commit: ded7c187480a68b6f7be2d0cb777461f57a2871c
Parents: 8fd3bf2
Author: Stephen Mallette <sp...@genoprime.com>
Authored: Fri Jul 20 11:20:03 2018 -0400
Committer: Stephen Mallette <sp...@genoprime.com>
Committed: Fri Jul 20 11:20:03 2018 -0400

----------------------------------------------------------------------
 docs/src/upgrade/release-3.4.x.asciidoc | 49 ++++++++++++++++++++++++++--
 1 file changed, 47 insertions(+), 2 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/ded7c187/docs/src/upgrade/release-3.4.x.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/upgrade/release-3.4.x.asciidoc b/docs/src/upgrade/release-3.4.x.asciidoc
index 97e14e3..0bb3903 100644
--- a/docs/src/upgrade/release-3.4.x.asciidoc
+++ b/docs/src/upgrade/release-3.4.x.asciidoc
@@ -36,7 +36,7 @@ modulator. This modulator allows the step it is modifying to accept configuratio
 behavior of the step itself. A good example of its usage is shown with the revised syntax of the `pageRank()` step
 which now uses `with()` to replace the old `by()` options:
 
-[groovy]
+[source,groovy]
 ----
 g.V().hasLabel('person').
   pageRank().
@@ -49,7 +49,7 @@ g.V().hasLabel('person').
 
 A similar change was made for `peerPressure()` step:
 
-[groovy]
+[source,groovy]
 ----
 g.V().hasLabel('person').
   peerPressure().
@@ -65,6 +65,33 @@ release where breaking changes are allowed.
 See: link:https://issues.apache.org/jira/browse/TINKERPOP-1975[TINKERPOP-1975],
 link:http://tinkerpop.apache.org/docs/3.4.0/reference/#with-step[Reference Documentation]
 
+==== io() Step
+
+There have been some important changes to IO operations for reading and writing graph data. The use of `Graph.io()`
+has been deprecated to further remove dependence on the Graph (Structure) API for users and to extend these basic
+operations to GLV users by making these features available as part of the Gremlin language.
+
+It is now possible to simply use Gremlin:
+
+[source,groovy]
+----
+graph = ...
+g = graph.traversal()
+g.io(someInputFile).read().iterate()
+g.io(someOutputFile).write().iterate()
+----
+
+While `io()` step is still single-threaded for OLTP style loading, it can be utilized in conjunction with OLAP which
+internally uses `CloneVertexProgram` and therefore any graph `InputFormat` or `OutputFormat` can be configured in
+conjunction with this step for parallel loads of large datasets.
+
+It is also worth noting that the `io()`-step may be overriden by graph providers to utilize their native bulk-loading
+features, so consult the documentation of the implementation being used to determine if there are any improved
+efficiencies there.
+
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-1996[TINKERPOP-1996],
+link:http://tinkerpop.apache.org/docs/3.4.0/reference/#io-step[Reference Documentation]
+
 ==== Removal of Giraph Support
 
 Support for Giraph has been removed as of this version. There were a number of reasons for this decision which were
@@ -284,6 +311,24 @@ See: link:https://issues.apache.org/jira/browse/TINKERPOP-1522[TINKERPOP-1522]
 
 ==== Graph Database Providers
 
+===== io() Step
+
+The new `io()`-step that was introduced provides some new changes to consider. Note that `Graph.io()` has been
+deprecated and users are no longer instructed to utilize that method. It is not yet decided when that method will be
+removed completely, but given the public nature of it and the high chance of common usage, it should be hanging around
+for some time.
+
+As with any step in Gremlin, it is possible to replace it with a more provider specific implementation that could be
+more efficient. Developing a `TraversalStrategy` to do this is encouraged, especially for those graph providers who
+might have special bulk loaders that could be abstracted by this step. Examples of this are already shown with
+`HadoopGraph` which replaces the simple single-threaded loader with `CloneVertexProgram`. Graph providers are
+encouraged to use the `with()` step to capture any necessary configurations required for their underlying loader to
+work. Graph providers should not feel restricted to `graphson`, `gryo` and `graphml` formats either. If a graph
+supports CSV or some custom graph specific format, it shouldn't be difficult to gather the configurations necessary to
+make that available to users.
+
+See: link:https://issues.apache.org/jira/browse/TINKERPOP-1996[TINKERPOP-1996]
+
 ===== Caching Graph Features
 
 For graph implementations that have expensive creation times, it can be time consuming to run the TinkerPop test suite