Upload
andrei-varvaruc
View
219
Download
0
Embed Size (px)
Citation preview
7/29/2019 How to Contribute to Github
1/11
How to GitHub: Fork, Branch, Track, Squash and Pull
Request
by Rich Jones
Mar 27, 2012
This guide will teach you how to properly contribute to open source projects on GitHub. It assumes that you already know about
how to use Git for version control and that you already have a GitHub account.
Psstt.. i f you already have a GitHub account and you want to earn more money,sign up for Gun.io with your GitHub profile
and we'll pair you with people looking for developers based on your portfolio!
Getting Started
GitHub displays these instructions when you start a new project.
GitHub is pretty great about giving advice to users starting new repositories, but it isn't very helpful when it comes to contributing
changes back to other projects. Hopefully, this guide will help.
Before you get started, find the page of the project you're looking to improve. Poke around in the code a little bit, familiarize
yourself with their development styles, check the commit log to see who is contributing and check out the profile of the core
maintainer.
Check the Network
http://gun.io/social/login/github/http://gun.io/7/29/2019 How to Contribute to Github
2/11
The network graph. Notice that somebody is already working on a 'mobile' branch, so you probably wouldn't want to duplicate
their effort.
The first thing to do is check the Networktab on the project to see all the other forks that other people have made. Spend a few
minutes digging around in them, as it's quite possible that somebody is already working on the problem that you'd like to see
solved. It'll also give you an idea of the activity of the project, and how likely it is that your changes will be merged in.
Opening an Issue
You've got issues, man.
Next, head over to the Issues tab. Have a look around, see how many issues there are and if anybody has opened up the issue
that you're interested in working on.
This is an important step that many people forget about, and they just submit major pull requests to maintainers without
considering that the maintainers might not have the same intentions with the software as they do. This is especially true if a new
feature requires user interface/design changes, as often, that's the aspect of programs that people are the most protective of.
If your issue doesn't exist already, open up a new issue. Standard human interaction rules apply here; be friendly, be polite, say
thanks for making the project, describe the bug or feature you'd like to work on and then offer to help.
Hopefully, they'll reply shortly with some input on how to solve the problem.
Making Your Fork
Hardcore Forking Action
Here's the fun part! Hit 'Fork'. Now you've got your own version! Go to the page, get the ssh: url from the box at the top and
then
git clone **your ssh/git url**
to your local machine. Hooray! You have the code on your local machine now.
7/29/2019 How to Contribute to Github
3/11
view rawgistfile1.txt
Make Your Fork Track the Original Upstream Repo
It's a fork. Hur hur hur.
This step isn't absolutely necessary, but I find it very useful if you plan on working on this project for anything more than a very
quick fix. Use the following commands to add the 'upsteam' (original project location) as a remote branch so that you can get
theirupdates into your branch. Replace the 'upstreamname' and 'projectname' values with that actual user/project name that
you're trying to track.
1 git remote add --track master upstream git://github.com/upstreamname/projectname.git
This Gist brought to you by GitHub.
This will add the original project as a remote named 'upstream'. To get the code, type:
git fetch upstream
Then, to merge it into your own project, type:
git merge upstream/master
Tada! Now you'll have an up-to-date version of the upstream code in your current branch.
Setting Up A Development Branch
Guys, remember the old internet? Oh man.
Now you're getting ready to start hacking, you'll want to switch off of the 'master' branch and onto a different branch for your
http://github.com/https://gist.github.com/Miserlou/2209205https://gist.github.com/Miserlou/2209205#file-gistfile1-txt7/29/2019 How to Contribute to Github
4/11
new feature. It's important to do this because you can only have onePull Requestper branch, so if you want to submit more
than one fix, you'll need to have multiple branches. Make a new branch like this:
git branch newfeature
Then switch to it like this:
git checkout newfeature
Now you're on your new branch. You can confirm this by simply typing 'git branch'.
Hack!
This part's up to you. Hack along as you normally would until the code is in the state where you're happy with it, it performs the
task as described and it passes all the tests you've written for it. Yayyyy!
Squashing Your Commits
Squash. Hur hur hur.
If you're a heavy committerlike me, you've probably got lots of poorly messaged commits ('works!', 'broken', 'fuck', 'woo',
etc.). This is a bad habit, but I haven't been able to break it yet andI know I'm not the only one!
Before you submit your pull request back upstream, you'll want to squash these commits into a small handful of well-labeled
commits. To do this, we're going to use the git rebase command. First, take a look at the commits we've made withgit logand
figure out the commits that we want to squash. If we wanted to squash the last 3 commits into one, we'd open up an an
interactive rebase like this:
git rebase -i HEAD~3
This will bring you into your editor with some text that will look something like this:
pick df94881 Allow install to SD
pick a7323e5 README Junkyism
pick 3ead26f rm classpath from git
To squash those commits into one, change to something like this:
pick df94881 Allow install to SD
squash a7323e5 README Junkyism
squash 3ead26f rm classpath from git
Then, save/quit, and you'll be brought to into another editor session. Describe the changes as well as you can and save/quit again.
Hooray! You've squashed your ugly commits into one nice one. Now you're ready to submit a pull request.
Submitting a Pull Request
7/29/2019 How to Contribute to Github
5/11
Once you've commited and squashed your changes, push them to your remote like this:
git push origin newfeature
Then go to that page on GitHub and change branches to the one for your new feature.
Submit a Pull Request!
Then, click on the little button that says 'Pull Request'. This will bring you to a page asking you to describe your change.
Describe it thoroughly.
Describe your Pull Request.
Then press 'Submit Pull Request'. Hooray! You did it. Now, you're not quite done yet. If the maintainer finds some problems
with your code, they won't want to pull your changes until you fix them. Fortunately, whenever you commit and push more
things to that branch of your code, they will be included in that pull request until it is closed.
Accepting And Merging a Pull Request
Bonus! If you're on the receiving end of a pull request, how do you merge the changes? Easy - press the button! GitHub now
has an auto-merge button which does everything for you in one click. However, it doesn't always work, in which case you'll have
to do the merge on your own machine, like so:
git checkout master
git remote add contributor git://github.com/contributor/project
git fetch contributor
git merge contributor/newfeature
git push origin master
And then their changes will be properly merged into your main master branch.
So, Your Pull Request Was Rejected. Now What?
7/29/2019 How to Contribute to Github
6/11
Some forks are unavoidable.
Sometimes, for technical or organizational reasons, your pull request will be rejected. This can feel really frustrating, and there
are a few different ways you can proceed. Just remember to act rationally.
The simplest thing is to simply accept their judgement. It's their project, and a good maintainer knows when to say "no."Iftheir argument is logically sound, you should accept it. If you don't think it's a particularly important feature, hopefully whoever
is looking at the project will check the Network and Issues tabs of the upstream project and will notice your changes. However, I
think this is a pretty poor solution in cases when the upstream maintainer is wrong or unresponsive.
A better thing to do is write about it. Write about it on your blog, start a discussion on a mailing list, and solicit opinions from the
community about what the best way to proceed is. It'll also give some Google-juice to your project/issue, which will help other
people who ran into the same problem you faced.
The last option is to sever ties with the upstream and declare yourself the new maintainer of the project . This should only be
as a last resortand should only really be done when the upstream project is dead or has gone completely off the rails. That being
said, this kind ofsoftware deadheading can actually breathe a lot of new life into a project - just look at how LibreOffice has
managed to revive the OpenOffice project by severing ties with Oracle.
If you do this, you should rename your project to differentiate it from the upstream, explicitly state your reasons for the schism in
your README, and be sure to give proper copyright credit according the the open source license they originally chose.
Maintaining an open source project carries quite a lot of responsibility, so make sure you're prepared to care for the
project once you create such a schism.
Wrap UpHopefully this little guide was useful for getting you started with collaborative software development on GitHub!
If you're a developer looking for more jobs, we at Gun.io would like to help! You can sign up with GitHub and we'll
automatically pair you up with freelance and full-time job offers based on your existing code portfolio!
Need a Hacker?
gun.io is where top developers find gigs. Bad developers are screened out, so you'll only hire great hackers at gun.io.
http://gun.io/posthttp://gun.io/social/login/github/7/29/2019 How to Contribute to Github
7/11
Pssst! Hackers,sign up here!
Comments
About gun.ioWe match top developers with high-quality freelance and full-time jobs.
Infrastructure ProgrammerCryptic Studios
Los Gatos
Artisteer eZ Publish Integration$350
Front-End Developer - js/jQuery/HTML/CSS, Shot in the dark here, but VisualForce and APEX (?)$1025
Sign up with GitHub and we'll match you with great gigs based on your open-source portfolio!
25 comments
Leave a message...
Discussion Community #Share
Reply
Steve Klabnik 11 months ago
You should really rebase the commits from upstream rather than merge, so you don't make a crazy graph with tons of mergecommits.
4
g b 11 months ago> Steve Klabnik
Something like this? http://blog.bleeds.info/sofa/_...
22
Share
http://gun.io/social/login/github/http://gun.io/accounts/signup/7/29/2019 How to Contribute to Github
8/11
Reply
man, this is all too much work. I need a Makefile just for the git stuff.
0
Reply
Tim Smart 2 months ago> g b
`git rebase master` on whatever branch you are on (change 'master' with the upstream branch). Just replacing 'merge'
with 'rebase' gets the job done.
The main problem comes when pushing your commits to the remote server. 'rebase' creates non-fast-forward commits which any
sane git server setup will reject. This means to update your branch you will have to delete the remote branch and re-push it. `git
push origin :my-branch && git push origin my-branch` and you are done.0
Reply
Josh Kaufman 11 months ago
This is a great post. I'm new to Github, and didn't know how to track the or iginal repo of a fork or squash commits. Thanks for putt ing
this together!
1
Reply
Eric Pardee 3 days ago
I found this helpful, thank you.
0
Reply
Charles Edward Smith 24 days ago
Okay, so how does one do this with TortoiseGIT?
0
Reply
Steve Powell a month ago
I tried to follow the `Make Your Fork Track the Original Upstream Repo` section but found that I needed to use the `git @
github:username/projectname` format for it to work properly (spaces added to avoid re-formatting). Otherwise `git fetch` simply times out
unable to make contact.
Thanks for a useful page.
0
Reply
Sonny Darvishzadeh a month agoI'm new to GitHub and this is a good start, thanks for the article
0
Reply
Shoop a month ago
Great post! But I would be interested in: "If you're on the [sending] end of a pull request, how do you merge the changes [if the pull
request has been accepted?]"
:)
0
Reply
Dineshkummarc 2 months ago
thanks Rich Jones,
what if i forked using github UI and want to get the updated commits for the particular fork. please update me.
0
Reply
Levi Notik 3 months ago
Awesome post. I always come back to this.
0
Reply
Greg Gauthier 4 months ago
How do you do a pull request without having to fork? Work wants me to use pull requests, but I got my knuckles slapped for forking
the repo in order to do that according to githubs instructions.
0
Reply
Hari K T 7 months ago
Great Post :)
0
Share
Share
Share
Share
Share
Share
Share
Share
Share
Share
Share
Share
7/29/2019 How to Contribute to Github
9/11
What's this? ALSO ONGUNIO BLOG
Reply
Can I translate this post in my language?
0
Reply
Rich 11 months ago> lethee
Yes!, Please be my guest. It'd be nice if you linked back to here though..
0
Reply
lethee 11 months ago> Rich
The URL will be http://dogfeet.github.com/arti... and be published in some days.
1
Reply
g b 11 months ago
before the squashing step, it's missing a step on how to send your stuff to your github fork, before you do any pull request! what if
you are working with another contributor on that feature? what if you are working at home and at work?
0
Reply
Chris 11 months ago
Seems "git remote add upstream ..." is missing from the section "Make Your Fork Track the Original Upstream Repo".
0
Reply
isomorphisms 11 months ago
Where's the "undo" button? I've struggled with git-rewindevery time I've tried to use it.
0
Reply
DiabloD3 11 months ago
There is a rather large lack of git f low usage going on here.
0
Reply
Dude 11 months ago> DiabloD3
Erm, git flow? Git is a distributed version control system that supports TONS of different workflows. You should choose one
based on merits and applicability to the project.
Plus, git flow sucks. Get over it.
1
Reply
Decklin 11 months ago
You can also merge pull requests from your own working copy without adding the contributor as a remote:
git fetch refs/pull/123/head:pull-123
git merge pull-123
There is also a 'refs/pull/123/remote/merge' which gives you the commit that the merge button would produce, but unfortunately the commit
message is not very useful.
0
Reply
Guest 11 months ago
Naming the parent repository 'upstream' is not a good idea since all branches have upstreams that can be set with --set-upstream
switch.
0
Reply
Chris Ryland 11 months ago
Note that the step "git remote add --track master upstream ..." isn't necessary--the "git clone" will already automatically track the
remote master for you.
0
Reply
Chris Ballinger 11 months ago> Chris Ryland
It won't automatically track the upstream's remote master though. It will only track your own fork's remote master.
2
2 comments 24 days ago
1 comment 23 days ago
Share
Share
Share
Share
Share
Share
Share
Share
Share
Share
Share
Share
7/29/2019 How to Contribute to Github
10/11
7/29/2019 How to Contribute to Github
11/11
Send it!
Pssst.. do you want to write for Gun.io? Or, do you have a blog you'd like to see syndicated here?
Get in touch!
Aboutgun.io is where hackers find jobs.gun.io is where hackers find jobs. Every month, tens of thousands of the best independent software developers from the open source community use gun.io toEvery month, tens of thousands of the best independent software developers from the open source community use gun.io to
find high-quality freelance and full-time jobs.find high-quality freelance and full-time jobs.
LinksPhilosophy
Community
Premium Services
Team
Blog
@GUNdotIO
ContactNeed assistance hiring? Let us help!
Your email address
Or just mail the boss,Or just mail the boss, [email protected]@gun.io, directly!, directly!
mailto:[email protected]://twitter.com/GUNdotIOhttp://gun.io/bloghttp://gun.io/teamhttp://gun.io/premiumhttp://gun.io/communityhttp://gun.io/philosophy