236

I would like to contribute to a certain project in GitHub. Should I fork it? Branch it? What is recommended and how to do it?

5

7 Answers 7

191

Ideally you:

  1. Fork the project
  2. Make one or more well commented and clean commits to the repository. You can make a new branch here if you are modifying more than one part or feature.
  3. Perform a pull request in github's web interface.

if it is a new Feature request, don't start the coding first. Remember to post an issue to discuss the new feature.

If the feature is well discuss and there are some +1 or the project owner approved it, assign the issue to yourself, then do the steps above.

Some projects won't use the pull request system. Check with the author or mailing list on the best way to get your code back into the project.

6
  • 4
    Details on GitHub's forking, and pull requests Dec 8, 2010 at 6:44
  • 1
    Yes, pull request. Merge request is gitorious terminology.
    – Yann Ramin
    Dec 8, 2010 at 6:47
  • 2
    @MariusKavansky it's the other way round! Once you know what to work on, then only you contribute :)
    – hashbrown
    Jan 7, 2014 at 6:46
  • after I contributed to some open source project. I think it is a better Idea to to open up an issue to discuss the new feature if it is a new feature. If it is a feature or issue that is well discussed, you should assign the issue to yourself then do the steps above. This is my 2cents.
    – wizztjh
    Jan 14, 2015 at 11:36
  • @hashbrown, He's asking where's the "list" of requested features thus far. Those features that are already being requested and +1ed.
    – Pacerier
    May 13, 2016 at 12:11
34

To add to Yann's answer, once you have forked a project, you can develop in any branch you want (a new one, or one from the original project)

Remember to:

6
  • 1
    can you add details or links on your second point (rebasing branch)? May 21, 2014 at 22:56
  • 1
    @JorgeArtware I have updated the answer with a few links illustrating the rebase.
    – VonC
    May 22, 2014 at 6:44
  • @VonC I ask a question here but if you believe it is necessary, I will make a whole new question out of it. Why would I rebase instead of merge, other than having the 'straight history' ? In other words, here's what I do when I contribute to some projects (after the PR from my feature branch has been merged to develop and to master branches): git checkout master; git pull; same for develop (where my feature branch was merged first) The difference I can think of, after reading "pull vs pull --rebase" and "merge vs rebase" is just the flat history. Anything else more deep? Mar 24, 2017 at 13:36
  • @grasshopper in term of "contribution" (the context of this page), you always want to rebase your local commits on top of updated branches before pushing: that will make said contribution trivial to integrate by the maintainer to the original project branch. In the context of your question, where your PR has been accepted, sure, you can merge instead of rebase to update existing branches.
    – VonC
    Mar 24, 2017 at 13:39
  • (Sorry changed username just now to reflect my github) - @VonC thank you, so all the suggestions that I was reading about the rebase apply before the PR, makes sense. To reflect the accepted and merged PR inside my local repo, is there any common practice (rebase instead of merge), or can I do whatever? What if I will submit another PR though? Mar 24, 2017 at 13:44
15

To add to Yan and VonC's answers, this is a good resource from github themselves: http://help.github.com/forking/

Also be sure to look on the right sidebar under the "collaborating" heading.

10

There is a great Railscast video here that walks you through the process. It also has a number of good tips such as showing how to determine which branch you might want to work on when contributing, using tests, submodules, etc.

While this screencast is primarily focused on Rails developers most of the information is valid for contributing to any open source project.

4

Github has many ways of collaborating to a project. The model most project use is a pull request model. I've started a project to help people making their first GitHub pull request. You can do the hands-on tutorial to make your first PR here

The workflow is simple as

  • Fork the repo in github
  • Clone the repo to your machine
  • Make a branch and make necessary changes
  • Push your changes to your fork on GitHub git push origin branch-name
  • Go to your fork on GitHub to see a Compare and pull request button
  • Click on it and give necessary details
3

lornajane has a blog post that explains the process well: http://www.lornajane.net/posts/2010/contributing-to-projects-on-github

0
2

Technical workflow

I would suggest the following workflow:

  1. Fork the repository (via GitHub web interface: "Fork" button)

  2. In your forked repository, copy the URL

  3. Clone (in the command line)

    git clone <url-from-your-workspace>

  4. Enter the directory, that just got created, and create a branch

    cd <directory> git checkout -b <branchname>

  5. Now make your changes

  6. You can create one or more commits after each change:

    git add .; git commit

  7. When done, push your changes

    git push origin <branch>

  8. In your command line, you should see a URL to create the PR. Visit the URL and click the button to create a PR.

  9. If not, visit the repository in the browser and it will offer you a button for creating the pull request

That's it.

So, basically, you forked the repository to your workspace, created a new branch and pushed that new branch.

If you later make more PR from the same cloned repo, you should synchronize (get the latest changes from the original repository) before you create another branch for another PR:

git checkout master
git remote add upstream <url-of-original-repo>
git pull upstream master

Other considerations:

  • the project may have Contribution Guidelines: Look for a file CONTRIBUTING.rst or .md
  • you may want to follow the coding guidelines for the project
  • you may want to outline your idea as issue first
  • you may want to look at the Pull Requests tab for the project and check if there are open PR, merged PR

These suggestions are here to save you from the trouble of putting work into a PR that will not get merged. If there is activity in the project and PR get merged, this is a good sign. If there are Contribution Guidelines, follow them.

Always be courteous. Remember, the maintainers of the project are in no way obligated to merge your PR. Do you have something valuable to add to the project?

0

Not the answer you're looking for? Browse other questions tagged or ask your own question.