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?
-
4I wrote a more detailed step by step guide on contributing to Concrete5 on Github, but the process could apply to any project. Check it out.– Joe MeyerAug 16, 2014 at 15:02
-
4check github.com/joindin/joind.in/wiki/How-to-Contribute-Code– KonstantinosDec 17, 2014 at 17:15
-
1perhaps with sufficient majority voting, a previously closed questions should be allowed to be resurrected again, and let people contribute to the thread again.– Peter TeohMay 7, 2015 at 0:05
-
@wizztjh, Another easy tutorial: pontikis.net/blog/…– PacerierMay 13, 2016 at 12:25
-
Here's a hands-on tutorial github.com/Roshanjossey/first-contributions– sudo bangbangMar 9, 2017 at 11:03
7 Answers
Ideally you:
- Fork the project
- 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.
- 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.
-
4
-
1
-
2@MariusKavansky it's the other way round! Once you know what to work on, then only you contribute :) 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.– wizztjhJan 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.– PacerierMay 13, 2016 at 12:11
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:
- add the original project as a remote (different form '
origin
', sinceorigin
would be your own repo, result of the fork) - rebase your branch on top of the branch of the original repo you want to contribute.
It is important your pulling request result in fast-forward merges.
See for instance:
-
1can 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.– VonCMay 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.– VonCMar 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
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.
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.
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
lornajane has a blog post that explains the process well: http://www.lornajane.net/posts/2010/contributing-to-projects-on-github
Technical workflow
I would suggest the following workflow:
Fork the repository (via GitHub web interface: "Fork" button)
In your forked repository, copy the URL
Clone (in the command line)
git clone <url-from-your-workspace>
Enter the directory, that just got created, and create a branch
cd <directory> git checkout -b <branchname>
Now make your changes
You can create one or more commits after each change:
git add .;
git commit
When done, push your changes
git push origin <branch>
In your command line, you should see a URL to create the PR. Visit the URL and click the button to create a PR.
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?