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. 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 continous development. It is important that you use a very recent snapshot as the developers might have made changes in the same files as you. This increases the chance for change collisions which can ultimately lead to the rejection of your contribution.

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 directoy 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. In case there are no errors, you can inspect the result. In case everything builds fine, you can 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 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. In case there are generated files included as well, please remove those files and regenerate the diff.

As you can see, the diff utility performs a line-by-line comparisons of the files. Therefor make sure, you 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. In case your contribution is large enough to justify a copyright claim, please indicate this in the patch. For modifications to existing files, we assume that your contribution falls under the same license as the modified file. All new files need to contain a license declaration.

Contributing Translations

Another possible area of contribution are translation of TaskJuggler into languages other than US english. Our development process is in pricinple prepared for translations, but the first translation will definitely be a bit bumpy to include. TaskJuggler has several hunderd 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 requires the translations to be updated as well. Please understand that we do not want to ship partial or outdated translations to our users.

Some final words to Contributors

We do welcome all contributions but please understand that we reseve 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.