contributing.md

Contributing

The target audience is people who use JCM already

If you use JCM, you may come across bugs, have ideas to implement, request features that could help you, or help implement or resolve issues.

The ideas and requests should go to the git's discussion . They can then be converted to issues.

Any bug should go in the git's issues . They are then open for solving. Please provide a minimal working example, so that we can reproduce and check that the verification passes ; also mention what you are working on to avoid multiple person doing the same work.

To help resolve an issue, you can clone the repository, create a new branch, commit your changes, then submit a pull request, explaining what are the choices you made for that issue.

Formatting

Pull requests must follow my personal Coding Styleguide

Tabs vs spaces

This project uses double-space for indentation. If you want to use tabs, you can ask git to modify the files when commiting them. A specific script makes that change, run it from the root project.

What this script does :

• create the file .git/info/attributes with *.java filter=tabspace . This will tell git to apply the filter tabspace on the *.java files ; if the file already exists it is deleted.
• append the line *.xml filter=tabspace to this same file. This will tell git to apply the filter tabspace on the *.xml files. This is because pom.xml files are also supposed to be space-started.
• run git config filter.tabspace.clean 'expand --tabs=2 --initial' : Before committing (clean) files applied the filtertabspace, git must run the expand command, replacing tabs with 2 spaces at the beginning of each line (--initial). This setting is repository-specific and can be removed by deleting the corresponding line in .git/config

Eclipse

For eclipse, a formatter xml and a cleanup xml are present in the meta/formatter/eclipse/ directory. You can load them from the "project properties > java code style" settings. Check "Enable project specific settings", then load them.

NOTE : you also need to change the save actions to make them meet the clean up actions. Save actions are done even when they are not present in the clean up.

Testing

New features, as well as bug fixes, are expected to test the minimum amount of use cases to ensure their main usage remains correct. For example, if you find a bug in a specific case, then that specific case must be tested against in the PR fixing it. This is important both for validating your PR, but also to ensure new modifications won't break the existing features

Disabling an existing test must be explained (typically no more relevant), at least in the commit or in the PR.

There are three main ways to add tests :

• checking your own class behavior and the generated file content,
• checking the generated class content and behavior,
• checking your plugin generator behavior.

In the main module

You can add usual unit tests in the main module's test dir.

Those are useful to check the behavior of specific parts of the projects, as well as the expected file content for a constructed JCM , typically using test utils

Implementation of parsers, validations, a well as code generation that does not persist at runtime (like javadocs, formatting, etc.) are expected to use this method.

Note that the helper class allows to compile a JCM in memory, however using the generated class can be cumbersome since you need to use reflect, unless you can cast it to a known interface. The next method allows easier manipulation, plus it permits to visually check the generated class files since they are exported and put in git. Therefore any later change in generated files can be tracked down to its commit.

In the jcodemodeltests module

This module uses a specific architecture :

1. generating classes should be annotated with @TestJCM and contain public methods that have a JCM and/or a JPackage parameter(s), or produce their own JCM. The convention is to end such a class with TestGen and place them in their own feature package. The method can be static; if not, a new instance is generated for each generating method.
2. those classes are parsed during the generate-test phase and the resulting (or requested) JCM is then exported in the src/generated/javatest dir. You can run the GenerateTestFiles in your IDE to generate them manually.
3. You can then add test classes in the usual src/test/java dir, that rely on those generated classes to check their behaviour and content. The convention is to place the test clas in the same package and with same start as the generating one, ending with Test.

General convention is as such, for feature Feat : generating is jcodemodel/tests/feat/FeatTestGen.java ; generated should be named eg jcodemodel/tests/feat/FeatExample1.java ; testing class should be jcodemodel/tests/feat/FeatTest.java

Testing your plugin's generator

A generator generates a JCM that the plugin will export when requested.

• The generator module should be in the plugin's generators submodule, with a module name starting with GEN (in its pom) ;
• The testing module should be in the plugins examples submodule, with a module name starting with XPL Generator .

For example, see the HelloWorld generator and its HelloWorld example modules. The former is named GEN Helloworld, the later XPL Generator Helloworld.

The testing module should not rely on internet data, as this can be an issue when remote host is down. With correct configuration the plugin will apply the generator and produce the classes in src/generated/java , allowing the usual unit tests in that module.