How to create a PULL request

[Gavin Andresen]

The bitcoin integration/testing source tree is at GitHub, and we (jgarzik/tcatm/gavinandresen right now) use GitHub's "pull request" feature to keep track of patches that people think are ready for integration into mainline bitcoin.  This post is a walk-through of how to create a pull request.

1. You'll need a GitHub account; sign up for free, and set up git and ssh to work with GitHub.

2. You need a fork of the main bitcoin source tree.  Login to your GitHub account, browse to the bitcoin project, then poke the little 'Fork' button near the top of the screen.

3. Connect that fork at GitHub with source code on your development machine.  The easiest way to do that is to clone your github fork, using the SSH Read+Write URL github shows you on your fork's page.  For example:

Code:

git clone git@github.com:your_github_name/bitcoin-git.git
cd bitcoin-git
git checkout -b niftynewfeature # Create a feature branch
 ... edit, test, re-edit, re-test...
git commit -a
git push git@github.com:your_github_name/bitcoin.git niftynewfeature:niftynewfeature

You might already have a clone of the bitcoin git tree that you've modified; you should push those changes into your new GitHub fork.  Assuming you made your changes in the 'master' branch on your machine (next time you should create a specific feature branch), the command would be:

Code:

git commit -a
git rebase -i remotes/origin/HEAD  # optional: lets you tidy up commits to create a clean patch
git push git@github.com:your_github_name/bitcoin.git master:niftynewfeature

4. Submit a PULL request by going to your fork's GitHub page, selecting the branch containing the changes you want pulled ("niftynewfeature" in the above example), and then poking the "Pull Request" button.  Enter a good description of what your changes do and why they're a good idea and how everybody and their brother is already using them to make the world a better place .

Eventually, if all goes well, after discussion and argument and nit-picking and revision, your changes will get pulled into the bitcoin repository.  If all doesn't go well, you (or the core developers) can close your pull request and resubmit it when the feature is perfect.

[Zulu]

I think it's possible to do something along the line of:

Code:

git remote add bitcoin git@github.com:username/bitcoin-git.git

Then you'll only need to do:

Code:

git push bitcoin branch_name
git pull bitcoin branch_name

You can also add a commit message by using the -m flag:

Code:

git commit -a -m "Check out my awesome bugfix"

This way you won't end up in Vim (and freak out). This is more usefull for shorter commit messages though.

[LMGTFY]

Code:

git commit -a -m "Check out my awesome bugfix"

This way you won't end up in Vim (and freak out). This is more usefull for shorter commit messages though.

...or you could just tell git what editor you'd prefer!

[khal]

Me too. Thanks Gavin.

[muc]

For those of us that are ignorant, can somebody tell me what a PULL request in layman's terms is? And what is it used for?

[TierNolan]

For those of us that are ignorant, can somebody tell me what a PULL request in layman's terms is? And what is it used for?

Since the project is open source, anyone can change the files.  However, this creates a "fork", their version of the software is different from everyone else's.  This means that they need to incorporate any future changes into their fork.

A pull request allows them to submit the change back to the main project.  If it is accepted, the changes become part of the official version of the software. 

[ampkZjWDQcqT]

For those of us that are ignorant, can somebody tell me what a PULL request in layman's terms is? And what is it used for?

It can be properly understood when you know what a Distributed Version Control System is. Start with http://progit.org/book/.

[casascius]

Can anyone help me figure out how to do the following?

1. Get the latest version at bitcoin/bitcoin
2. Apply just sipa's pull request called "Wallet Import and Export" to my own copy so I can compile it in.

Thanks

EDIT: Asking a question seems to guarantee I will find the answer right after I ask.  My end result was to git clone bitcoin/bitcoin, and then download https://github.com/bitcoin/bitcoin/pull/220.diff, then git apply, then compile.

[finway]

I've made a new locale file "bitcoin_zh_CN.ts",How can i upload it to my github fork and make a pull request?

I've made my fork of bitcoin on github.com, I've installed Git, and cloned my fork.
I ran
git push origin master
It shows:  
everything up-to-date
and nothing changed to my fork on github.com

but i've copy "bitcoin_zh_CN.ts" to the directory "bitcoin/src/qt/locale",
clearly

What should i do? (http://github.com/finway-china/bitcoin)


EDIT:
Yeah, done my first pull request

git add bitcoin_zh_CN.ts
git commit
EDIT
git push origin master

[kurtosis]

or optionally (for posterity of a stickied thread):

Code:

git add -A
git commit -m 'added awesome new feature'
git push -u origin master

Explanations for -A and -u.  Generally only use -A if all the modifications to be committed are a single bundle of functionality, describable by the same commit message.

[Andreas Schildbach]

after discussion and argument and nit-picking and revision

What happens if I already submitted the pull request and then commit a fix to my patch, so there are now 2 commits in that pull request. Am I supposed to squash the commits into one? Do I need to re-submit my pull request afterwards?

[jgarzik]

after discussion and argument and nit-picking and revision

What happens if I already submitted the pull request and then commit a fix to my patch, so there are now 2 commits in that pull request. Am I supposed to squash the commits into one? Do I need to re-submit my pull request afterwards?

You do not have to resubmit the pull request.  Squash the commits into one, and then "git push --force" to "rebase" the branch.

[robamichael]

For those of us that are ignorant, can somebody tell me what a PULL request in layman's terms is? And what is it used for?

Since the project is open source, anyone can change the files.  However, this creates a "fork", their version of the software is different from everyone else's.  This means that they need to incorporate any future changes into their fork.

A pull request allows them to submit the change back to the main project.  If it is accepted, the changes become part of the official version of the software. 

Is the decision for acceptance determined by a developer?

[kjj]

Whether or not your pulls get accepted depends on a rough consensus of the devs.  Some of them have a bit more pull than the others, but there isn't like a formal voting process.

If you are submitting pulls, you'll get emails from github when people comment on it.  Pay attention to those, the people making them are giving advice earned through hard experience.  Address their concerns when you can, and be prepared to defend your choices.

Also start hanging out in #bitcoin-dev on IRC.  It can be very helpful to start conversations about your pull, particularly with the people that have commented on it.  Be polite, and keep in mind that they can be busy, even if you can't see it.

[robamichael]

Whether or not your pulls get accepted depends on a rough consensus of the devs.  Some of them have a bit more pull than the others, but there isn't like a formal voting process.

If you are submitting pulls, you'll get emails from github when people comment on it.  Pay attention to those, the people making them are giving advice earned through hard experience.  Address their concerns when you can, and be prepared to defend your choices.

Also start hanging out in #bitcoin-dev on IRC.  It can be very helpful to start conversations about your pull, particularly with the people that have commented on it.  Be polite, and keep in mind that they can be busy, even if you can't see it.

Thank you for your advice. I definitely will be checking out the IRC channel.

Is it fair to say then, that Bitcoin is not completely decentralized? I am only asking to better my understanding, but it seems there is some amount, even if minor, of centralization.

[Gavin Andresen]

Is it fair to say then, that Bitcoin is not completely decentralized? I am only asking to better my understanding, but it seems there is some amount, even if minor, of centralization.

The only completely and utterly decentralized bitcoin-like system I can think of would have every person using it write and run their own code.

On computers that they built themselves.

Communicating over a wireless mesh network where each node in the mesh was controlled by a single person who wrote all the code and built all the hardware....

[robamichael]

Right - maybe the word "completely" was stronger than what I needed.

The mechanics of bitcoin differ from something like gold, because gold was created by nature, and bitcoin is managed by people. And anything managed by people is centralized to some extent.

I will do some reading and try to understand the PULL process.

[oleganza]

Is it fair to say then, that Bitcoin is not completely decentralized? I am only asking to better my understanding, but it seems there is some amount, even if minor, of centralization.

To me, Bitcoin is valuable not because of how much it is "decentralized" and "democratic", but simply because it allows choice including option to exit the club at any time. I have a choice to build my own software, I have choice to suggest an improvement to others, I have choice to mine coins myself, or buy them, or stash them away and sell any time in the future. Of course, my freedom of choice is limited by my resources and your willingness to cooperate with me. But that's voluntary. Neither you, nor me can impose our will on each other. So I can use bitcoins with peace of mind knowing that they are built on top of voluntary interactions instead of enslavement. If I get rich or poor, it will be only because of my voluntary choices, so there will be no one to blame but myself.

[rbgrish]

Well Said oleganza!

[GambitBTC]

Great tut +1 for the info