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/TINKERPOP-1404 Commit: 4ed009525ba3c0bed01fd2331b54ee1dbb76284c Parents: 75baf01 Author: Stephen Mallette <sp...@genoprime.com> Authored: Fri Sep 16 10:14:59 2016 -0400 Committer: Stephen Mallette <sp...@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 -d...@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 d...@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 ------------
