Contribute via Github

Prerequisites

To contribute through pull requests, you'll need a few things:

Know at least the basics of Git
Have a GitHub account
Have a fork of the project you want to contribute to

Before going into detail, let's go over some vocabulary. Here's a short glossary of the words you'll constantly come across with Git/GitHub:

repo: short for "repository". This word refers to a set of files versioned with Git.
branch: a branch in a Git project. Branches let you create a parallel version of the code from a given point in its history.
master: the main branch of the repo.
origin: the remote repo, hosted on GitHub for example.
pull request: the operation used to propose a code change to a project on GitHub.
fork: a repo that is a copy of another repo. It lets you start from an existing project in order to change it: to improve it, fix it, or turn it into something else.
upstream: for a fork, the repo the fork comes from.
fetch: the operation that downloads data from the remote to your local copy.
push: the operation that sends your local data to the remote.

Setup

Fork

The first thing to do is go to GitHub and create a fork of the project you want to contribute to.

For example, to contribute to the Leek Wars client, go here: Leek Wars Client

Then just click the "fork" button at the top right.

By "forking" the project, GitHub creates a new repo on your account. It's a copy of the original project.

Then get the address of your GitHub repo, from the URL or by clicking the green "Clone or download" button.

Go to the folder where you want to put your local repo and run this command: git clone \ Don't forget to replace "<Repo URL>".

There you go. You've created a fork of the project and downloaded it locally, onto your machine. But there's one more thing to do so that you can keep using it without trouble in the future.

Upstream

Next, you need to set up the upstream, which lets you update your repo from the project's repo.

The git remote -v command lists the configured remote addresses.

origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch) origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)

For now, you should see two addresses configured as origin. One for fetch, used when you want to bring in the latest changes from your remote, your repo hosted on GitHub. And the other for push, which works the other way around: it sends your new local changes to the remote repo.

We're going to add the upstream to these. To do so, get the address of the project you just forked, again from the URL or the "Clone or download" button.

The command to add the upstream is: git remote add upstream \

If you run the git remote -v command again, you should now see four entries: two for the origin and two for the upstream, each one appearing once for fetch and once for push.

origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch) origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push) upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (fetch) upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (push)

You're now ready to contribute!

Keeping up to date

(You can skip this step if you've just made your fork.)

Chances are the project you're contributing to isn't frozen. The people who look after it will keep changing it, and other contributions may be accepted.

So your repo can quickly become outdated, and that's likely to cause problems.

Say a file originally contained "A", and you want to submit a contribution that changes this "A" into "B". In the meantime, someone else may have changed that "A" into "C".

Then, when you submit your change, there will be a conflict: "A" can't be changed into "B" since "A" is no longer in the file.

In short, it's important to keep your repo up to date to avoid nasty surprises.

Don't worry: now that you've set up the upstream, it'll be a piece of cake!

The first thing to do is get the new changes from the project's repo. For that, use the fetch command:

git fetch upstream And Git will download the changes you don't have.

Next, switch to the branch you want to update with the checkout command. For example, with master:

git checkout master

And finally, the rebase command lets you rebase your master branch onto the upstream.

git rebase upstream/master

This way, Git takes the upstream's master branch (that is, the master branch of the forked repo) as the base, and reapplies the commits you've made on top of the branch's history.

With a bit of luck, if your commits don't touch things that have changed, there won't be any conflicts.

And there you go! Your branch is now up to date with the project's.

To update the branches you're working on, you can do the same thing after updating your master.

Switch to the branch: git checkout \, then git rebase master

Starting a contribution

Got your fork? Set up the upstream?

Good! Time to prepare your pull request.

The first step is probably to have an idea for a feature to build. Feel free to pick ideas from the repo's issues! Leek Wars client issues

Next, you'll need to create a branch to make your changes on. This keeps your changes isolated and makes it easy to work on another pull request in parallel, for example.

To do so, switch to the upstream's master branch:

git checkout upstream/master

You can also switch to your own master branch if it's up to date with the upstream, thanks to the previous step.

git checkout master

Then create your branch:

git checkout -b myAwesomeFeature

There you go: you've just created a branch for your feature, starting from the original repo's history. By keeping the upstream up to date as shown in the previous section, you'll always be able to start your changes from the latest version of the repo.

The git checkout -b command created a branch and switched you to it (you can check this with the git branch command: a * appears in front of the branch you're on).

So you're ready to change the code and bring your idea to life.

Keep in mind the rule of one feature per pull request. That way, the history stays clear for the author of the original repo, who remains free to accept one feature and reject another. There's no point in making a single pull request for 36 different things.

Once you've finished your changes and checked that everything works with no bugs, all that's left is to commit your changes.

To do so:

git commit -am "Message summarizing the commit"

If you've added a file, you'll need to add it like this:

git add \

You can check which files are affected, and which ones have been added or not, with the command:

git status

If you make a lot of changes, consider splitting them into several meaningful commits.

Once your changes are added to the commit history, all you have to do is send everything to GitHub:

git push origin \

After that, you'll see that your branch is on your repo on GitHub, with your changes.

All that's left is to create the pull request!

Creating the pull request

[...]