Contributing via pull requests

In this post, I'd like to give a small step-by-step introduction how to contribute via pull-requests with an example of a recipe in haikuports. I'm in no way an experienced user of git etc., so I appreciate improvements in the comments. Just remember, we want to keep it very simple... :)

These are the steps for a pull request:

1. Create a user at github.
2. Create a fork of the project.
3. Clone that forked project.
4. Make your changes to the code, test and commit them.
5. Push your changes to your forked project.
6. Create a pull-request

1. Create a user at github

That one should be obvious...

2. Create a fork of the project

Go to the haikuports project and click the "Fork" button at the top right of the page. Now go to your personal github and you'll find the forked repo there.

3. Clone that forked project

On that page of your fork, click the "Clone or download" button and copy the web URL "https://github.com/humdingerb/haikuports.git". Now open a Terminal, change into the folder you want to put the code and clone your fork (i.e. download the code):

cd /boot/home
git clone https://github.com/humdingerb/haikuports.git

Getting the whole haikuports tree takes a while...

4. Make your code changes

Now do those changes you wanted to do. Maybe it was simply a typo in a recipe description. After all is done and you checked if haikuporter can still build the package. You check once more your changes to make sure you didn't change more than intended:

git diff

This shows the differences compared to the original files. If that's OK, you commit them all with:

git commit -a

A text editor opens for you to enter a descriptive commit message, e.g. "Recipe XY: fixed typo in description".

Now, what if after that commit you realize that there was another typo, or you made a typo when correcting the typo, or something equally tautologically embarrassing?
Easy, just make your changes and then amend those changes when committing again with:

git commit -a -amend

That way, you'll still only have one commit when you're finally pushing it to your repo. You can do this as often as you have to...

5. Push your changes

You push those changes to your github with:

git push

6. Create a pull-request

Now open your forked project at github in the webbrowser. At the top you click the button "New pull request" which will take you through the steps of submitting your changes to the haikuports project.
If they accept your request, they pull your changes into their master branch and you're all done.

Often however, the developer/maintainer of the project has a few details to nag about. No problem, just make those additional changes to the code and again amend those with:

git commit -a -amend

To update the existing pull-request, you have to "force" the push with:

git push -f

And that's all there is to it. Really quite easy in its simplest form, isn't it? Of course, things can get a bit more complicated (but also more sophisticated) when using branches and remote repos, and even more complicated when you've messed up your commits and have to get it all back on track... :)
Don't let that discourage you, though. Open the Vision app and join the #haiku channel on IRC to get help, consult the haikuports wiki, and always keep in mind the xkcd wisdom: