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 for the IZPACK project.
      Use your Xircles account to log in to JIRA.
      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.
    • Make sure the existing tests pass

      Code Block
      mvn test
      mvn -Pwith-gui-tests test


    • 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.

...

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

...

  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



  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:

    Code Block
    languagebash
    git remote add izpack https://github.com/izpack/izpack.git

     

 

Creating and Checking Out a Local GIT Branch From Uncommitted Changes

...

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:

Code Block
languagebash
git commit

...

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

If you leave out the -m option you can add a commit message interactively, best containing the issue ID and title.

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

Code Block
languagehtml/xml
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

Code Block
languagebash
git push origin IZPACK-123

...

Code Block
languagebash
git checkout master
git branch -D IZPACK-123

Reset a Local Repository To The Current Development State

...

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

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

...