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:
- Create a new annotated tag with an appropriate version number increase (major, minor, patch) described in semantic versioning
- If not already present, create a new file
gradle.properties
with two entriesrepoUser
andrepoPassword
for our Nexus repository. - Run
./gradlew publish -PwithNewVersion
(maybe also adding-PasSnapshot
to create a SNAPSHOT release)