You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by dk...@apache.org on 2016/06/09 16:47:18 UTC
[37/50] [abbrv] incubator-tinkerpop git commit: Break apart the
developer docs a bit into new sections CTR
Break apart the developer docs a bit into new sections 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/2c092c89
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/tree/2c092c89
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/diff/2c092c89
Branch: refs/heads/TINKERPOP-1331
Commit: 2c092c89760d539f477517e4a3a80c2c23267237
Parents: 1f0c34f
Author: Stephen Mallette <sp...@genoprime.com>
Authored: Wed Jun 8 09:01:24 2016 -0400
Committer: Stephen Mallette <sp...@genoprime.com>
Committed: Wed Jun 8 09:01:24 2016 -0400
----------------------------------------------------------------------
docs/src/dev/developer/contributing.asciidoc | 440 +------------------
.../developer/development-environment.asciidoc | 98 +++++
docs/src/dev/developer/for-committers.asciidoc | 364 +++++++++++++++
docs/src/dev/developer/index.asciidoc | 12 +
4 files changed, 476 insertions(+), 438 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/2c092c89/docs/src/dev/developer/contributing.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/dev/developer/contributing.asciidoc b/docs/src/dev/developer/contributing.asciidoc
index bf20f01..5f705da 100644
--- a/docs/src/dev/developer/contributing.asciidoc
+++ b/docs/src/dev/developer/contributing.asciidoc
@@ -38,7 +38,7 @@ Mailing List Participation
~~~~~~~~~~~~~~~~~~~~~~~~~~
TinkerPop has two mailing lists: link:https://groups.google.com/forum/#!forum/gremlin-users[gremlin-users] and
-link:https://lists.apache.org/list.html?dev@tinkerpop.apache.org[dev]. Subscribing to and
+pass:[<a href="https://lists.apache.org/list.html?dev@tinkerpop.apache.org">dev</a>]. Subscribing to and
participating on one or both of these mailing lists is a great way to contribute to TinkerPop. Helping users with their
problems by answering their questions on gremlin-users is a great help to the community and an easy way for
the community to become familiar with the contributor.
@@ -221,440 +221,4 @@ and resolving the conflicts by hand, then pushing the result to your branch. Or
and force pushing the branch.
. Try to be responsive to the discussion rather than let days pass between replies
-On successful review, the *pull request will be merged* to the main repository and the JIRA issue will be closed.
-
-[[building-testing]]
-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 must be running and link:http://www.grymoire.com/Unix/Awk.html[awk] version `4.0.1` is required): `bin/process-docs.sh`
-** Build AsciiDocs (but don't evaluate code blocks): `bin/process-docs.sh --dryRun`
-** Build AsciiDocs (but don't evaluate code blocks in specific files): `bin/process-docs.sh --dryRun docs/src/reference/the-graph.asciidoc,docs/src/tutorial/getting-started,...`
-** Build AsciiDocs (but evaluate code blocks only in specific files): `bin/process-docs.sh --fullRun docs/src/reference/the-graph.asciidoc,docs/src/tutorial/getting-started,...`
-** Process a single AsciiDoc file: +pass:[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.
-** 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`
-
-[[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 invokation
-of the Docker script is expected to take some time.
-
-The script can be found under `PROJECT_HOME/docker/build.sh`. The following tasks are currently
-supported:
-
-* run standard test suite
-* run integration tests
-* build Java docs
-* build user docs
-
-A list of command line options is provided by `docker/build.sh --help`. The container will install,
-configure and start all required dependencies, such as Hadoop.
-
-If the container is used to generate the user docs, it will start a web server and show the URL that
-is used to host the HTML docs.
-
-After finishing all tasks, the script will immediately destroy the container.
-
-IDE Setup with Intellij
------------------------
-
-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:
-
-. Build `gremlin-shaded` from the command line with `mvn clean install`.
-. Right-click on the `gremlin-shaded` module in the project viewer of Intellij and select "Remove module".
-. 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).
-. 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 link:http://plugins.jetbrains.com/plugin/7442?pr=idea[GMavenPlus Intellij plugin].
-
-For Committers
---------------
-
-image::business-gremlin.png[width=400]
-
-The guidelines that follow apply to those with commit access to the main repository:
-
-Communication
-~~~~~~~~~~~~~
-
-TinkerPop has a link:http://groups.google.com/group/gremlin-users[user mailing list] and a
-link:http://mail-archives.apache.org/mod_mbox/incubator-tinkerpop-dev/[developer mailing list]. As a committer,
-it is a good idea to join both.
-
-It would also be helpful to join the public link:https://s.apache.org/tinkerpop[TinkerPop HipChat room] for developer
-discussion. This helps contributors to communicate in a more real-time way. Anyone can join as a guest, but for
-regular contributors it may be best to request that an Apache HipChat account be created.
-
-Occasionally, online meetings via video conference are held. These meetings are schedule via the dev mailing list
-about a week before they are to occur to find a day and time that is available for those interested in attending.
-On the day of the meeting, the meeting organizer will create a Google Hangout (or similar video conferencing link) to
-post to the TinkerPop room in HipChat. At that point, all who are interested can attend. Meeting minutes should be
-taken and added to the <<meetings,Meetings>> section of this document using the pattern already established.
-
-Release Notes
-~~~~~~~~~~~~~
-
-There is a two-pronged approach to maintaining the change log and preparing the release notes.
-
-1. For work that is documented in JIRA, run the release notes report to include all of
-the tickets targeted for a specific release. This report can be included in the
-release announcement.
-
-2. The manual change log (`CHANGELOG.asciidoc`) can be used to highlight large
-changes, describe themes (e.g. "We focused on performance improvements") or to
-give voice to undocumented changes.
-
-Given the dependence on the JIRA report for generating additions to the `CHANGELOG.asciidoc`,
-which uses the title of the issue as the line presented in the release note report, titles should
-be edited prior to release to be useful in that context. In other words, an issue title should
-be understandable as a change in the fewest words possible while still conveying the gist of the
-change.
-
-Changes that break the public APIs should be marked with a "breaking" label and should be
-distinguished from other changes in the release notes.
-
-Branches
-~~~~~~~~
-
-The "master" branch is used for the main line of development and release branches are constructed as needed
-for ongoing maintenance work. If new to the project or are returning to it after some time away, it may be good
-to send an email to the developer mailing list (or ask on HipChat) to find out what the current operating branches
-are.
-
-Other branches may be created for collaborating on features or for RFC's that other developers may want to inspect.
-It is suggested that the JIRA issue ID be used as the prefix, since that triggers certain automation, and it provides a
-way to account for the branch lifecycle, i.e. "Who's branch is this, and can I delete it?"
-
-For branches that are NOT associated with JIRA issues, developers should utilize their Apache ID as
-a branch name prefix. This provides a unique namespace, and also a way to account for the branch lifecycle.
-
-Developers should remove their own branches when they are no longer needed.
-
-Tags
-~~~~
-
-Tags are used for milestones, release candidates, and approved releases. Please refrain from creating arbitrary
-tags, as they produce permanent clutter.
-
-Issue Tracker Conventions
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-TinkerPop uses Apache JIRA as its link:https://issues.apache.org/jira/browse/TINKERPOP[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" with two exceptions:
-** The "breaking" label which marks an issue as one that is representative of a change in the API that might
-affect users or providers. This label is important when organizing release notes.
-** The "deprecation" label which is assigned to an issue that is about removing a deprecated portion of the API.
-* The "affects/fix version(s)" fields should be appropriately set, where the "fix version" implies the version on
-which that particular issue will completed. This is a field usually only set by committers.
-* The "priority" field can be arbitrarily applied with one exception. The "trivial" option should be reserved for
-tasks that are "easy" for a potential new contributor to jump into and do not have significant impact to urgently
-required improvements.
-
-Code Style
-~~~~~~~~~~
-
-Contributors should examine the current code base to determine what the code style patterns are and should match their
-style to what is already present. Of specific note however, TinkerPop does not use "import wildcards" - IDEs should
-be adjusted accordingly to not auto-wildcard the imports.
-
-Build Server
-~~~~~~~~~~~~
-
-TinkerPop uses both link:https://travis-ci.com/[Travis] and link:https://www.appveyor.com/[AppVeyor] for
-link:https://en.wikipedia.org/wiki/Continuous_integration[CI] services. Travis validates builds on Ubuntu, while
-AppVeyor validates builds on Windows. The build statuses can be found here:
-
-* link:https://travis-ci.org/apache/incubator-tinkerpop[Travis Build Status]
-* link:https://ci.appveyor.com/project/ApacheSoftwareFoundation/incubator-tinkerpop[AppVeyor Build Status]
-
-Note that the CI process does not run integration tests or include Neo4j-related tests as those tests would likely
-exceed the allowable times for builds on these servers.
-
-Deprecation
-~~~~~~~~~~~
-
-When possible, committers should avoid direct "breaking" change (e.g. removing a method from a class) and favor
-deprecation. Deprecation should come with sufficient documentation and notice especially when the change involves
-public APIs that might be utilized by users or implemented by providers:
-
-* Mark the code with the `@Deprecated` annotation.
-* Use javadoc to further document the change with the following content:
-** `@deprecated As of release x.y.z, replaced by {@link SomeOtherClass#someNewMethod()}` - if the method is not
-replaced then the comment can simply read "not replaced". Additional comments that provide more context are
-encouraged.
-** `@see <a href="https://issues.apache.org/jira/browse/TINKERPOP-XXX">TINKERPOP-XXX</a>` - supply a link to the
-JIRA issue for reference.
-* Be sure that deprecated methods are still under test - consider using javadoc/comments in the tests themselves to
-call out this fact.
-* Create a new JIRA issue to track removal of the deprecation for future evaluation - this issue should have the
-"breaking" label as well as a "deprecation" label.
-* Update the "upgrade documentation" to reflect the API change and how the reader should resolve it.
-
-The JIRA issues that track removal of deprecated methods should be periodically evaluated to determine if it is
-prudent to schedule them into a release.
-
-Developing Tests
-~~~~~~~~~~~~~~~~
-
-TinkerPop has a wide variety of test types that help validate its internal code as well as external provider code.
-There are "unit tests" and "integration tests". Unit tests execute on standard runs of `mvn clean install`. These
-tests tend to run quickly and provide a reasonable level of coverage and confidence in the code base. Integration
-tests are disabled by default and must be explicitly turned on with a special build property by adding
-`-DskipIntegrationTests=false` to the `mvn` execution. Integration tests run slower and may require external
-components to be running when they are executed. They are "marked" as separate from unit tests by inclusion of the
-suffix "IntegrateTest".
-
-Here are some other points to consider when developing tests:
-
-* Avoid use of `println` in tests and prefer use of a SLF4j `Logger` instance so that outputs can be controlled in a
-standard way.
-* If it is necessary to create files on the filesystem, do not hardcode directories - instead, use the `TestHelper` to
-create directory structures. `TestHelper` will properly create file system structure in the appropriate build
-directory thus allowing proper clean-up between test runs.
-* If writing tests in one of the test suites, like `gremlin-test`, it is important to remember that if a new `Graph`
-instance is constructed within the test manually, that it be closed on exit of that test. Failing to do this cleanup
-can cause problems for some graph providers.
-* Tests that are designed to use a `GraphProvider` implementation in conjunction with `AbstractGremlinTest` _and_ are
-in the `/test` directory should not be named with `Test` as the suffix, as this will cause them to execute in some
-environments without a `GraphProvider` being initialized by a suite. These types of tests should be suffixed with
-`Check` instead. Please see link:https://github.com/apache/incubator-tinkerpop/blob/e32a4187e4f25e290aabe14007f9087c48a06521/neo4j-gremlin/src/test/java/org/apache/tinkerpop/gremlin/neo4j/structure/NativeNeo4jStructureCheck.java[NativeNeo4jStructureCheck]
-for an example.
-
-Gremlin Language Test Cases
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When writing a test case for a Gremlin step, be sure to use the following conventions.
-
-* The name of the traversal generator should start with `get`, use `X` for brackets, `_` for space, and the Gremlin-Groovy sugar syntax.
-** `get_g_V_hasLabelXpersonX_groupXaX_byXageX_byXsumX_name()`
-* When creating a test for a step that has both a barrier and sideEffect form (e.g. `group()`, `groupCount()`, etc.), test both representations.
-** `get_g_V_groupCount_byXnameX()`
-** `get_g_V_groupCountXaX_byXnameX_capXaX()`
-* The name of the actual test case should be the name of the traversal generator minus the `get_` prefix.
-* The Gremlin-Groovy version of the test should use the sugar syntax in order to test sugar (as Gremlin-Java8 tests test standard syntax).
-** `g.V.age.sum`
-* Avoid using lambdas in the test case unless that is explicitly what is being tested as OLAP systems will typically not be able to execute those tests.
-* `AbstractGremlinProcessTest` has various static methods to make writing a test case easy.
-** `checkResults(Arrays.asList("marko","josh"), traversal)`
-** `checkMap(new HashMap<String,Long>() {{ put("marko",1l); }}, traversal.next())`
-
-[[rtc]]
-Review then Commit
-~~~~~~~~~~~~~~~~~~
-
-Code modifications must go through a link:http://www.apache.org/foundation/glossary.html#ReviewThenCommit[review-then-committ] (RTC)
-process before being merged into a release branch. All committers should follow the pattern below, where "you" refers to the
-committer wanting to put code into a release branch.
-
-* Make a JIRA ticket for the software problem you want to solve (i.e. a fix).
-* Fork the release branch that the fix will be put into.
-** The branch name should be the JIRA issue identifier (e.g. `TINKERPOP-XXX`).
-* Develop your fix in your branch.
-* When your fix is complete and ready to merge, issue a link:https://git-scm.com/docs/git-request-pull[pull request].
-** Be certain that the test suite is passing.
-** If you updated documentation, be sure that the `process-docs.sh` is building the documentation correctly.
-* Before you can merge your branch into the release branch, you must have at least 3 +1 link:http://www.apache.org/foundation/glossary.html#ConsensusApproval[consensus votes].
-** Please see the Apache Software Foundations regulations regarding link:http://www.apache.org/foundation/voting.html#votes-on-code-modification[Voting on Code Modifications].
-* Votes are issued by TinkerPop committers as comments to the pull request.
-* Once 3 +1 votes are received, you are responsible for merging to the release branch and handling any merge conflicts.
-** If there is a higher version release branch that requires your fix (e.g. `3.y-1.z` fix going to a `3.y.z` release), be sure to merge to that release branch as well.
-* Be conscious of deleting your branch if it is no longer going to be used so stale branches don't pollute the repository.
-
-NOTE: These steps also generally apply to external pull requests from those who are not official Apache committers. In
-this case, the person responsible for the merge after voting is typically the first person available
-who is knowledgeable in the area that the pull request affects. Any additional coordination on merging can be handled
-via the pull request comment system.
-
-The following exceptions to the RTC (review-then-commit) model presented above are itemized below. It is up to the
-committer to self-regulate as the itemization below is not complete and only hints at the types of commits that do not
-require a review.
-
-* You are responsible for a release and need to manipulate files accordingly for the release.
-** `Gremlin.version()`, CHANGELOG dates, `pom.xml` version bumps, etc.
-* You are doing an minor change and it is obvious that an RTC is not required (would be a pointless burden to the community).
-** The fix is under the link:http://www.apache.org/foundation/glossary.html#CommitThenReview[commit-then-review] (CTR) policy and lazy consensus is sufficient, where a single -1 vote requires you to revert your changes.
-** Adding a test case, fixing spelling/grammar mistakes in the documentation, fixing LICENSE/NOTICE/etc. files, fixing a minor issue in an already merged branch.
-
-When the committer chooses CTR, it is considered good form to include something in the commit message that explains
-that CTR was invoked and the reason for doing so. For example, "Invoking CTR as this change encompasses minor
-adjustments to text formatting."
-
-Pull Request Format
-^^^^^^^^^^^^^^^^^^^
-
-When you submit a pull request, be sure it uses the following style.
-
-* The title of the pull request is the JIRA ticket number + "colon" + the title of the JIRA ticket.
-* The first line of the pull request message should contain a link to the JIRA ticket.
-* Discuss what you did to solve the problem articulated in the JIRA ticket.
-* Discuss any "extra" work done that go beyond the assumed requirements of the JIRA ticket.
-* Be sure to explain what you did to prove that the issue is resolved.
-** Test cases written.
-** Integration tests run (if required for the work accomplished).
-** Documentation building (if required for the work accomplished).
-** Any manual testing (though this should be embodied in a test case).
-* Notes about what you will do when you merge to the respective release branch (e.g. update CHANGELOG).
-** These types of "on merge tweaks" are typically done to extremely dynamic files to combat and merge conflicts.
-* If you are a TinkerPop committer, you can VOTE on your own pull request, so please do so.
-
-[[dependencies]]
-Dependencies
-~~~~~~~~~~~~
-
-There are many dependencies on other open source libraries in TinkerPop modules. When adding dependencies or
-altering the version of a dependency, developers must consider the implications that may apply to the TinkerPop
-LICENSE and NOTICE files. There are two implications to consider:
-
-. Does the dependency fit an Apache _approved_ license?
-. Given the addition or modification to a dependency, does it mean any change for TinkerPop LICENSE and NOTICE files?
-
-Understanding these implications is important for insuring that TinkerPop stays compliant with the Apache 2 license
-that it releases under.
-
-Regarding the first item, refer to the Apache Legal for a list of link:http://www.apache.org/legal/resolved.html[approved licenses]
-that are compatible with the Apache 2 license.
-
-The second item requires a bit more effort to follow. The Apache website offers a
-link:http://www.apache.org/dev/licensing-howto.html[how-to guide] on the approach to maintaining appropriate LICENSE
-and NOTICE files, but this guide is designed to offer some more specific guidance as it pertains to TinkerPop
-and its distribution.
-
-To get started, TinkerPop has both "source" and "binary" LICENSE/NOTICE files:
-
-* Source LICENSE/NOTICE relate to files packaged with the released source code distribution:
-link:https://github.com/apache/incubator-tinkerpop/blob/master/LICENSE[LICENSE] / link:https://github.com/apache/incubator-tinkerpop/blob/master/NOTICE[NOTICE]
-* Binary LICENSE/NOTICE relate to files packaged with the released binary distributions:
-** Gremlin Console link:https://github.com/apache/incubator-tinkerpop/blob/master/gremlin-console/src/main/LICENSE[LICENSE]
-/ link:https://github.com/apache/incubator-tinkerpop/blob/master/gremlin-console/src/main/NOTICE[NOTICE]
-** Gremlin Server link:https://github.com/apache/incubator-tinkerpop/blob/master/gremlin-server/src/main/LICENSE[LICENSE]
-/ link:https://github.com/apache/incubator-tinkerpop/blob/master/gremlin-server/src/main/NOTICE[NOTICE]
-
-Source LICENSE and NOTICE
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-As dependencies are not typically added to the source distribution (i.e. the source zip distribution), there is
-typically no need to edit source LICENSE/NOTICE when editing a TinkerPop `pom.xml`. These files only need to be edited
-if the distribution has a file added to it. Such a situation may arise from several scenarios, but it would most
-likely come from the addition of a source file from another library.
-
-* If the file being bundled is Apache licensed, then add an entry to NOTICE.
-* If the file being bundled is under a different approved license, then add an entry to LICENSE and include a copy of
-that LICENSE in the root `/licenses` directory of the code repository.
-
-Binary LICENSE and NOTICE
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The binary LICENSE/NOTICE is perhaps most impacted by changes to the various `pom.xml` files. After altering the
-`pom.xml` file of any module, build both Gremlin Console and Gremlin Server and examine the contents of both binary
-distributions, either:
-
-* target/apache-gremlin-console-x.y.z-distribution.zip
-* target/apache-gremlin-server-x.y.z-distribution.zip
-
-Apache licensed software does not need to be included in LICENSE, but if the new dependency is an Apache-approved
-license (e.g. BSD, MIT) then it should be added in the pattern already defined. A copy of the LICENSE should be
-added to the `<project>/static/licenses` directory of the code repository.
-
-To determine if changes are required to the NOTICE, first check if the bundled jar has a NOTICE file in it (typically
-found in `/META-INF` directory of the jar).
-
-* If the bundled file does not have a NOTICE, then no changes to TinkerPop's NOTICE are required.
-* If the NOTICE of the file being bundled is NOT Apache licensed, then there is no change to TinkerPop's NOTICE.
-* If the NOTICE of the file being bundled is Apache licensed, then include the copyright notification in TinkerPop's
-NOTICE.
-* If the NOTICE of the file being bundled is Apache licensed AND is an Apache Software Foundation project, then
-ONLY include the portion of that NOTICE in TinkerPop's NOTICE that is unrelated to the Apache boilerplate NOTICE.
-If there is no such portion that is different than the boilerplate then this NOTICE can be excluded (i.e. don't
-alter TinkerPop's NOTICE at all).
-
-Please refer to the link:http://www.apache.org/dev/licensing-howto.html#mod-notice[Modifications to Notice] section
-of the Apache "Licensing How-to" for more information.
-
-[[documentation]]
-Documentation
-~~~~~~~~~~~~~
-
-The documentation for TinkerPop is stored in the git repository in `docs/src/` and are then split into several
-subdirectories, each representing a "book" (or its own publishable body of work). If a new AsciiDoc file is added to
-a book, then it should also be included in the `index.asciidoc` file for that book, otherwise the preprocessor will
-ignore it. Likewise, if a whole new book (subdirectory) is added, it must include an `index.asciidoc` file to be
-recognized by the AsciiDoc preprocessor.
-
-Adding a book also requires a change to the root `pom.xml` file. Find the "asciidoc" Maven profile and add a new
-`<execution>` to the `asciidoctor-maven-plugin` configuration. For each book in `docs/src/`, there should be a
-related `<execution>` that generates the HTML from the AsciiDoc. Follows the patterns already established by
-the existing `<execution>` entries, paying special attention to the pathing of the '<sourceDirectory>',
-`<outputDirectory>` and `<imagesdir>`. Note that the `<outputDirectory>` represents where the book will exist when
-uploaded to the server and should preserve the directory structure in git as referenced in `<sourceDirectory>`.
-
-Please see the <<building-testing,Building and Testing>> section for more information on how to generate the
-documentation.
-
-[[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
-resources. That file gets copied to the `target/test-classes` on build and surefire and failsafe plugins in maven
-are then configured to point at that area of the file system for those configuration files. The properties files
-can be edited to fine tune control of the log output, but generally speaking the current configuration is likely
-best for everyone's general purposes, so if changes are made please revert them prior to commit.
-
-For Providers
--------------
-
-Graph Providers are those who develop third-party systems and libraries on top of the various TinkerPop APIs and
-protocols. They manage their projects independently of TinkerPop in separate repositories. Additional details for
-providers can be found in the link:http://tinkerpop.apache.org/docs/x.y.z/dev/provider/[Provider Documentation].
+On successful review, the *pull request will be merged* to the main repository and the JIRA issue will be closed.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/2c092c89/docs/src/dev/developer/development-environment.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/dev/developer/development-environment.asciidoc b/docs/src/dev/developer/development-environment.asciidoc
new file mode 100644
index 0000000..3bb6613
--- /dev/null
+++ b/docs/src/dev/developer/development-environment.asciidoc
@@ -0,0 +1,98 @@
+////
+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.
+////
+Development Environment
+=======================
+
+[[building-testing]]
+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 must be running and link:http://www.grymoire.com/Unix/Awk.html[awk] version `4.0.1` is required): `bin/process-docs.sh`
+** Build AsciiDocs (but don't evaluate code blocks): `bin/process-docs.sh --dryRun`
+** Build AsciiDocs (but don't evaluate code blocks in specific files): `bin/process-docs.sh --dryRun docs/src/reference/the-graph.asciidoc,docs/src/tutorial/getting-started,...`
+** Build AsciiDocs (but evaluate code blocks only in specific files): `bin/process-docs.sh --fullRun docs/src/reference/the-graph.asciidoc,docs/src/tutorial/getting-started,...`
+** Process a single AsciiDoc file: +pass:[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.
+** 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`
+
+[[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 invokation
+of the Docker script is expected to take some time.
+
+The script can be found under `PROJECT_HOME/docker/build.sh`. The following tasks are currently
+supported:
+
+* run standard test suite
+* run integration tests
+* build Java docs
+* build user docs
+
+A list of command line options is provided by `docker/build.sh --help`. The container will install,
+configure and start all required dependencies, such as Hadoop.
+
+If the container is used to generate the user docs, it will start a web server and show the URL that
+is used to host the HTML docs.
+
+After finishing all tasks, the script will immediately destroy the container.
+
+IDE Setup with Intellij
+-----------------------
+
+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:
+
+. Build `gremlin-shaded` from the command line with `mvn clean install`.
+. Right-click on the `gremlin-shaded` module in the project viewer of Intellij and select "Remove module".
+. 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).
+. 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 link:http://plugins.jetbrains.com/plugin/7442?pr=idea[GMavenPlus Intellij plugin].
http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/2c092c89/docs/src/dev/developer/for-committers.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/dev/developer/for-committers.asciidoc b/docs/src/dev/developer/for-committers.asciidoc
new file mode 100644
index 0000000..49f1899
--- /dev/null
+++ b/docs/src/dev/developer/for-committers.asciidoc
@@ -0,0 +1,364 @@
+////
+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.
+////
+For Committers
+==============
+
+image::business-gremlin.png[width=400]
+
+The guidelines that follow apply to those with commit access to the main repository:
+
+Communication
+-------------
+
+TinkerPop has a link:http://groups.google.com/group/gremlin-users[user mailing list] and a
+link:http://mail-archives.apache.org/mod_mbox/incubator-tinkerpop-dev/[developer mailing list]. As a committer,
+it is a good idea to join both.
+
+It would also be helpful to join the public link:https://s.apache.org/tinkerpop[TinkerPop HipChat room] for developer
+discussion. This helps contributors to communicate in a more real-time way. Anyone can join as a guest, but for
+regular contributors it may be best to request that an Apache HipChat account be created.
+
+Occasionally, online meetings via video conference are held. These meetings are schedule via the dev mailing list
+about a week before they are to occur to find a day and time that is available for those interested in attending.
+On the day of the meeting, the meeting organizer will create a Google Hangout (or similar video conferencing link) to
+post to the TinkerPop room in HipChat. At that point, all who are interested can attend. Meeting minutes should be
+taken and added to the <<meetings,Meetings>> section of this document using the pattern already established.
+
+Release Notes
+-------------
+
+There is a two-pronged approach to maintaining the change log and preparing the release notes.
+
+1. For work that is documented in JIRA, run the release notes report to include all of
+the tickets targeted for a specific release. This report can be included in the
+release announcement.
+
+2. The manual change log (`CHANGELOG.asciidoc`) can be used to highlight large
+changes, describe themes (e.g. "We focused on performance improvements") or to
+give voice to undocumented changes.
+
+Given the dependence on the JIRA report for generating additions to the `CHANGELOG.asciidoc`,
+which uses the title of the issue as the line presented in the release note report, titles should
+be edited prior to release to be useful in that context. In other words, an issue title should
+be understandable as a change in the fewest words possible while still conveying the gist of the
+change.
+
+Changes that break the public APIs should be marked with a "breaking" label and should be
+distinguished from other changes in the release notes.
+
+Branches
+--------
+
+The "master" branch is used for the main line of development and release branches are constructed as needed
+for ongoing maintenance work. If new to the project or are returning to it after some time away, it may be good
+to send an email to the developer mailing list (or ask on HipChat) to find out what the current operating branches
+are.
+
+Other branches may be created for collaborating on features or for RFC's that other developers may want to inspect.
+It is suggested that the JIRA issue ID be used as the prefix, since that triggers certain automation, and it provides a
+way to account for the branch lifecycle, i.e. "Who's branch is this, and can I delete it?"
+
+For branches that are NOT associated with JIRA issues, developers should utilize their Apache ID as
+a branch name prefix. This provides a unique namespace, and also a way to account for the branch lifecycle.
+
+Developers should remove their own branches when they are no longer needed.
+
+Tags
+----
+
+Tags are used for milestones, release candidates, and approved releases. Please refrain from creating arbitrary
+tags, as they produce permanent clutter.
+
+Issue Tracker Conventions
+-------------------------
+
+TinkerPop uses Apache JIRA as its link:https://issues.apache.org/jira/browse/TINKERPOP[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" with two exceptions:
+** The "breaking" label which marks an issue as one that is representative of a change in the API that might
+affect users or providers. This label is important when organizing release notes.
+** The "deprecation" label which is assigned to an issue that is about removing a deprecated portion of the API.
+* The "affects/fix version(s)" fields should be appropriately set, where the "fix version" implies the version on
+which that particular issue will completed. This is a field usually only set by committers.
+* The "priority" field can be arbitrarily applied with one exception. The "trivial" option should be reserved for
+tasks that are "easy" for a potential new contributor to jump into and do not have significant impact to urgently
+required improvements.
+
+Code Style
+----------
+
+Contributors should examine the current code base to determine what the code style patterns are and should match their
+style to what is already present. Of specific note however, TinkerPop does not use "import wildcards" - IDEs should
+be adjusted accordingly to not auto-wildcard the imports.
+
+Build Server
+------------
+
+TinkerPop uses both link:https://travis-ci.com/[Travis] and link:https://www.appveyor.com/[AppVeyor] for
+link:https://en.wikipedia.org/wiki/Continuous_integration[CI] services. Travis validates builds on Ubuntu, while
+AppVeyor validates builds on Windows. The build statuses can be found here:
+
+* link:https://travis-ci.org/apache/incubator-tinkerpop[Travis Build Status]
+* link:https://ci.appveyor.com/project/ApacheSoftwareFoundation/incubator-tinkerpop[AppVeyor Build Status]
+
+Note that the CI process does not run integration tests or include Neo4j-related tests as those tests would likely
+exceed the allowable times for builds on these servers.
+
+Deprecation
+-----------
+
+When possible, committers should avoid direct "breaking" change (e.g. removing a method from a class) and favor
+deprecation. Deprecation should come with sufficient documentation and notice especially when the change involves
+public APIs that might be utilized by users or implemented by providers:
+
+* Mark the code with the `@Deprecated` annotation.
+* Use javadoc to further document the change with the following content:
+** `@deprecated As of release x.y.z, replaced by {@link SomeOtherClass#someNewMethod()}` - if the method is not
+replaced then the comment can simply read "not replaced". Additional comments that provide more context are
+encouraged.
+** `@see <a href="https://issues.apache.org/jira/browse/TINKERPOP-XXX">TINKERPOP-XXX</a>` - supply a link to the
+JIRA issue for reference.
+* Be sure that deprecated methods are still under test - consider using javadoc/comments in the tests themselves to
+call out this fact.
+* Create a new JIRA issue to track removal of the deprecation for future evaluation - this issue should have the
+"breaking" label as well as a "deprecation" label.
+* Update the "upgrade documentation" to reflect the API change and how the reader should resolve it.
+
+The JIRA issues that track removal of deprecated methods should be periodically evaluated to determine if it is
+prudent to schedule them into a release.
+
+Developing Tests
+----------------
+
+TinkerPop has a wide variety of test types that help validate its internal code as well as external provider code.
+There are "unit tests" and "integration tests". Unit tests execute on standard runs of `mvn clean install`. These
+tests tend to run quickly and provide a reasonable level of coverage and confidence in the code base. Integration
+tests are disabled by default and must be explicitly turned on with a special build property by adding
+`-DskipIntegrationTests=false` to the `mvn` execution. Integration tests run slower and may require external
+components to be running when they are executed. They are "marked" as separate from unit tests by inclusion of the
+suffix "IntegrateTest".
+
+Here are some other points to consider when developing tests:
+
+* Avoid use of `println` in tests and prefer use of a SLF4j `Logger` instance so that outputs can be controlled in a
+standard way.
+* If it is necessary to create files on the filesystem, do not hardcode directories - instead, use the `TestHelper` to
+create directory structures. `TestHelper` will properly create file system structure in the appropriate build
+directory thus allowing proper clean-up between test runs.
+* If writing tests in one of the test suites, like `gremlin-test`, it is important to remember that if a new `Graph`
+instance is constructed within the test manually, that it be closed on exit of that test. Failing to do this cleanup
+can cause problems for some graph providers.
+* Tests that are designed to use a `GraphProvider` implementation in conjunction with `AbstractGremlinTest` _and_ are
+in the `/test` directory should not be named with `Test` as the suffix, as this will cause them to execute in some
+environments without a `GraphProvider` being initialized by a suite. These types of tests should be suffixed with
+`Check` instead. Please see link:https://github.com/apache/incubator-tinkerpop/blob/e32a4187e4f25e290aabe14007f9087c48a06521/neo4j-gremlin/src/test/java/org/apache/tinkerpop/gremlin/neo4j/structure/NativeNeo4jStructureCheck.java[NativeNeo4jStructureCheck]
+for an example.
+
+Gremlin Language Test Cases
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When writing a test case for a Gremlin step, be sure to use the following conventions.
+
+* The name of the traversal generator should start with `get`, use `X` for brackets, `_` for space, and the Gremlin-Groovy sugar syntax.
+** `get_g_V_hasLabelXpersonX_groupXaX_byXageX_byXsumX_name()`
+* When creating a test for a step that has both a barrier and sideEffect form (e.g. `group()`, `groupCount()`, etc.), test both representations.
+** `get_g_V_groupCount_byXnameX()`
+** `get_g_V_groupCountXaX_byXnameX_capXaX()`
+* The name of the actual test case should be the name of the traversal generator minus the `get_` prefix.
+* The Gremlin-Groovy version of the test should use the sugar syntax in order to test sugar (as Gremlin-Java8 tests test standard syntax).
+** `g.V.age.sum`
+* Avoid using lambdas in the test case unless that is explicitly what is being tested as OLAP systems will typically not be able to execute those tests.
+* `AbstractGremlinProcessTest` has various static methods to make writing a test case easy.
+** `checkResults(Arrays.asList("marko","josh"), traversal)`
+** `checkMap(new HashMap<String,Long>() {{ put("marko",1l); }}, traversal.next())`
+
+[[rtc]]
+Review then Commit
+------------------
+
+Code modifications must go through a link:http://www.apache.org/foundation/glossary.html#ReviewThenCommit[review-then-committ] (RTC)
+process before being merged into a release branch. All committers should follow the pattern below, where "you" refers to the
+committer wanting to put code into a release branch.
+
+* Make a JIRA ticket for the software problem you want to solve (i.e. a fix).
+* Fork the release branch that the fix will be put into.
+** The branch name should be the JIRA issue identifier (e.g. `TINKERPOP-XXX`).
+* Develop your fix in your branch.
+* When your fix is complete and ready to merge, issue a link:https://git-scm.com/docs/git-request-pull[pull request].
+** Be certain that the test suite is passing.
+** If you updated documentation, be sure that the `process-docs.sh` is building the documentation correctly.
+* Before you can merge your branch into the release branch, you must have at least 3 +1 link:http://www.apache.org/foundation/glossary.html#ConsensusApproval[consensus votes].
+** Please see the Apache Software Foundations regulations regarding link:http://www.apache.org/foundation/voting.html#votes-on-code-modification[Voting on Code Modifications].
+* Votes are issued by TinkerPop committers as comments to the pull request.
+* Once 3 +1 votes are received, you are responsible for merging to the release branch and handling any merge conflicts.
+** If there is a higher version release branch that requires your fix (e.g. `3.y-1.z` fix going to a `3.y.z` release), be sure to merge to that release branch as well.
+* Be conscious of deleting your branch if it is no longer going to be used so stale branches don't pollute the repository.
+
+NOTE: These steps also generally apply to external pull requests from those who are not official Apache committers. In
+this case, the person responsible for the merge after voting is typically the first person available
+who is knowledgeable in the area that the pull request affects. Any additional coordination on merging can be handled
+via the pull request comment system.
+
+The following exceptions to the RTC (review-then-commit) model presented above are itemized below. It is up to the
+committer to self-regulate as the itemization below is not complete and only hints at the types of commits that do not
+require a review.
+
+* You are responsible for a release and need to manipulate files accordingly for the release.
+** `Gremlin.version()`, CHANGELOG dates, `pom.xml` version bumps, etc.
+* You are doing an minor change and it is obvious that an RTC is not required (would be a pointless burden to the community).
+** The fix is under the link:http://www.apache.org/foundation/glossary.html#CommitThenReview[commit-then-review] (CTR) policy and lazy consensus is sufficient, where a single -1 vote requires you to revert your changes.
+** Adding a test case, fixing spelling/grammar mistakes in the documentation, fixing LICENSE/NOTICE/etc. files, fixing a minor issue in an already merged branch.
+
+When the committer chooses CTR, it is considered good form to include something in the commit message that explains
+that CTR was invoked and the reason for doing so. For example, "Invoking CTR as this change encompasses minor
+adjustments to text formatting."
+
+Pull Request Format
+~~~~~~~~~~~~~~~~~~~
+
+When you submit a pull request, be sure it uses the following style.
+
+* The title of the pull request is the JIRA ticket number + "colon" + the title of the JIRA ticket.
+* The first line of the pull request message should contain a link to the JIRA ticket.
+* Discuss what you did to solve the problem articulated in the JIRA ticket.
+* Discuss any "extra" work done that go beyond the assumed requirements of the JIRA ticket.
+* Be sure to explain what you did to prove that the issue is resolved.
+** Test cases written.
+** Integration tests run (if required for the work accomplished).
+** Documentation building (if required for the work accomplished).
+** Any manual testing (though this should be embodied in a test case).
+* Notes about what you will do when you merge to the respective release branch (e.g. update CHANGELOG).
+** These types of "on merge tweaks" are typically done to extremely dynamic files to combat and merge conflicts.
+* If you are a TinkerPop committer, you can VOTE on your own pull request, so please do so.
+
+[[dependencies]]
+Dependencies
+------------
+
+There are many dependencies on other open source libraries in TinkerPop modules. When adding dependencies or
+altering the version of a dependency, developers must consider the implications that may apply to the TinkerPop
+LICENSE and NOTICE files. There are two implications to consider:
+
+. Does the dependency fit an Apache _approved_ license?
+. Given the addition or modification to a dependency, does it mean any change for TinkerPop LICENSE and NOTICE files?
+
+Understanding these implications is important for insuring that TinkerPop stays compliant with the Apache 2 license
+that it releases under.
+
+Regarding the first item, refer to the Apache Legal for a list of link:http://www.apache.org/legal/resolved.html[approved licenses]
+that are compatible with the Apache 2 license.
+
+The second item requires a bit more effort to follow. The Apache website offers a
+link:http://www.apache.org/dev/licensing-howto.html[how-to guide] on the approach to maintaining appropriate LICENSE
+and NOTICE files, but this guide is designed to offer some more specific guidance as it pertains to TinkerPop
+and its distribution.
+
+To get started, TinkerPop has both "source" and "binary" LICENSE/NOTICE files:
+
+* Source LICENSE/NOTICE relate to files packaged with the released source code distribution:
+link:https://github.com/apache/incubator-tinkerpop/blob/master/LICENSE[LICENSE] / link:https://github.com/apache/incubator-tinkerpop/blob/master/NOTICE[NOTICE]
+* Binary LICENSE/NOTICE relate to files packaged with the released binary distributions:
+** Gremlin Console link:https://github.com/apache/incubator-tinkerpop/blob/master/gremlin-console/src/main/LICENSE[LICENSE]
+/ link:https://github.com/apache/incubator-tinkerpop/blob/master/gremlin-console/src/main/NOTICE[NOTICE]
+** Gremlin Server link:https://github.com/apache/incubator-tinkerpop/blob/master/gremlin-server/src/main/LICENSE[LICENSE]
+/ link:https://github.com/apache/incubator-tinkerpop/blob/master/gremlin-server/src/main/NOTICE[NOTICE]
+
+Source LICENSE and NOTICE
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As dependencies are not typically added to the source distribution (i.e. the source zip distribution), there is
+typically no need to edit source LICENSE/NOTICE when editing a TinkerPop `pom.xml`. These files only need to be edited
+if the distribution has a file added to it. Such a situation may arise from several scenarios, but it would most
+likely come from the addition of a source file from another library.
+
+* If the file being bundled is Apache licensed, then add an entry to NOTICE.
+* If the file being bundled is under a different approved license, then add an entry to LICENSE and include a copy of
+that LICENSE in the root `/licenses` directory of the code repository.
+
+Binary LICENSE and NOTICE
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The binary LICENSE/NOTICE is perhaps most impacted by changes to the various `pom.xml` files. After altering the
+`pom.xml` file of any module, build both Gremlin Console and Gremlin Server and examine the contents of both binary
+distributions, either:
+
+* target/apache-gremlin-console-x.y.z-distribution.zip
+* target/apache-gremlin-server-x.y.z-distribution.zip
+
+Apache licensed software does not need to be included in LICENSE, but if the new dependency is an Apache-approved
+license (e.g. BSD, MIT) then it should be added in the pattern already defined. A copy of the LICENSE should be
+added to the `<project>/static/licenses` directory of the code repository.
+
+To determine if changes are required to the NOTICE, first check if the bundled jar has a NOTICE file in it (typically
+found in `/META-INF` directory of the jar).
+
+* If the bundled file does not have a NOTICE, then no changes to TinkerPop's NOTICE are required.
+* If the NOTICE of the file being bundled is NOT Apache licensed, then there is no change to TinkerPop's NOTICE.
+* If the NOTICE of the file being bundled is Apache licensed, then include the copyright notification in TinkerPop's
+NOTICE.
+* If the NOTICE of the file being bundled is Apache licensed AND is an Apache Software Foundation project, then
+ONLY include the portion of that NOTICE in TinkerPop's NOTICE that is unrelated to the Apache boilerplate NOTICE.
+If there is no such portion that is different than the boilerplate then this NOTICE can be excluded (i.e. don't
+alter TinkerPop's NOTICE at all).
+
+Please refer to the link:http://www.apache.org/dev/licensing-howto.html#mod-notice[Modifications to Notice] section
+of the Apache "Licensing How-to" for more information.
+
+[[documentation]]
+Documentation
+-------------
+
+The documentation for TinkerPop is stored in the git repository in `docs/src/` and are then split into several
+subdirectories, each representing a "book" (or its own publishable body of work). If a new AsciiDoc file is added to
+a book, then it should also be included in the `index.asciidoc` file for that book, otherwise the preprocessor will
+ignore it. Likewise, if a whole new book (subdirectory) is added, it must include an `index.asciidoc` file to be
+recognized by the AsciiDoc preprocessor.
+
+Adding a book also requires a change to the root `pom.xml` file. Find the "asciidoc" Maven profile and add a new
+`<execution>` to the `asciidoctor-maven-plugin` configuration. For each book in `docs/src/`, there should be a
+related `<execution>` that generates the HTML from the AsciiDoc. Follows the patterns already established by
+the existing `<execution>` entries, paying special attention to the pathing of the '<sourceDirectory>',
+`<outputDirectory>` and `<imagesdir>`. Note that the `<outputDirectory>` represents where the book will exist when
+uploaded to the server and should preserve the directory structure in git as referenced in `<sourceDirectory>`.
+
+Please see the <<building-testing,Building and Testing>> section for more information on how to generate the
+documentation.
+
+[[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
+resources. That file gets copied to the `target/test-classes` on build and surefire and failsafe plugins in maven
+are then configured to point at that area of the file system for those configuration files. The properties files
+can be edited to fine tune control of the log output, but generally speaking the current configuration is likely
+best for everyone's general purposes, so if changes are made please revert them prior to commit.
http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/2c092c89/docs/src/dev/developer/index.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/dev/developer/index.asciidoc b/docs/src/dev/developer/index.asciidoc
index a9eb1f3..f1c472f 100644
--- a/docs/src/dev/developer/index.asciidoc
+++ b/docs/src/dev/developer/index.asciidoc
@@ -26,6 +26,18 @@ technical information and other internal processes related to the project.
include::contributing.asciidoc[]
+include::development-environment.asciidoc[]
+
+include::for-committers.asciidoc[]
+
+For Providers
+=============
+
+Graph Providers are those who develop third-party systems and libraries on top of the various TinkerPop APIs and
+protocols. They manage their projects independently of TinkerPop in separate repositories. Additional details for
+providers can be found in the link:http://tinkerpop.apache.org/docs/x.y.z/dev/provider/[Provider Documentation].
+
+
include::release.asciidoc[]
include::administration.asciidoc[]