CONTRIBUTING.md

Process to contribute new features or to fix bugs

To propose a new feature, or to report a bug, first create an issue and add labels accordingly. Working on such issues is done by creating a merge request from the issue page, which 1) creates a new branch to work on, and 2) creates a new WIP merge request for the new branch. Once done (and new tests are written to ensure, a bug is really fixed, and the feature does the right thing), the merge request will be accepted and merged into master.

Creating normal test cases

A test usually defines a grammar, optionally some attributes and a Test class. It then normally runs RelAST followed by JastAdd. To create a new test, the following four ingredients are involved:

Specification

Here, the grammar and attributes to be compiled are contained. Use src/test/jastadd/$YourTestName as directory to put your files into. All generated *.ast, *.jadd and ResolverStubs.jrag are already ignored by the main .gitignore.

Generated Java files

Usually, all files are generated into a separate directory in src/test/java-gen/. This location can be configured.

Build configuration

Currently, the test setup is configured within build.gradle using a specialized Gradle task RelastTest. An example configuration might look like:

task compileMultipleTest(type: RelastTest) {
    relastFiles 'src/test/jastadd/multiple/Part1.relast',
                'src/test/jastadd/multiple/Part2.relast',
                'src/test/jastadd/multiple/Part3.relast'
    grammarName = 'src/test/jastadd/multiple/Multiple'
    useJastAddNames = true
    packageName = 'multiple.ast'
    moreInputFiles 'src/test/jastadd/Utils.jadd'
}

The following options are supported, similar to the command-line options:

Name	Description	Required	Default
relastFiles	Input grammar(s). Either one or multiple files separated by comma.	Yes	none
grammarName	Directory and file prefix for the generated grammar and jrag created by RelAST.	Yes	none
useJastAddNames	Set to true to use accessor names for relations matching JastAdd naming convention.	No	false
packageName	Name of the package for the Java files generated by JastAdd.	Yes (not enforced)	The empty package
moreInputFiles	Additional files as input for JastAdd.	No	No additional files
resolverHelper	Set to true to generate means for lazy resolving.	No	false
jastAddList	Alternative name for List nodes. Will be passed to both RelAST and JastAdd.	No	List
serializer	Name of supported serializer. One of {jackson, jackson-json-pointer, jackson-manual-references}.	No	No serializer

Test files

The actual test source, usually located in src/test/java/ in the package org.jastadd.relast.tests. Pay attention to import the correct nonterminal classes by using the same package as configured. This project uses JUnit 5 as test framework.

Creating special tests

Aside from the normal tests, there are some special tests.

Negative parser tests

To check, errors are found and contain the correct messages, one test Errors is used. Here, the RelAST compiler is invoked manually, and the actual error messages are compared to expected ones for each grammar in src/test/jastadd/errors. The expected messages can contain the special word $FILENAME to refer to the filename of the grammar, if there is only one, or $FILENAME1, $FILENAME2 etc., if there are many. Furthermore, empty lines, lines starting with // and the order of the error messages are ignored.

Output diff

Currently, there is one test to test whether the output of RelAST is a valid input for RelAST and produces the same output again. To achieve this, there are two Gradle tasks. The first produces the usual .ast and .jadd files, whereas the second task takes the .ast as input. The test then ensures, that both output grammars are identical.

Publishing

To publish a new version, the following needs to be done:

1. Create a new annotated tag with an appropriate version number increase (major, minor, patch) described in semantic versioning
2. If not already present, create a new file gradle.properties with two entries repoUser and repoPassword for our Nexus repository.
3. Run ./gradlew publish -PwithNewVersion (maybe also adding -PasSnapshot to create a SNAPSHOT release)