Contributing

From September 2011, The Grinder source code and documentation is hosted in a Git repository. You can obtain a copy from Sourceforge.

Note, the documentation branch (docs) refers to the latest released version of The Grinder, and so can lag the Git HEAD.

If you want to build The Grinder from source, you'll need:

Dependencies on third party libraries are managed by Maven.

The following optional packages are necessary to run The Grinder unit tests.

If you feel you have something worth sharing, please first discuss your ideas on the grinder-development list. If your ideas develop into code, you can submit patches to this list. Patches should be generated using git format-patch -M -B against either the latest released version of The Grinder 3, or the Git master branch. Patches should also include updates to the relevant documentation sources. Please include a statement in your email that you, and where appropriate your employer, are happy for your work to be distributed under the terms of The Grinder license.

Coding Standards

Contributions of Java code should be checked with the FindBugs static analysis tool, and pass with no warnings. A FindBugs filter file for The Grinder can be found in the etc directory.

I actively track code coverage, and expect full JUnit tests for new code. I use Clover; you can get a free Clover license for development of The Grinder.

I have a strong preference for classes that take all the things they need as parameters to their constructors (like constructor injection), and for contracts to be specified in terms of Java interfaces. This makes unit testing easier, and forces the developer to think about the purpose and contract of each class.

Please pay attention to the existing coding style of The Grinder. There is a Checkstyle configuration file for The Grinder in etc which you should use to check the formatting of your code. You can do this using the checkstyle:checkstyle Maven goal. Checkstyle helps to make the code readable, catches quite a few silly errors, and makes applying patches a much nicer experience. Patches that do not pass the Checkstyle rules will be rejected.

Documentation can always be improved. Tutorials and examples from users of The Grinder are always welcome. Please mail suggestions, corrections, and improvements to the grinder-development@lists.sourceforge.net mailing list.

The Subversion repository for The Grinder documentation is public. Authors who have made valuable contributions can ask for check-in rights via the grinder-development@lists.sourceforge.net mailing list.

If you are bilingual you might fancy translating the console into a language of your choice. Jose Antonio Zapta Rey did just this and produced a Spanish translation.

This translation will be automaically be the default for users with their locale set correctly for the Spanish language. If your locale is set otherwise and you are curious to try this out, specify the Java user.language system property.

java -Duser.language="es" net.grinder.Console

Bertrand Ave produced a translation for French speaking users (user.language="fr"), Huibert Alblas produced a German translation (user.language="de"), and Italian, Polish, Russian, and Chinese translations have since followed.

How to provide or update a translation

The translation properties files are stored in the source repository. Getting the file directly from the repository will make your translation is as up to date as possible, and avoid duplicating effort. The definition of all English text used by the console is contained in the Console.properties file. Individual translations are contained in Console_XX.properties where XX is the two letter ISO 639 language code. For example, the Spanish translation is contained in Console_es.properties. If you want to update an existing translation, make a copy of the file. If you want to create a new translation, create a new file.

Use a text editor to edit your file. Existing translations will guide you as to which properties you need to translate. You should only include properties that have translated text. Don't include properties such as scriptTab.image that refer to images, or properties that refer to logical names such as action.menu.

To test your file before contributing it, place the file in a directory structure matching translation/net/grinder/console/swingui/resources and add the translation directory to the start of the CLASSPATH that you use to start the console. You may need to set user.language as described above. The Grinder is being actively developed, and you will not be able to test new translation properties added since the last release without building the latest source from the repository. If you can't find the time for this, an untested translation is better than no translation.

Post your translation to the grinder-development list, stating the git hash of the revision upon which it was based. Please also include a statement that you are happy for your work to be distributed under the terms of The Grinder license.

There are many projects that build upon, or otherwise complement, the features provided by The Grinder. Some of these are referenced from the links page.

On release, The Grinder jar files are deployed to the Sonatype OSS Nexus repository, and will be synchronised to Maven Central soon afterwards.