tinkerpop-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From spmalle...@apache.org
Subject tinkerpop git commit: Updated dev docs regarding branching and pull requests CTR
Date Fri, 16 Sep 2016 14:16:01 GMT
Repository: tinkerpop
Updated Branches:
  refs/heads/tp31 75baf01e8 -> 4ed009525


Updated dev docs regarding branching and pull requests CTR


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

Branch: refs/heads/tp31
Commit: 4ed009525ba3c0bed01fd2331b54ee1dbb76284c
Parents: 75baf01
Author: Stephen Mallette <spmva@genoprime.com>
Authored: Fri Sep 16 10:14:59 2016 -0400
Committer: Stephen Mallette <spmva@genoprime.com>
Committed: Fri Sep 16 10:14:59 2016 -0400

----------------------------------------------------------------------
 docs/src/dev/developer/contributing.asciidoc   |  6 +-
 docs/src/dev/developer/for-committers.asciidoc | 83 ++++++++++++++++++---
 2 files changed, 76 insertions(+), 13 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/4ed00952/docs/src/dev/developer/contributing.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/dev/developer/contributing.asciidoc b/docs/src/dev/developer/contributing.asciidoc
index 36124f1..63c40b7 100644
--- a/docs/src/dev/developer/contributing.asciidoc
+++ b/docs/src/dev/developer/contributing.asciidoc
@@ -179,9 +179,9 @@ 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 branch to create the branch from in the first place. In other words, is
the change to be targetted
-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`, `tp31` etc) to create the development branch
from in the first place.
+In other words, is the change to be targetted 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:

http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/4ed00952/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
index fa88070..9c5059c 100644
--- a/docs/src/dev/developer/for-committers.asciidoc
+++ b/docs/src/dev/developer/for-committers.asciidoc
@@ -60,13 +60,18 @@ 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]]
 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.
+TinkerPop has several release branches:
+
+* `tp30` - 3.0.x (no longer maintained)
+* `tp31` - 3.1.x (bug fixes and documentation updates only)
+* `master` - 3.2.x
+
+Changes to `tp31` should merge to `master`. Please read more about this process in the <<pull-requests,
Pull Requests>>
+section.
 
 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
@@ -200,8 +205,8 @@ 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.
+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.
@@ -210,7 +215,7 @@ committer wanting to put code into a release 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].
+* 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] from other committers.
 ** 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.
@@ -236,10 +241,11 @@ When the committer chooses CTR, it is considered good form to include
something
 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
-~~~~~~~~~~~~~~~~~~~
+[[pull-requests]]
+Pull Requests
+~~~~~~~~~~~~~
 
-When you submit a pull request, be sure it uses the following style.
+When submitting a pull request to one of the <<branches, release branches>>,
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.
@@ -254,6 +260,63 @@ When you submit a pull request, be sure it uses the following style.
 ** 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.
 
+A pull request will typically be made to a target <<branches, branch>>. Assuming
that branch is upstream of other
+release branches (e.g. a pull request made to for the branch containing 3.1.x must merge
to the branch that releases
+3.2.x), it is important to be sure that those changes are merged to the downstream release
branches. Typicaly,
+this process is best handled by multiple pull requests: one to each release branch.
+
+As an example, consider a situation where there is a feature branch named "TINKERPOP-1234"
that contains a fix for
+the `tp31` branch:
+
+[source,bash]
+----
+`git checkout -b TINKERPOP-1234 tp31`
+// do a bunch of stuff to implement TINKERPOP-1234 and commit/push
+git checkout -b <TINKERPOP-1234-master> master
+git merge TINKERPOP-1234
+----
+
+At this point, there are two branches, with the same set of commits going to `tp31` and `master`.
Voting will occur
+on both pull requests. After a successful vote, it is time to merge. If there are no conflicts,
then simply `git merge`
+both pull requests to their respective branches. If there are conflicts, then there is some
added work to do - time to
+rebase:
+
+[source,bash]
+----
+git checkout TINKERPOP-1234
+git rebase origin/tp31
+----
+
+Depending on the conflict, it might be a good idea to re-test before going any further, otherwise:
+
+[source,bash]
+----
+git push origin TINKERPOP-1234 --force
+----
+
+Now, `git rebase` has re-written the commit history, which makes a mess of the other pull
request to master. This
+problem is rectified by essentially re-issuing the PR:
+
+[source,bash]
+----
+git checkout TINKERPOP-1234-master
+git reset --hard origin/master
+git merge TINKERPOP-1234
+----
+
+Again, depending on the changes, it may make sense to re-test at this point, otherwise:
+
+[source,bash]
+----
+git push origin TINKERPOP-1234-master --force
+----
+
+It should not 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
+only contains the expected commits is the responsibility of the committer as well as the
reviewer.
+
 [[dependencies]]
 Dependencies
 ------------


Mime
View raw message