Creating pull requests

Please keep in mind, that pull requests are the official way how make a code contribution. They help us by launching an automatic verification, reviewing and accepting it preserving a clean changelog and the contributor's list for later releases.

We use the opensource platform Github (github.com) for the active development, because it offers the possibility code of pull requests for reviewing/staging contributions before merging them without using patch files. Intermediate and final states are more or less frequently pushed back to the Codehaus GIT repository.

You should be familar with Git to send contributions as pull request.

The developers are automatically informed on incoming pull requests, and a verification is automatically launched by the build system to ensure compilation, unit and integration tests work on defined platforms.

Here is a HOWTO to start from scratch:

See also:

[1] http://jira.codehaus.org/browse/IZPACK
[2] http://xircles.codehaus.org/projects/izpack

Use Cases

A basic tutorial how to handle repositories on Github can be found here: https://help.github.com/articles/fork-a-repo.

The steps described below are use-cases for a quick start with practical examples for contributing code to IzPack. They are kept simple especially for users new to Git and Github.

Setting Up a User Repository

The basic steps for a quick start are:

  1. Fork the original izpack/izpack repository.
    This can be done on the Github website.
    For instructions, see this manual  https://help.github.com/articles/fork-a-repo.
    Result: Your own repository with a fork of the IzPack development repository.
     
  2. Clone your repo to a local computer. 

    git clone https://github.com/my_username/my_izpack_repo.git



  3. Convenient: Add the official IzPack repository as remote, i.e. izpack, to easily pick up changes from it or reset the user repository with it's latest state:

    git remote add izpack https://github.com/izpack/izpack.git

Creating and Checking Out a Local GIT Branch From Uncommitted Changes

In case you have already made changes in your master branch, they can still be easily included in a newly created Git branch.

Prerequisites:

The changes in files to be included in the branch require these files to be already added. If you added new files, use

git add <new_file>

to achieve this

After this launch:

git checkout -b IZPACK-123

which creates a new branch IZPACK-123 and activates it at once. The commands git branch and git checkout can be combined to do these steps separately

The files can now be further edited or pushed to the user's repository add Github.

Committing New Changes Locally

After you've finished your implementation including all necessary tests, you can commit these changes locally with a message best containing the issue ID and title:

git commit -m "[IZPACK-123] - My issue's title"

If you leave out the -m option you can add a commit message interactively.

If you do several commits within the same development branch just fixing the same things you worked on before, use

git commit --amend

to leave a clean history behind. Be aware, that on accepting your pull requests later all your intermediate commit messages appear in the history and might confuse other developers or an automatically generated changelog.

Pushing Changes to a Github User Repository

git push origin IZPACK-123

from where you can create a pull request using the Github web interface.

Deleting a Local Branch After a Pull Request Has Been Accepted

After your pull request has been accepted and merged by a developer, the temporary branch is always deleted in the official IzPack repository at Github.

At this stage, you can also delete it locally:

git checkout master
git branch -D IZPACK-123

Reset a Local Repository To The Current Development State

For being sure changes can be really applied on a pull request next time it is recommended to reset a current repository to the current development state from time to time. Provided you already added the original izpack/izpack repository as a remote izpack, this can be done by

git fetch izpack
git checkout master
git reset --hard izpack/master
git push

This way you avoid future merge conflicts to be manually resolved.