How to Contribute

Why contribute?

TaskJuggler is an Open Source Project. It was developed by volunteers mostly in their spare time. Made available under the GNU General Public license and similar licenses, TaskJuggler can be shared and used free of charge by anybody who respects the license conditions. Does that mean you can use it without worrying about anything? Clearly not! Though users have no legal obligation to contribute, you should feel a moral obligation to support Open Source in whatever way you can. This can range from helping out other users with their first Linux installation to actively contributing to the TaskJuggler Project, not just as a programmer. The following section describes, how you can contribute to any of the components that are part of the TaskJuggler software releases.

Preparing a contribution

To get started you need to download the most current development snapshot from the TaskJuggler Download Site. The development snapshot is updated once a day to provide access to the most recent developments. It is important that you use a very recent snapshot as the developers have probably made changes in the same files as you. This increases the chance for change collisions which could mean recreating your contribution from scratch.

Unpack the tarball as described in the installation section. Then rename the taskjuggler directory to something like taskjuggler-yourname. Then unpack the tarball again in the same place as before. You should now have a directory that contains two identical directory trees, each with a slightly different name of the top-level directory of each tree.

Next you need to find the files where you want to make your modifications. Please make your changes only in the taskjuggler-yourname directory. The other directory must be left unmodified. We need it later on to create a file that just contains your changes. Sometimes files will be generated from other files. Do not change those generated files. Your changes will be overwritten the next time you call the make utility. To identify those files, some familiarity with make and other Linux tools are helpful. Whenever there is a file with the same base name and the extension .in in the same directory, then the file is generated from the .in-file. You need to modify the .in-file, not the one with just the base name. Another indicator is the fact that the file is not part of the tarball. With few exceptions that can be identified by the .in-file rule above, the tarball does not contain any generated files.

Creating a Patch

When you are done with your changes, it's a good idea to test them. Type

make
in the taskjuggler-yourname directory. If there are no errors, you can check or test the result. If everything builds fine, you can then remove all generated files again by typing
make distclean
Now you can generate a file that just contains your modifications by typing
diff -ru taskjuggler-svn taskjuggler-yourname > taskjuggler-yourname.diff
Inspect the generated diff file taskjuggler-yourname.diff and make sure it only contains diffs for files that you have changed and the changes are the way you want them to be. If there are generated files included in the diff, please remove those files and regenerate the diff.

The diff utility performs a line-by-line comparisons of the files. Try to only make changes that have an impact on the generated files. Do you change indentation or line wrapping of paragraphs. These kind of changes increase the size of diff files and make it much harder to evaluate the patches. When making changes to the program code, please use our coding style. If your contribution is large enough to justify a copyright claim, please indicate what copyright you claim in the patch. For modifications to existing files, we will assume that your contribution falls under the same license as the modified file. All new files will need to contain a license declaration, preferably GPL.

Contributing Translations

Another possible area of contribution are translation of TaskJuggler into languages other than US English. Our development process is in principle prepared for translations, but the first translation will definitely be a bit difficult to do. TaskJuggler has several hundred messages and more than hundred pages of documentation. Any translation is a significant effort and an ongoing commitment. TaskJuggler is still actively developed and this will require the translations to be updated as well. Please understand that we do not want to ship partial or outdated translations to our users, so please ensure you or a group of people are willing to maintain the translations.

Some final words to Contributors

We do welcome all contributions but please understand that we reserve the right to reject any contribution that does not follow the above guidelines or otherwise conflicts with the goals of the TaskJuggler team. It is a good idea to contact the team prior to making any larger efforts.