Contributing Content Via Pull Request

This content is mostly stolen from OGC Environmental Linked Features Interoperability Experiment (ELFIE) wiki, thanks Dave Blodgett for this clean intro to GitHub.

As described in the contributing section of the readme, content can be submitted via pull request or by opening a new issue pointing to content that needs to be brought in. This page describes how to add content to a fork of the repository and submit a pull request containing those changes.

git and git BASH

For mac and linux users, you will need the git command line tools. Windows users should install git-for-windows, which includes git BASH, a bash shell emulator.

ssh keys

If you want to type passwords for everything, skip this section and only use the "https" option when setting up remote repositories (lame). If you hate typing your username and password, follow the instructions here to get your ssh key setup on github. Pro tip: If you want to live dangerously and never type passwords, create a passwordless ssh key for use with github!

Forking the repository

If you don't know about forking, it's time to read some stackoverflow! Even if you do know about forking, please review this github guide, then come back here for some details. The following are some considerations, that are person preferences, but will help us all stay on the same page.

1. Fork then clone using ssh (not https).
   e.g. git clone [email protected]:YourGitHubID/boreholeie.git This gets you set up with a remote who's origin is your personal fork of the shared repository.
2. Add a remote upstream repository.
   e.g. git remote add upstream [email protected]:opengeospatial/boreholeie.git
   This gives you access to contents of the shared repository.
3. Revoke your "push" access to upstream.
   e.g. git remote set-url --push upstream no_push
   We almost never want to "push" to upstream, so just turn it off, it's easy to make mistakes.
4. Try "pulling" from upstream.
   e.g. git pull upstream master This pulls changes from the upstream master branch into your current checked out branch.
5. Try "pushing" to origin. e.g. git push origin master This pushes local changes to your personal fork of the shared repository.

That's it. Now you can do what you want on your fork with impunity and submit a pull request with some new commits when you are ready.
Note: You should do this kind of thing out of habit.

$ git status
On branch master
nothing to commit, working tree clean
$ git checkout master
Already on 'master'
$ git pull upstream master
From https://github.com/opengeospatial/boreholeie
 * branch            master     -> FETCH_HEAD
Already up-to-date.
$ git push origin master
Everything up-to-date

Adding new commits

Now that you have remotes all set, you are ready to get some work done. Up till now, we've needed to use the command line because we need to setup multiple remotes. For adding new content or changing existing content, using the github desktop app or another GUI, such as the one included in git-for-windows. Just make sure you use the command line to get the latest commits from upstream and keep you personal fork in sync.

Submitting a pull request.

Once you have some new commits pushed to your personal remote (fork) of the group's repository, you are ready to submit a pull request. You can do this from the group repository and set the "Head Fork" to your personal fork, or you can start the pull request from your fork and GitHub is smart enough to know you want to submit a request to the group repository you forked in the first place.

Review and Reconciliation

Once you have a pull request submitted, all the "watchers" of the repository will receive a notice about it and the review process will proceed. If your request needs to be changed, it can either be merged with an agreed additional pull request to address the issue, or you might make the change as additional commits that you push. If you do push additional commits before the pull request get's merged, the new commits just show up in the open pull request.

That's it. Once you've gone through this process once or twice, it's no big deal and it is a super useful way to work autonomously and get your work reviewed by the group.