incubator-tinkerpop git commit: Added a "how to contribute" section to recipes. CTR

[sp...@apache.org]

Repository: incubator-tinkerpop
Updated Branches:
  refs/heads/master 09b87ea80 -> 55172b447


Added a "how to contribute" section to recipes. CTR


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

Branch: refs/heads/master
Commit: 55172b447325a995b91a80ccf9bfdca6ba656d42
Parents: 09b87ea
Author: Stephen Mallette <sp...@genoprime.com>
Authored: Fri May 6 09:38:48 2016 -0400
Committer: Stephen Mallette <sp...@genoprime.com>
Committed: Fri May 6 09:38:48 2016 -0400

----------------------------------------------------------------------
 docs/src/recipes/index.asciidoc | 69 ++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/55172b44/docs/src/recipes/index.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/recipes/index.asciidoc b/docs/src/recipes/index.asciidoc
index 3ff99d1..a9c3796 100644
--- a/docs/src/recipes/index.asciidoc
+++ b/docs/src/recipes/index.asciidoc
@@ -36,3 +36,72 @@ link:http://tinkerpop.apache.org/docs/x.y.z/tutorials/the-gremlin-console/[The G
 include::shortest-path.asciidoc[]
 
 include::if-then-based-grouping.asciidoc[]
+
+[[contributing]]
+How to Contribute a Recipe
+==========================
+
+Recipes are generated under the same system as all TinkerPop documentation and is stored directly in the source code
+repository. TinkerPop documentation is all link:http://asciidoc.org/[asciidoc] based and can be generated locally with
+either link:http://tinkerpop.apache.org/docs/x.y.z/dev/developer/#building-testing[shell script/Maven] or
+link:http://tinkerpop.apache.org/docs/3.2.0-incubating/dev/developer/#docker-integration[Docker] build commands. Once
+changes are complete, submit a pull request for review by TinkerPop committers.
+
+NOTE: Please review existing recipes and attempt to conform to their writing and visual style. It may also be a good
+idea to discuss ideas for a recipe on the link:http://mail-archives.apache.org/mod_mbox/incubator-tinkerpop-dev/[developer mailing list]
+prior to starting work on it, as the community might provide insight on the approach and idea that would be helpful.
+It is preferable that a link:issues.apache.org/jira/browse/TINKERPOP[JIRA issue] be opened that describes the nature
+of the recipe so that the eventual pull request can be bound to that issue.
+
+To contribute a recipe, first clone the repository:
+
+[source, shell]
+git clone https://github.com/apache/incubator-tinkerpop.git
+
+The recipes can be found in this directory:
+
+[source, shell]
+ls docs/src/recipes
+
+Each recipe exists within a separate `.asciidoc` file.  The file name should match the name of the recipe. Recipe names
+should be short, but descriptive (as they need to fit in the left-hand table of contents when generated). The
+`index.asciidoc` is the parent document that "includes" the content of each individual recipe file. A recipe file is
+included in the `index.asciidoc` with an entry like this: `include::my-recipe.asciidoc[]`
+
+Documentation should be generated locally for review prior to submitting a pull request. TinkerPop documentation is
+"live" in that it is bound to a specific version when generated. Furthermore, code examples (those that are
+`gremlin-groovy` based) are executed at document generation time with the results written directly into the output.
+The following command will generate the documentation with:
+
+[source,shell]
+bin/process-docs.sh
+
+The generated documentation can be found at `target/docs/htmlsingle/recipes`. This process can be long on the first
+run of the documentation as it is generating all of the documentation locally (e.g. reference documentation,
+tutorials, etc). To generate just the recipes, follow this process:
+
+[source,shell]
+bin/process-docs.sh --dryRun               <1>
+rm -r target/postprocess-asciidoc/recipes  <2>
+bin/process-docs.sh                        <3>
+
+<1> That command will quickly generate all of the documentation, but it does not do the code example execution (which is
+the "slow" part).
+<2> Delete the recipes directory, which forces a fresh copy of the recipes to be generated.
+<3> Process all of the documentation that is "new" (i.e. the fresh copy of recipes).
+
+The `bin/process-docs.sh` approach requires that Hadoop is installed. To avoid that prerequisite, try using Docker:
+
+[source,shell]
+docker/build.sh -d
+
+The downside to using Docker is that the process will take longer as each run will require the entire documentation set
+to be generated.
+
+The final step to submitting a recipe is to issue a link:https://help.github.com/articles/using-pull-requests/[pull request through GitHub].
+It is helpful to prefix the name of the pull request with the JIRA issue number, so that TinkerPop's automation between
+GitHub and JIRA are linked.  As mentioned earlier in this section, the recipe will go under review by TinkerPop
+committers prior to merging. This process may take several days to complete. We look forward to receiving your
+submissions!
+
+