=== 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 ==== All TaskJuggler development is coordinated using the [http://git.or.cz/ Git revision control system]. All changes must be submitted using Git so that we can track the authorship of each submission. To contribute you need to have at least Git version 1.5.0 installed. Git was developed as a tool for the Linux Kernel developers but is now very popular with many other Open Source projects as well. Git and the TaskJuggler development environment are primarily designed to be used on Linux or Unix-like systems. While it is possible to use it on other systems such as Microsoft Windows, we do not recommend this. If you can't switch to a Linux installation for your TaskJuggler contributions, you should consider using a Linux Live (or bootable) CD/DVD or use a VmWare Player image of a Linux distribution. Make sure you have followed the steps described in the [Installation.html#Installation_Steps_for_Developers Installation Steps for Developers] chapter. If you have never used Git before, you need to configure it first. You need to set your name and email address. This information will be present in all patches that you submit. git config --global user.name "Your Name" git config --global user.email "firstname.lastname@domain.org" Do not use the development snapshots or send your patches as plain diff files. We'd like to ensure that we know who contributed to TaskJuggler. Therefor we are only accepting signed-off git patches with full user names and valid email addresses. Next you need to find the files where you want to make your modifications. 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 repository. With few exceptions the repository does not contain any generated files. ==== Creating a Patch ==== When you are done with your changes, it's a good idea to test them. In the taskjuggler directory run the following commands. cd taskjuggler3 rake test rake spec rake manual rake gem If there are no errors, you can check or test the result. If everything works fine, you can lock at your changes again. git diff The git-diff utility performs a line-by-line comparison of the files against the latest version in you local repository. Try to only make changes that have an impact on the generated files. Do not change indentation or line wrapping of paragraphs unless absolutely necessary. These kinds 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 exactly the same 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 version 2. In any case, the license must be [http://www.opensource.org/licenses an OSI accepted license] and be compatible with the rest of the project. Review all changes carefully. In case you have created new source files, you need to register them with your repository. git add FILENAME If you think you are done, you can commit your changes to your local repository. git commit -a Whenever you have made a certain change or added a certain feature, you should commit your changes to your local repository. This keeps patches small and makes reviewing them easier. The easier your patches can be reviewed, the more likely they will get in. The final step to submit your changes is to package them up and sign them. It is always a good idea to check for upstream changes again. git pull This makes sure you are really committing your patches against the latest version of the source code. In case there were upstream changes, you need to merge them first. Usually Git does this automatically. Refer to the [http://www.kernel.org/pub/software/scm/git/docs/user-manual.html Git manual] for details on resolving conflicts during merges. Now you can create the patch or patch-set. git format-patch -s origin This will generate a number of files starting with 5-digit file names. You then need to attach these files to a posting in the [http://www.taskjuggler.org/forum.php TaskJuggler Developer Forum]. ==== Contributing to the User Manual ==== The user manual is currently a rough port of the 2.x manual. It contains many inaccuracies and does not provide much more than a tutorial and a syntax reference. Any help to turn this into a real user manual is greatly appreciated. The manual is composed from 3 different sources. # The sources for normal pages are in MediaWiki format and can be found in the ''''manual'''' directory of the source distribution. # The information in the syntax reference is extracted from the TJP parser source code. It can be found in the file ''''lib/TjpSyntaxRules.rb''''. You can ignore all but the ''''doc(...)'''', ''''arg(...)'''' and ''''example(...)'''' sections. # The TJP examples are in the ''''test/TestSuite/Syntax/Correct'''' directory. The following commands build the HTML files for the manual in the ''''data/manual'''' directory. cd lib ruby UserManual.rb ==== Contributing to the Test Suite ==== The test suite can be found in the ''''test'''' and ''''spec'''' directories. It contains unit and system tests but is very rudimentary at the moment. Adding more system tests to the test/CSV-Report directory is probably the best place to start. Originally, TaskJuggler used classic Ruby unit tests, but a migration to [http://rspec.info/|RSpec-2] is in the works now. New tests should be written as RSpec tests unless they require infrastructure only available in the ''''test'''' directory. ==== Contributing to the Ruby code ==== For the first stable TaskJuggler III release we should have all 2.x features supported. The few things that break backwards compatibility should be documented in the [[TaskJuggler_2x_Migration]] section. In general, patches are very welcome. Please follow the coding style and naming conventions used in the existing code. Larger changes should be preceded by a discussion in the [http://www.taskjuggler.org/forum.php TaskJuggler Developer Forum]. ==== 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.