Skip to content

Contributing to Github

Jump to bottom
Ben Matern edited this page Jul 3, 2018 · 21 revisions

Contributing

Here's some general/basic Github information on how to contribute to these projects. These instructions are commandline or browser based. Many of these steps can also be accomplished using Github Desktop GUI.

The first thing you need to do is to set up your environment. Using MinION-extractor-GUI as an example:

Fork the repository and prepare your environment.

  1. Fork the repo. This means you create a new online repository in your own environment. The fork button is on the github repository page, use your browser.

More on forking

  1. Clone your fork. This means you will copy the files from your personal repository to your local computer. There is a clone button on your repository, so use your browser, or commandline:
cd ../GithubWorkDir/
git clone https://github.com/YOUR-USERNAME/MinION-extractor-GUI

More on cloning a fork

  1. Configure your fork so it can sync with the upstream repository. By default, there is no upstream repository configured. You should add the original project as the parent repository, otherwise you won't see new upstream code changes. Use commandline:
cd ../GithubWorkDir/MinION-extractor-GUI
git remote -v
git remote add upstream https://github.com/transplantation-immunology-maastricht/MinION-extractor-GUI.git
git remote -v

More on configuring your fork

  1. Sync your fork. This means download the newest code from the upstream repository, to your local hard drive. You don't need to do this (steps #4-#5) if you created your fork just now, but you should sync your fork before you start developing features. This step doesn't modify your online repository, only your local hard drive.
cd ../GithubWorkDir/MinION-extractor-GUI
git fetch upstream
git checkout master
git merge upstream/master

More on syncing your fork

  1. Push the synced fork back to your personal online repository. Syncing only updated files on your hard drive, this push will update your online repository with the latest code (including any new changes).
git push origin master

More on pushing your fork

Modify Code and upload changes.

Once your environment is set up, you can begin changing/adding code.

  1. Fork the project, or sync your existing fork with it's upstream. See steps #1-#5 above.

  2. Create a branch and check it out. Branches are often named to represent a new feature or bug fix. Maybe it is called "Fixing_mac_crash" or "new_fast5_keys". Use 'git branch' to verify what branch is currently checked out, for steps #3-#5 you are working in feature branch, not the master branch.

cd ../GithubWorkDir/MinION-extractor-GUI
git branch
git checkout -b 'new_fast5_keys'
git branch

More on branches

  1. Make code changes in your Github work directory. Use your preferred text editor. There are likely some scripts included (*.sh or *.bat) to launch the project to get started. If you create new code files, you will need to add them to the project:
cd ../GithubWorkDir/MinION-extractor-GUI/src
git add helloworld.py

Or use git add . to add all new files

  1. Commit your code changes. Commit will stage your modifications, and get them ready to push to your online repository. This will inform you of all changes, new files, and conflicts.
cd ../GithubWorkDir/MinION-extractor-GUI
git commit -a -m 'adding helloworld.py'
  1. Push your code changes. This will update the feature branch on your online repository. "origin" should still be configured to point at your fork.
cd ../GithubWorkDir/MinION-extractor-GUI
git remote -v
git push origin 'new_fast5_keys'

More on git push

  1. Merging your fork's feature branch into it's master branch takes a few steps: Checkout your fork's master branch, update master from it's origin, merge your feature branch into master branch, and push local changes to your repository.
cd ../GithubWorkDir/MinION-extractor-GUI
git checkout master
git pull origin master
git merge new_fast5_keys
git push origin master

When you have problems merging

  1. When the code on your fork is at a major milestone, such as completing a new feature, you can start a pull request. In your browser, go to your fork's master branch, and push the "New Pull Request" button. The pull request should show you all changed files, please add a comment describing what has changed.

The base fork should be: transplantation-immunology-maastricht/MinION-extractor-GUI : master

The head fork should be: YOUR-USERNAME/MinION-extractor-GUI : master

More on pull requests

  1. A member of tranplantation-immunology will review and merge your pull request. Probably.

  2. If you wish, after your pull request is merged into the base repository, you can remove your feature branch. No need to have old branches lingering about.

Many of the previous steps can be accomplished using a Github Desktop GUI for Windows or Mac. You should generally follow the same general steps, but the GUI may use different terminology.

When any of these steps fail, or if your files cannot be merged automatically, then use Google to determine a solution. Many people have surely already had the same problem as you.

Clone this wiki locally