Introduction

This is a set of best practices for IzPack developers and contributors.

It tries to be normative without putting too much bureaucracy in the processes.

General recommendations

1. Be friendly. The IzPack community has always been like that and we don't want that to change!
2. A new feature must always be documented, else there is no point in adding it!
3. Any idea or code change must be reported in an issue from our JIRA instance.
   This helps us to have an overview what's going on, to plan releases as well as generating complete and meaningful release notes.

Please keep in mind that most IzPack developers are volunteers that are not paid for developing it. We do it for fun on our free time, so please don't expect the same level of support as if we were a company (but we're doing our best to be as close to that as possible ).

Recommendations for developers

General recommendations

1. Always create a JIRA issue.
2. Use meaningful comments when doing a commit/push/pull request.
3. Always mention the JIRA issue that is related to your commit (e.g., "Fix for JIRA-123").
   Especially use the JIRA issue ID(s) in the title of the pull request - in this case there is automatically created a link to your pull request in the according JIRA issue(s).
4. When doing a commit based on a patch from a contributor, make sure to mention the contributor name in the comment (e.g. "Fix for JIRA-123. (Contributor name)" ).
5. Never commit incomplete changes (GIT is not a backup system).
6. Use a Git branch per issue, best with a JIRA issue ID as branch name.
   This allows you to easily send updates to pull requests, for instance if you get errors in the connected CI builders. 
7. Don't maintain Versions.txt anymore, we will extract release notes from JIRA starting from IzPack 4.0 and beyond.
8. Subscribe to the developer mailing list to follow IzPack development conversations.
9. Do not hesitate to pick new JIRA issues: both the other developers and the issue submitter will thank you for the work!
10. When you start working on an issue, don't forget to mark it as in progress so that we know that you're solving it!
    • For developing workflow will be: Open -> In progress -> Resolution -> Resolved -> Closed
    • For language file update: Open -> Resolved -> Closed
11. For more information about an issue please visit: What is an Issue?

Reporting issues and improving the documentation

1. Always create a JIRA issue in case of bug, improvement or new feature. You can follow progress of your issue there.
2. In case you located a necessary change in the code, don't send bigger patches, try to fork the master repository at Github and create a pull request instead.
   If you can't send a pull request for some reason and you have a patch, then attach it to the JIRA issue.
   Make sure you send a real diff-generated patch, not whole files or ZIPs with the modified files... (Several programs will generate this, for example: IntelliJ, Eclipse, Netbeans, TortoiseSVN,...)
   Anyway, sending pull requests most probably decreases the waiting time for your change to be merged, because it costs us less effort to handle it! 
3. Do not hesitate to attach screenshots and stack traces.
4. In case of a new feature proposal make sure to attach documentation to an according JIRA issue.
5. Subscribe to the developer mailing list if you want to follow IzPack development conversations.
   Avoid sending patches or copying code parts with patches to the mailing lists - this blows up discussion threads and probably nobody will be able to handle this, thus, it will be probably ignored. If you have particular suggestions, send it as pull request for an easy reviewed by everyone.
6. Respect code format styles! Otherwise we have a hard time trying to merge your code.

Code reviews

Before merging a pull request or a patch submitted by an external contributor, developers are expected to make a simple code review.

1. Look at the code carefuly to ensure that it is of good quality
2. Obviously... test it
3. Attach your review to the related JIRA issue
4. Send your review to the dev mailing-list if needed.

In case no other developer makes a comment after a few days, you can act as you decided: accept or reject it!

Code formatting

The src folder in the IzPack source code contains code style settings for Eclipse and IntelliJ IDEA.

Everyone has its own preferences, so to make everyone comfortable, here are a few things to respect.

The preferred style is ANSI-style, i.e., we prefer:

if (i == 0)
{
    doThis();
}
else
{
    doThat();
    andThat();
}

over:

if (i == 0) {
    doThis();
} else {
    doThat();
    andThat();
}

of even this:

if (i == 0) doThis();
else {
    doThat();
    andThat();
}

You may prefer putting braces on end of lines rather than on new lines, but in this case please don't be feel offended when we run code formatting from times to times

Taking the project from version repository you will have Eclipse settings for the IDE and code formatting. 

You should avoid long width lines. 80 characters is probably short nowadays. 100-120 characters looks like to be a good limit.

As of IzPack 5.0 we guarantee to provide at least Java 6 compatibility for installer execution, use it as the language source and target version.

Using 3rd-party libraries

• Please try to use built-in 3rd-party libraries in favor of implementing your own solutions.
  During coding, if you find code parts which might be replaced by patterns provided by existing 3rd-party libraries replace it.
  For example, Apache commons-io should be used for copying files or assembling filenames independently from the OS instead of accessing java.io and streams directly.
• Do not add new 3rd-party libraries which have to be merged by default to the resulting installer without a discussion (mailing lists, JIRA).
  The reason is not blowing up the installer size without a good reason.