# Process to contribute new features or to fix bugs
To propose a new feature, or to report a bug, first [create an issue][create-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 needed:
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`, `*.jrag` and `ResolverStubs.jrag` are already ignored by the main `.gitignore`.
All generated `*.ast`, `*.jadd` and `ResolverStubs.jrag` are already ignored by the main `.gitignore`.
## Generated files
## Generated Java files
Usually, all files are generated into a separate directory in `src/test/java-gen/`.
This location can be [configured](#build-configuration).
## Build configuration
Currently, test setup is configured within the `build.gradle` using a specialized Gradle task `RelastTest`.
Currently, the test setup is configured within `build.gradle` using a specialized Gradle task `RelastTest`.
| `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
@@ -65,5 +71,15 @@ Furthermore, empty lines, lines starting with `//` and the order of the error me
## 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 two Gradle tasks. The first produces the usual `.ast` and `.jadd` files, whereas the second task takes the `.ast` as input.
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](https://semver.org/)
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)