[Users] How to submit patches to the Einstein Toolkit

[Erik Schnetter]

When using Subversion, there are two classes of people: Those with
write access to the repository, which can make changes or create
branches for development, and those without, who are forced to send
patches or tarballs by email or by attaching them to a bug report. The
latter is really quite inconvenient, both for the people preparing
them, and also for the people who have to apply them.

When using a git repository hosted at Bitbucket (or Github etc.),
things are much easier for all parties. There is no need to send
around patches or tarballs any more. Instead, you do the following.
Bear with me -- the instructions are lengthy only because I'm
explaining things, but each of these steps really corresponds just to
a mouse click or two.



(1) Create an account at Bitbucket. Obviously, you do this only once.

(2) Fork the repository on Bitbucket. This creates a copy of the
repository on Bitbucket which belongs to you, and where you can commit
changes. I see the "fork" menu entry hidden behind the three
horizontal dots in the top-left corner of the original repository's
web pages.

That's "fork", and not "clone" -- clone would make a copy on your
laptop, which isn't quite enough. The difference is that you can later
allow others to look at your forked repository, and thus pick up the
changes you made.

(3) Clone the forked repository, or -- if you already have a clone of
the original repository -- add a new "remote" to it. That's
straightforward if you use a GUI, on the command line you'll have to
follow instructions that are posted on Google.

All the steps until here are necessary only once per repository.
(Unfortunately, the ET uses a gazillion of repositories -- in
hindsight I'm not quite sure why, it certainly doesn't make things
easier.)

(4) Make your changes, commit them, etc. I usually create a new branch
for every patch.

(5) Push your changes (i.e. the branch) to the forked repository. They
are now visible to the world; people can look at them and comment
them.

(6) Tell others about your changes and where to find them. The easiest
way is to create a "pull request" on Bitbucket. I see the "create pull
request" menu entry near the "fork" menu entry. A "pull request" is
essentially a ticket (on Bitbucket) that allows others -- those with
write access to the repository -- to merge ("pull") your changes with
the click of a button. Those with write access like this, because it's
very convenient. They don't even have to clone your branch -- it's all
visible right there in the web browser, and reviewing and accepting a
patch takes less than a minute.

As an added bonus, since you created the commit, your name will be
associated with the change and bring you fame.



And as a side note, my (egoistic) willingness to look at a patch
depends on how much trouble I have to go through for this. Clicking on
a link that immediately shows me a nice commit message in a web
browser together with a colour-coded diff is about as easy as it gets
for me.

-erik

-- 
Erik Schnetter <schnetter at cct.lsu.edu>
http://www.perimeterinstitute.ca/personal/eschnetter/