Step-by-step guide to contributing on GitHub
Have you considered contributing to an open supply undertaking, however you are too confused (or intimidated) by the method to even attempt? I have been there too!
I wrote this step-by-step information to indicate the precise course of I exploit when contributing to a undertaking on GitHub. If you happen to observe this information precisely, you may make your first open supply contribution TODAY!
Why contribute to open supply?
There are lots of nice causes to contribute to open supply initiatives:
- It builds your resume by demonstrating which you can collaborate with others on code.
- It offers you follow with Git and GitHub, which is a beneficial information science ability.
- It lets you construct relationships within the open supply group.
- It feels good to provide again to a undertaking that you simply use!
Within the instance beneath, I will contribute to Python’s scikit-learn library. I have been educating Machine Learning with scikit-learn for a few years, so I am very happy to provide again!
First, it is advisable select a undertaking to contribute to. I counsel you begin with a library you at the moment use, as a result of you’ll already perceive the aim of the library and you’ll be invested in making it higher.
Second, it is advisable select find out how to contribute. I counsel contributing to the undertaking documentation, because it does not require writing any code. Begin by discovering a typo or a damaged hyperlink to repair. Since this ought to be a easy repair, it is possible for you to to give attention to studying the contribution workflow.
As soon as you’ve got chosen what to repair, you’ll be able to start the step-by-step course of beneath:
- Steps 1 via 6 are setup steps, that means you solely should do them as soon as for every GitHub undertaking.
- Steps 7 via 19 ought to be repeated for every contribution to that undertaking.
These assets may be useful to you as you’re employed via the steps:
Step 1: Signal into GitHub
Signal into your GitHub account, or create a free GitHub account if you do not have one.
Step 2: Fork the undertaking repository
Discover the undertaking’s repository on GitHub, after which “fork” it by clicking the Fork button within the higher proper nook:
This creates a duplicate of the undertaking repository in your GitHub account. Within the higher left nook, you will note that you’re now taking a look at a repository in your account:
Step 3: Clone your fork
Whereas nonetheless in your repository, click on the inexperienced Clone or obtain button after which copy the HTTPS URL:
Utilizing Git in your native machine, clone your fork utilizing the URL you simply copied:
git clone URL_OF_FORK.
For instance, I used
git clone https://github.com/justmarkham/scikit-learn.git.
Cloning copies the repository recordsdata (and commit historical past) from GitHub to your native machine. The repository can be downloaded right into a subdirectory of your working listing, and the subdirectory could have the identical identify because the repository.
(If you happen to run into issues throughout this step, learn the Set up Git web page from GitHub’s documentation.)
Step 4: Navigate to your native repository
For the reason that clone was downloaded right into a subdirectory of your working listing, you’ll be able to navigate to it utilizing:
For instance, I used
Step 5: Test that your fork is the “origin” distant
You’ll be synchronizing your native repository with each the undertaking repository (on GitHub) and your fork (additionally on GitHub). The URLs that time to those repositories are referred to as “remotes”. Extra particularly, the undertaking repository is known as the “upstream” distant, and your fork is known as the “origin” distant.
If you cloned your fork, that ought to have mechanically set your fork because the “origin” distant. Use
git distant -v to indicate your present remotes. You must see the URL of your fork (which you copied in step 3) subsequent to the phrase “origin”.
If you happen to do not see an “origin” distant, you’ll be able to add it utilizing:
git distant add origin URL_OF_FORK.
(If you happen to run into issues throughout this step, learn the Managing remote repositories web page from GitHub’s documentation.)
Step 6: Add the undertaking repository because the “upstream” distant
Go to your fork on GitHub, and click on the “forked from” hyperlink to return to the undertaking repository:
Whereas within the undertaking repository, click on the inexperienced Clone or obtain button after which copy the HTTPS URL:
Add the undertaking repository because the “upstream” distant utilizing:
git distant add upstream URL_OF_PROJECT.
For instance, I used
git distant add upstream https://github.com/scikit-learn/scikit-learn.git.
git distant -v to examine that you simply now have two remotes: an origin that factors to your fork, and an upstream that factors to the undertaking repository.
This diagram summarizes the complete setup course of (steps 1 via 6):
Step 7: Pull the most recent modifications from upstream into your native repository
Earlier than you begin making any modifications to your native recordsdata, it is a good follow to first synchronize your native repository with the undertaking repository. Use
git pull upstream grasp to “pull” any modifications from the “grasp” department of the “upstream” into your native repository.
If you happen to forked and cloned the undertaking repository only a few minutes in the past, it is most unlikely there can be any modifications, through which case Git will report that your native repository is “already updated”. But when there are any modifications, they are going to mechanically be merged into your native repository.
Step 8: Create a brand new department
Slightly than making modifications to the undertaking’s “grasp” department, it is a good follow to as a substitute create your individual department. This creates an setting in your work that’s remoted from the grasp department.
git checkout -b BRANCH_NAME to create a brand new department after which instantly swap to it. The identify of the department ought to briefly describe what you’re engaged on, and mustn’t include any areas.
For instance, I used
git checkout -b doc-fixes as a result of I used to be making some small fixes to the documentation.
git department to indicate your native branches. You must see your new department in addition to “grasp”, and your new department ought to have an asterisk subsequent to it to point that it is “checked out” (that means that you simply’re working in it).
Step 9: Make modifications in your native repository
Use a textual content editor or IDE to make the modifications you deliberate to the recordsdata in your native repository. Since you checked out a department within the earlier step, any edits you make will solely have an effect on that department.
Step 10: Commit your modifications
After you make a set of modifications, use
git add -A to stage your modifications and
git commit -m "DESCRIPTION OF CHANGES" to commit them.
For instance, I used
git commit -m "repair typos in set_config docstring" for one among my commits.
If you’re making a number of units of modifications, it is a good follow to make a commit after every set.
Step 11: Push your modifications to your fork
When you find yourself executed making your entire modifications, add these modifications to your fork utilizing
git push origin BRANCH_NAME. This “pushes” your modifications to the “BRANCH_NAME” department of the “origin” (which is your fork on GitHub).
For instance, I used
git push origin doc-fixes.
Step 12: Start the pull request
Return to your fork on GitHub, and refresh the web page. You may even see a highlighted space that shows your lately pushed department:
Click on the inexperienced Evaluate & pull request button to start the pull request.
(Alternatively, should you do not see this highlighted space, you’ll be able to swap to your department utilizing the Department button after which click on the New pull request button.)
Step 13: Create the pull request
When opening a “pull request”, you’re making a “request” that the undertaking repository “pull” modifications out of your fork. You will note that the undertaking repository is listed because the “base repository”, and your fork is listed because the “head repository”:
Earlier than submitting the pull request, you first want to explain the modifications you made (somewhat than asking the undertaking maintainers to determine them out on their very own). You must write a descriptive title in your pull request, after which embody extra particulars within the physique of the pull request. If there are any associated GitHub points, ensure that to say these by quantity. The physique can embody Markdown formatting, and you’ll click on the Preview tab to see the way it will look.
On the best facet, you may even see a hyperlink to the undertaking’s Contributing tips. That is primarily value studying via if you’re submitting substantial code (somewhat than simply fixing a typo), however it might nonetheless be value scanning via at this level.
Beneath the pull request type, you will note a listing of the commits you made in your department, in addition to the “diffs” for all the recordsdata you modified.
If every thing seems to be good, click on the inexperienced Create pull request button!
This diagram summarizes the complete pull request course of course of (steps 7 via 13):
Step 14: Evaluate the pull request
You could have now created a pull request, which is saved within the undertaking’s repository (not in your fork of the repository). It is a good suggestion to learn via what you wrote, in addition to clicking on the Commits tab and the Recordsdata modified tab to evaluation the contents of your pull request:
If you happen to understand that you simply omitted some essential particulars, you’ll be able to click on the three dots within the higher proper nook to edit your pull request description.
Step 15: Add extra commits to your pull request
You possibly can proceed so as to add extra commits to your pull request even after opening it! For instance, the undertaking maintainers could ask you to make some modifications, or you might simply consider a change that you simply forgot to incorporate:
Begin by returning to your native repository, and use
git department to see which department is at the moment checked out. If you’re at the moment within the grasp department (somewhat than the department you created), then use
git checkout BRANCH_NAME to modify. For instance, I used
git checkout doc-fixes.
Then, you must repeat steps 9 via 11: make modifications, commit them, and push them to your fork.
Lastly, return to your open pull request on GitHub and refresh the web page. You will note that your new commits have mechanically been added to the pull request:
Step 16: Focus on the pull request
If there are questions or dialogue about your pull request from the undertaking maintainers, you’ll be able to add to the dialog utilizing the remark field on the backside of the pull request:
If there are inline feedback about particular modifications you made, you’ll be able to reply to these as nicely:
Click on the Resolve dialog button after you have addressed any particular requests.
Step 17: Delete your department out of your fork
If the undertaking maintainers settle for your pull request (congratulations!), they are going to merge your proposed modifications into the undertaking’s grasp department and shut your pull request:
You’ll be given the choice to delete your department out of your fork, because it’s now not of any use:
Click on the Delete department button:
Step 18: Delete your department out of your native repository
You also needs to delete the department you created out of your native repository, in order that you do not unintentionally begin working in it the subsequent time you wish to make a contribution to this undertaking.
First, swap to the grasp department:
git checkout grasp.
Then, delete the department you created:
git department -D BRANCH_NAME. For instance, I used
git department -D doc-fixes.
Step 19: Synchronize your fork with the undertaking repository
At this level, your fork is out of sync with the undertaking repository’s grasp department.
To get it again in sync, you must first use Git to drag the most recent modifications from “upstream” (the undertaking repository) into your native repository:
git pull upstream grasp.
Then, push these modifications out of your native repository to the “origin” (your fork):
git push origin grasp.
If you happen to return to your fork on GitHub, you will note that the grasp department is “even” with the undertaking repository’s grasp department:
This step will not be strictly mandatory, since you’ll pull modifications from upstream earlier than you make your subsequent contribution to this undertaking (step 7). Nonetheless, this step is beneficial if you’ll clone your fork from one other machine.
Congratulations on making your first open supply contribution! 🎉 Please share a hyperlink to your profitable pull request within the feedback part beneath. If you happen to bumped into any surprising issues, I might love to listen to about it in order that I can proceed to enhance this information.
Ideas for contributing code
If you happen to’re prepared to start out making code contributions (past simply fixing typos), listed below are just a few suggestions:
- Flick thru a repository’s open points (particularly ones labeled “good first problem”) to see if there is a matter you would possibly be capable to clear up.
- If you happen to’re planning to contribute code that’s unrelated to an current problem, it is a good suggestion to open a brand new problem describing your proposal earlier than beginning work on it. The undertaking maintainers would possibly offer you suggestions that can assist to form your work, which is able to finally improve the probability that your pull request can be accepted.
- Learn the undertaking’s contributing information, which is able to normally be within the GitHub repository or the undertaking documentation. It is going to doubtless include many useful suggestions for find out how to efficiently contribute to the undertaking.
Good luck, and let me know when you’ve got any questions!