Contributing
The Source
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.
What do I need to build The Grinder?
If you want to build The Grinder from source, you'll need:
| Java Standard Edition 6 ("Java 6") or higher | |
| Apache Maven 3.0.3 |
Dependencies on third party libraries are managed by Maven.
What do I need to test and package The Grinder?
The following optional packages are necessary to run The Grinder unit tests.
| Jython 2.1, 2.5.0, 2.5.1, 2.5.2 | to verify The Grinder works with alternative Jython versions |
How to give back
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 help wanted
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.
Internationalisation help wanted
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.
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.
Writing software that depends on The Grinder
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.