Getting Started: Contributing on Github
This guide will take you through getting started contributing to our GitHub repository, from zero through your first pull request!
Go to https://github.com/join to create your account. Pick an easily recognizable user name, such as your initials, or first and last name.
More information can be found here.
Now that you have your own account, it's time to "fork" the repository to your account. Click on the "fork" button in the top right of the https://github.com/IMA-WorldHealth/bhima. This will copy the repository to your account.
More information can be found here.
Now you have your own copy of the code online. You must clone the repository locally using git. To clone your repository, simply type the command below, replacing $YOUR_USERNAME with the account name you created in Step 0.
git clone git@github.com:$YOUR_USERNAME/bhima.gitIn order to stay up to date with the changes in the IMA-WorldHealth/bhima repository, you'll need to add it as a remote. It is common to name the remote upstream, but you can name it whatever you want. Below, we'll use upstream as the name.
git remote add upstream https://github.com/IMA-WorldHealth/bhima.gitAll our work is documented by issues. Issues are usually either feature requests, bug reports, design discussions, or proposals for code and procedural enhancements. Anyone can create them - including you!
A good place to start is the issues labeled First Time Contributor. These are usually simple to tackle and are marked so that a new contributor can easily jump in.
Once you decide on an issue to work on, make a comment stating that you will work on it. You will usually get that issue assigned to you.
Here is a good example of a comment before working on an issue.
In case your forget what you should be working on, you can browse all the issues you are assigned - both those open and closed. For example, here are all the issues closed by @lomamech.
Now that you have your issue, you can begin actually writing code! Create a branch to work on locally. We have some advice on git branch names on the wiki.
Let's walk through the steps to starting your first branch:
# first, let's fetch from our upstream remote to make sure we have the latest code
git fetch upstream
# switch to the master branch
git checkout master
# update your master to the upstream's master
git merge upstream/master
# check out a new branch off your master branch
# the -b flag will create a new branch
git checkout -b feature-your-new-feature-branchThis is the fun part. You get to implement your feature, fix, or enhancement. Enjoy!
While working, you should frequently commit your work using git commit. Committing will ask you for a commit message - we use the same commit message syntax as AngularJS. See our advice on commit message syntax.
# add all the files you have changed (git calls this "staging")
git add .
# commit the changes with a nice message
git commit Now that you have one or more commits on a branch, you need to contribute it back to the main IMA-WorldHealth/bhima repository. To accomplish this, you must push your code to your personal remote repository origin.
# push your work to github.com/$YOUR_USERNAME/bhima
git push origin feature-your-feature-branchYou are almost done! It is time to open a new pull request. On one side, you should have the IMA-WorldHealth master branch. On the other, choose your repository and your branch. Then, click "Create a Pull Request".
More information can be found here.
That's it! You've made your first contribution! The project maintainers will either approve your pull request and merge it, or will ask you to make some changes. All changes will be made to your local branch (step 6), committed (step 8), and then pushed back up to the GitHub same branch (step 9). Once your code has been merged, go ahead and find another issue to work on (step 4)!