Fork & Pull Instructions for Highway Data Updating

NOTE: THIS IS A FIRST DRAFT OF THESE INSTRUCTIONS! PLEASE SEND ALONG SUGGESTIONS AND CORRECTIONS!

Here is the procedure to use the fork/pull method to contribute an update to the Travel Mapping highway data.

The master copy of the data is on GitHub in a repository named HighwayData in the TravelMapping organization. You can get to it through the web interface at

https://github.com/TravelMapping/HighwayData

Only a handful of people have the ability to commit directly to the master repository, and even those people should be following the procedure below to submit changes.

The following assumes you have a GitHub account and are logged in at github.com. It also assumes you have set up your GitHub environment on your own computer according to the instructions at

https://help.github.com/articles/set-up-git/

You will need to create a fork of the HighwayData repository in your own GitHub account. This can be done in the web interface, using the "Fork" button near the upper right of the page above.

This will create a copy of the whole repository in your account. You'll then be in your fork's web page. Mine is:

https://github.com/jteresco/HighwayData

You can safely do whatever you want in your fork - it will not have an effect on the master repository.

Next, clone this fork to your local computer and set it up to have its origin as the copy you made on GitHub and set it up to have the master as an upstream origin so you will be able to get updates to the master brought into your fork.

The instructions for this are Steps 2 and 3 on this page:

https://help.github.com/articles/fork-a-repo/

In my case, I cloned with:

git clone https://github.com/jteresco/HighwayData.git

(this takes a few minutes - you're getting a copy of all of the highway data)

When I issue the command "git remote -v" in the cloned repository's new directory, I get:

origin	https://github.com/jteresco/HighwayData.git (fetch)
origin	https://github.com/jteresco/HighwayData.git (push)

I added the master upstream as in Step 6 with the command:

git remote add upstream https://github.com/TravelMapping/HighwayData.git

and when I now issue the command "git remote -v", I get the expected output:

origin	https://github.com/jteresco/HighwayData.git (fetch)
origin	https://github.com/jteresco/HighwayData.git (push)
upstream	https://github.com/TravelMapping/HighwayData.git (fetch)
upstream	https://github.com/TravelMapping/HighwayData.git (push)

So I now have a clone on my local computer of my own fork of the HighwayData repository.

I will not need to re-create this fork or its local clone again, but if I don't use it for a while, I should update it to match the upstream (overall master, not my fork). Following the steps on

https://help.github.com/articles/syncing-a-fork/

git fetch upstream
git checkout master
git merge upstream/master

I was able to bring in changes from the origin to the master of my fork by following the instruction in the first answer at http://stackoverflow.com/questions/20984802/how-can-i-keep-my-fork-in-sync-without-adding-a-separate-remote/27599083#27599083

I will use my fork to fix a reported error in the data, which I also added to GitHub as an "Issue" on the HighwayData repository:

https://github.com/TravelMapping/HighwayData/issues/13

To fix this, I'll need to add a point to I-91's Massachusetts segment to match the point on MA 2.

Since we'll want this to be contributed back to the master, we'll create a branch and make our changes in that branch.

I'll give my branch a meaningful name. I'll include my GitHub username and a few words describing what I'm planning to do in this branch.

git checkout -b jteresco-i91-ma2-concurrency-fix

I then made my edits. In this case, I added a line to hwy_data/MA/usai/ma.i091.wpt, but in many cases, you will be editing, creating, or deleting several files in your branch.

(To Do: instructions here or a link to instructions elsewhere on how to run the site update program locally to make sure things still seem to work before committing anything.)

Before I proceed, I make sure I'm still "in" my branch with the "git branch" command. It shows:

* jteresco-i91-ma2-concurrency-fix
  master

The '*' indicates the current branch. So I'm good.

The "git status" command shows my changes:

On branch jteresco-i91-ma2-concurrency-fix
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

    modified:   hwy_data/MA/usai/ma.i091.wpt

no changes added to commit (use "git add" and/or "git commit -a")

So I can go ahead and add and commit my changes to the branch:

git add hwy_data/MA/usai/ma.i091.wpt
git commit -a -m "Added shaping point to MA I-91 to match MA 2 along their concurrency."

Be sure to give meaningful and helpful commit messages (the part after -m).

Now I want to get this branch back to the origin of my fork on GitHub. I first push the branch to GitHub:

git push origin jteresco-i91-ma2-concurrency-fix

This gives some output:

Counting objects: 6, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 610 bytes | 0 bytes/s, done.
Total 6 (delta 4), reused 0 (delta 0)
To https://github.com/jteresco/HighwayData.git
* [new branch]      jteresco-i91-ma2-concurrency-fix -> jteresco-i91-ma2-concurrency-fix

Now we return to our fork's page on GitHub:

https://github.com/jteresco/HighwayData

There should now be a box showing that you have pushed a branch. We can create a pull request back to the TravelMapping master with the "Compare & Pull Request" button. This brings you to the "Open a pull request" page, where you can optionally add more comments as part of the pull request.

This creates a pull request on the TravelMapping/HighwayData repository, which can then be merged in or discussed further if necessary. (Further changes can then be made to be incorporated into the branch and pull request -- details of how this is accomplished need to be investigated).

Finally, someone with write permissions to the master repository can merge the pull request, and your changes are now in. Once that's all done, the branch can be deleted.