Updated instructions on how to fetch code from a forked repo, how to …

…kick of a travis-ci build from a PR

Testing Done:
ran build-support/bin/publish_docs.py and looked at the output and clicked on the links.

Bugs closed: 583, 713

Reviewed at https://rbcommons.com/s/twitter/r/1205/

src/python/pants/docs/howto_contribute.rst

@@ -76,14 +76,40 @@ If you have an idea for new work that's not yet been discussed on `pants-devel
 conversation there to vet the proposal. Once the group agrees it's worth
 a spike you can file a github issue and assign it to yourself.
 
+.. _download_source_code:
 
 Getting Pants Source Code
 =========================
 
-After deciding on the change you'd like to make we'll need to get the code. ::
+If you just want to compile and look at the source code, the easiest way is to clone the repo. ::
 
    git clone https://github.com/pantsbuild/pants
 
+If you would like to start developing patches and contributing them back, you will want to
+create a fork of the repo using the `instructions on github.com
+<https://help.github.com/articles/fork-a-repo/>`_.  With this setup, you can push branches and run
+Travis-CI before your change is committed.
+
+If you've already cloned your repo without forking, you don't have to re-checkout your repo.  First,
+create the fork on github.  Make a note the clone url of your fork.  Then run the following
+commands::
+
+   git remote remove origin
+   git remote add origin <url-to-clone-your-fork>
+   git remote add upstream  https://github.com/pantsbuild/pants
+
+After this change, ``git push`` and ``git pull`` will go to your fork.  You can get
+the latest changes from the ``pantsbuild/pants`` repo's master branch
+using the `syncing a fork <https://help.github.com/articles/syncing-a-fork/>`_ instructions
+on github.
+
+**Pro tip:** If you want your local master branch to be an exact copy of the ``pantsbuild/pants`` repo's
+master branch, use these commands::
+
+   git co master
+   git fetch upstream
+   git reset --hard upstream/master
+
 
 Making the Change
 =================
@@ -139,7 +165,9 @@ This ``post`` creates a new review, but does not yet publish it.
 At the provided URL, there's a web form. To get your change reviewed,
 you must fill in the change description, reviewers, testing done, etc.
 To make sure it gets seen, add ``pants-reviews`` to the Groups field
-and a specific reviewer to the People field.
+and a specific reviewer to the People field.  If you have created a
+`pull request <_dev_run_all_tests>`_ on github to run Travis-CI, put the pull request
+number in the Bug field and your git branch name in the Branch field.
 
 When the review looks good, publish it.
 An email will be sent to the ``pants-reviews`` mailing list and the reviewers

src/python/pants/docs/howto_develop.rst

@@ -6,8 +6,7 @@ This page describes the developer workflow when changing Pants itself. (If you
 wanted instructions for using Pants to develop other programs, please see
 :doc:`first_tutorial`.)
 
-.. Getting the source code section.
-
+These instructions assume you've already :ref:`downloaded the source code <download_source_code>`.
 
 ********************
 Running from sources
@@ -65,9 +64,9 @@ Building a Pants PEX for Production
 ***********************************
 
 Most of the time, you will probably want to use an official published version of pants.
-But what if you want to let some of your internal users try out the latest and greatest 
-unreleased code?  What if you want to create a custom build of pants with some 
-unpublished patches?  In that case, you want to build a production ready version of 
+But what if you want to let some of your internal users try out the latest and greatest
+unreleased code?  What if you want to create a custom build of pants with some
+unpublished patches?  In that case, you want to build a production ready version of
 pants including dependencies for all platforms, not just your development environment.
 
 The following command will create a locally built ``pants.pex`` for all platforms::
@@ -146,14 +145,15 @@ run it before you contribute a change or merge it to master::
 
    ./build-support/bin/ci.sh
 
-Sometimes you want to run tests on Travis-CI even though you're not sure
-your change is ready to merge to master.
+You can run your code through the Travis-CI before you submit a change.  Travis-CI is integrated
+with the pull requests for the ``pantsbuild/pants`` repo.  Travis-CI will test it soon after the
+pull request is created.  It will queue up a new job every time you subsequently push your branch.
 
-* If you can push to the ``pantsbuild/pants`` project,
-  push your development branch to origin. Travis-CI will test it soon after.
-* If you *can't* push to the ``pantsbuild/pants`` project,
-  push a branch to your fork of pantsbuild on github, then open a pull request
-  against pants with your branch. Travis-CI will test it soon after.
+To kick off a new CI-build, push a branch to your :ref:`fork <download_source_code>` of
+``pantsbuild/pants``.  Create a pull request on the ``pantsbuild/pants``
+`repo <https://github.com/pantsbuild/pants>`_,
+not your fork.  If you are posting a review request, put the pull request number into the Bug field.
+Then, when you close the request, you can navigate from the bug number to easily close the pull request.
 
 *********
 Debugging