You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by sp...@apache.org on 2018/10/08 15:51:07 UTC
[tinkerpop] 01/03: Minor updates to dev docs
This is an automated email from the ASF dual-hosted git repository.
spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit 3ec14cbad6abc0483bae91775956ce6af812627a
Author: Stephen Mallette <sp...@genoprime.com>
AuthorDate: Mon Oct 8 11:49:55 2018 -0400
Minor updates to dev docs
Includes spelling/grammer fixes, minor process adjustments based on GitBox, and other lesser updates CTR
---
docs/src/dev/developer/contributing.asciidoc | 50 ++++++++++++++------------
docs/src/dev/developer/for-committers.asciidoc | 30 ++++++++++------
2 files changed, 46 insertions(+), 34 deletions(-)
diff --git a/docs/src/dev/developer/contributing.asciidoc b/docs/src/dev/developer/contributing.asciidoc
index 29486ed..576a652 100644
--- a/docs/src/dev/developer/contributing.asciidoc
+++ b/docs/src/dev/developer/contributing.asciidoc
@@ -37,13 +37,13 @@ link:https://cwiki.apache.org/confluence/display/SPARK/Contributing+to+Spark["Co
TinkerPop has two mailing lists: link:https://groups.google.com/forum/#!forum/gremlin-users[gremlin-users] 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
+problems by answering their questions on gremlin-users is a massive help to the community and an easy way for
the community to become familiar with the contributor.
The dev@tinkerpop.apache.org mailing list is where all design discussion, early feature announcements, release
discussions and other similar communication takes place. Having insight into the project at this level, will yield a
-lot of information about the day-to-day course of TinkerPop and many of the other ways contributors can be involved
-require a subscription to this list.
+lot of information about the day-to-day course of TinkerPop and provides a way to help shape the direction of the
+project.
=== Testing Releases
@@ -55,18 +55,19 @@ that votes of non-PMC members are considered non-binding, but are certainly cons
=== Reviewing Changes
Virtually all changes to TinkerPop's source code are performed via GitHub
-link:https://github.com/apache/tinkerpop/pulls[pull requests]. When a pull request is issue it undergoes a
-<<rtc,review process>> prior to be merged to a release branch. Anyone is free to comment and provide a vote (+1/+0/-1)
-on a pull request. Note that votes of non-committers are considered non-binding, but are certainly considered in the
-review process.
+link:https://github.com/apache/tinkerpop/pulls[pull requests]. When a pull request is issued it undergoes a
+<<rtc,review process>> prior to being merged to a release branch. Anyone is free to comment and provide a vote
+(+1/+0/-1) on a pull request. Note that votes of non-committers are considered non-binding, but are certainly
+considered in the review process.
=== Writing Documentation
Proposing a documentation change is quite similar to providing a source code change, which is described below in more
-detail. Note that there is a difference between project documentation and the TinkerPop web site. The project
-documentation refers to the documentation that is published per release like, tutorials, reference documentation, and
-other similar pages. This content is not updated after release and remains static bound to that version. The TinkerPop
-web site refers to the static home page and its related content, such as link:http://tinkerpop.apache.org/gremlin.html[Understanding Gremlin],
+detail. Note that there is a difference between project documentation and the
+link:http://tinkerpop.apache.org/[TinkerPop web site]. The project documentation refers to the documentation that is
+published per release like, tutorials, reference documentation, and other similar pages. This content is not updated
+after release and remains static bound to that version. The TinkerPop web site refers to the static home page and its
+related content, such as link:http://tinkerpop.apache.org/gremlin.html[Understanding Gremlin],
link:http://tinkerpop.apache.org/policy.html[Provider Listing and Graphic Usage Policies] and other similar pages.
This content is not bound to any particular version and can be published at any time where new content simply replaces
old content.
@@ -82,7 +83,7 @@ For web site changes, the process is largely the same except that the documentat
Asciidoc. The content can be found in the source control tree at link:https://github.com/apache/tinkerpop/tree/master/docs/site[docs/site].
The web site is always published from the `master` branch as it is not bound to a version, so there is no need to
submit a pull request to any other branches besides that one. If the change to this documentation involves changing
-provider listings in some way, first propose the those changes on the dev@tinkerpop.apache.org mailing list and achieve
+provider listings in some way, first propose those changes on the dev@tinkerpop.apache.org mailing list and achieve
consensus (wait time is 72 hours as usual). At that point, pull requests or direct changes can be submitted.
Again, see the <<documentation-environment,Documentation Environment>> section for more information on how to generate
the site locally.
@@ -105,7 +106,8 @@ itself, however, it is very much encouraged that such a project stand on its own
this that meet the TinkerPop link:http://tinkerpop.apache.org/policy.html[listing policy] can be added to the
TinkerPop web site and promoted there. Please see the current listing of such libraries on the TinkerPop
link:http://tinkerpop.apache.org/#graph-systems[home page] to get an idea as to what kinds of libraries are available
-from the community.
+from the community. When in doubt about whether a library might be a good fit for hosting and ongoing maintenance in
+the TinkerPop project itself, please ask on the dev@tinkerpop.apache.org mailing list.
== Considering Code Changes
@@ -188,9 +190,10 @@ link:https://github.com/apache/tinkerpop[GitHub repository] if not already done.
. Make changes in the fork
.. It is typically best to create a branch for the changes. Consider naming that branch after the JIRA issue number
to easily track what that branch is for.
-.. Consider which release branch (e.g. `master`, `tp31` etc) to create the development branch from in the first place.
-In other words, is the change to be targeted at a specific TinkerPop version (e.g. a patch to an older version)? When
-in doubt, please ask on dev@tinkerpop.apache.org.
+.. Consider which release branch (e.g. `master`, `tp33` - consult the
+link:http://tinkerpop.apache.org/docs/x.y.z/dev/developer/#branches[Branches Section] for more information) to create
+the development branch from in the first place. In other words, is the change to be targeted at a specific TinkerPop
+version (e.g. a patch to an older version)? When in doubt, please ask on dev@tinkerpop.apache.org.
. Build the project and run tests.
.. A simple build can be accomplished with maven: `mvn clean install`.
.. Often, a "simple build" isn't sufficient and integration tests are required:
@@ -199,10 +202,10 @@ tests to execute.
.. Docker can help simplify building and testing: `docker/build.sh -t -i -n`
.. Please see the <<building-testing,Building and Testing>> section for more building and testing options.
. Consider whether documentation or tests need to be added or updated as part of the change, and add them as needed.
-.. Nearly all changes should include a modification to the `CHANGELOG.asciidoc` file - one more entries to
+.. Nearly all changes should include a modification to the `CHANGELOG.asciidoc` file - one or more entries to
help summarize the change.
-.. Some changes will require updates to the "upgrade documentation" - usually reserved for major new features and
-breaking changes.
+.. Some changes will require updates to the link:http://tinkerpop.apache.org/docs/x.y.z/upgrade/[Upgrade Documentation].
+Updates to this documentation are usually reserved for major new features and breaking changes.
.. Docker can help simplify documentation generation: `docker/build.sh -d`
.. Please see the <<building-testing,Building and Testing>> section for more documentation generation options.
. Open the link:https://help.github.com/articles/using-pull-requests/[pull request] against the appropriate branch
@@ -225,9 +228,10 @@ of the entire change.
. Reviewers can indicate that a change looks suitable for merging with by providing a "+1". Please see the
<<rtc, Review then Commit>> process for more details.
. Sometimes, other changes will be merged which conflict with your pull request's changes. The PR can't be merged
-until the conflict is resolved. This can be resolved with "git fetch origin" followed by "git merge origin/master"
-and resolving the conflicts by hand, then pushing the result to your branch. Or more nicely, consider rebasing changes
-and force pushing the branch.
-. Try to be responsive to the discussion rather than let days pass between replies
+until the conflict is resolved. In these cases the PR must be rebased, conflicts resolved and the resulting changes
+force pushed back to the branch.
+. Try to be responsive to the discussion rather than let days pass between replies.
+. Reviewers may request additional pull requests (e.g. one for each release branch that it may be related to) if
+the changes brings extensive conflict between branches.
On successful review, the *pull request will be merged* to the main repository and the JIRA issue will be closed.
diff --git a/docs/src/dev/developer/for-committers.asciidoc b/docs/src/dev/developer/for-committers.asciidoc
index 82b3609..236b980 100644
--- a/docs/src/dev/developer/for-committers.asciidoc
+++ b/docs/src/dev/developer/for-committers.asciidoc
@@ -23,14 +23,14 @@ The guidelines that follow apply to those with commit access to the main reposit
== Communication
TinkerPop has a link:http://groups.google.com/group/gremlin-users[user mailing list] and a
-link:https://lists.apache.org/list.html?dev@tinkerpop.apache.org[developer mailing list]. As a committer,
+pass:[<a href="https://lists.apache.org/list.html?dev@tinkerpop.apache.org">dev mailing list</a>]. As a committer,
it is a good idea to join both.
-It would also be helpful to join the public link:https://apache.hipchat.com/chat/room/2013155[TinkerPop HipChat room]
-for developer discussion. This helps contributors to communicate in a more real-time way. Anyone can join as a guest,
+It may also be helpful to join the public link:https://apache.hipchat.com/chat/room/2013155[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
+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
@@ -123,8 +123,9 @@ be adjusted accordingly to not auto-wildcard the imports.
TinkerPop uses link:https://travis-ci.com/[Travis] for link:https://en.wikipedia.org/wiki/Continuous_integration[CI]
services. The build status can be found link:https://travis-ci.org/apache/tinkerpop[here]. 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.
+does not run all possible tests (e.g. Neo4j-related tests) as a full execution would likely exceed the allowable times
+for builds on these servers. Instead Travis runs a basic cross-section of tests selected to provide a reasonably high
+degree of confidence in the branch built.
== Deprecation
@@ -436,7 +437,7 @@ that may be used as building blocks for your benchmarks; `AbstractBenchmarkBase`
[[rtc]]
== Review then Commit
-Code modifications must go through a link:http://www.apache.org/foundation/glossary.html#ReviewThenCommit[review-then-committ] (RTC)
+Code modifications must go through a link:http://www.apache.org/foundation/glossary.html#ReviewThenCommit[review-then-commit] (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.
@@ -444,7 +445,7 @@ to the committer wanting to put code into a release branch.
* 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].
+* When your fix is complete and ready to merge, issue a <<pull-requests,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]
@@ -457,7 +458,7 @@ the pull request (in other words, the change submitter and the reviewer are the
not rely strictly on lazy consensus.
* Votes are issued by TinkerPop committers as comments to the pull request.
* Once either consensus position is reached, 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.
+** 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), multiple pull requests may be necessary (i.e. one for each branch).
* 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
@@ -493,7 +494,9 @@ require a review.
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."
+adjustments to text formatting." CTR based commits will still require manual merging through all release branches.
+Merges should occur in reverse order, starting with the latest release version first (e.g. if the fix is going to
+3.2.x then the change should be merged in the following order `master`, `tp33`, `tp32`).
[[pull-requests]]
=== Pull Requests
@@ -518,6 +521,11 @@ release branches (e.g. a pull request made to for the branch containing 3.1.x mu
3.2.x), it is important to be sure that those changes are merged to the downstream release branches. Typically,
this process is best handled by multiple pull requests: one to each release branch.
+While merges can be handled manually with `git` commands, it is typically best to use the GitHub UI itself and the
+"Merge Pull Request" button instead. Branches should be merged in reverse order, starting with the latest release
+version first (e.g. if the fix is going to 3.2.x then the change should be merged in the following order `master`,
+`tp33`, `tp32`).
+
As an example, consider a situation where there is a feature branch named "TINKERPOP-1234" that contains a fix for
the `tp31` branch:
@@ -564,7 +572,7 @@ Again, depending on the changes, it may make sense to re-test at this point, oth
git push origin TINKERPOP-1234-master --force
----
-It should not be safe to merge both pull requests to their release branches.
+It should now be safe to merge both pull requests to their release branches.
IMPORTANT: Always take a moment to review the commits in a particular pull request. Be sure that they are *all* related
to the work that was done and that no extraneous commits are present that cannot be explained. Ensuring a pull request