Contributor Workflow with Github

Intro

So you are going to contribute to kemia. Awesome! The following is our recommended workflow.

Overview

Contributors commit (frequently) code changes to their own fork of kemia, then push a ‘squashed’ single feature-based commit to the kemia development branch after testing it.

Fork

First, follow the Github instructions to fork kemia to your own public repository on Github. Of course, you will need to install git and setup your Github account.

Clone your fork

Next, clone your fork of kemia to a convenient location on your local machine.

>git clone [email protected]:YOURNAME/kemia.git
>cd kemia

Now you are ready to start coding!

Start coding!

There are lots of tutorials on lots of ways of using git with your shiny new local repository. Here is a basic step-by-step for working on a new feature:

1. Make a new branch for the new feature.
   

   >git checkout -b implement_bread_slicer

2. Code stuff.
3. Checkin frequently with as many descriptive commit messages as you want.
   

   >git status
   >git add [files]
   >git add [more files]
   >git commit -m "add finger guard to slicer" 

4. Write and Run unit tests for the new feature and to check for any regressions.
5. Lather, rinse, repeat.

Keeping Your Fork Up-To-Date

As your fork ages, other contributions will have been merged into the main kemia repository causing your fork to slowly become more and more out-of-date. Remember, the github Fork Queue is not the right tool for keeping your forks up to date.
You need to add the main kemia repository to the list of remotes for your local repo (here called ‘upstream’).

>git remote add upstream [email protected]:kemia/kemia.git

Make sure your repository is clean (no uncommitted changes) and is currently on the development branch. If not, commit or stash any changes and switch to the development:

>git checkout development

Then you can pull all the new commits from the main line:

>git pull upstream development

Remember, pull is a combination of the commands fetch and merge, so there may be merge conflicts to be manually resolved.

Interim publish to your fork

You may have commits that you want to publish to your forked repo on github to make them visible to other contributors before the new feature is complete and ready to push to the main kemia repository.

>git push origin development 

Publish your contributions

When you are done with the feature, double check that everything is fine, it is easier to fix errors before you publish.

1. Check the test suite, in case your changes broke any tests.
2. Check if compiling raises any errors.
3. Check for merge conflicts by bringing your repository up to date.
4. If everything looks good with your new feature, then squash the commits into a single feature-based commit with an interactive rebasing (the kemia repo is called ‘upstream’ in this example) .
   

   >git rebase -i upstream

5. Push to the main kemia repository
   

   >git push upstream development

6. Send a quick email to the development team describing your cool new feature!