We need you!

Icon

The IzPack documentation needs work, and you are invited to edit it!

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • Register on Jira/Xircles (xircles.codehaus.org)
  • Register on Github (github.com)
  • Fork the izpack/izpack repository on the Github website
  • Make a local copy of your fork
  • For each bug, improvement or feature
    • Create a Jira issue
      This issue is the central place for discussing and mainly designing the contribution.
    • Create a Git branch in your local copy with the name of the issue, for example IZPACK-123
    • Check out the new Git branch
    • Make just the changes for the according issue in this branch, nothing else, to have a clean changelog.
    • Test your changes locally as good as you can
    • Send the changes in the branch as pull request.
      On accepting the request your changes merged into the izpack/izpack master repository and the branch itself is automatically deleted on Github. You can delete it also in your local copy if you want.
    • If the pull request is not accepted, but there are just some more changes requested, you can further edit the code in the same checked out branch and refresh the same pull request on Github.

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.

Forking, Cloning and 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.
    Code Block
    languagebash
    git clone https://github.com/my_username/my_izpack_repo.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

Code Block
languagebash
git add <new_file>

to achieve this

After this launch:

Code Block
languagebash
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:

Code Block
languagebash
git commit

Add a commit message interactively, best containing the issue ID and title.

Pushing Changes to a Github User Repository

Code Block
languagebash
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:

Code Block
languagebash
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

Code Block
languagebash
git fetch izpack
git reset --hard izpack/master

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