Merge branch '21-create-guides-for-contributing' into 'master'

Resolve "Create guides for contributing"

Closes #21

See merge request !8

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][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 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).
+
+## Build configuration
+
+Currently, the test setup is configured within `build.gradle` using a specialized Gradle task `RelastTest`.
+An example configuration might look like:
+
+```groovy
+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](/../#supported-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](#build-configuration).
+This project uses JUnit 5 as test framework.
+
+# Creating special tests
+
+Aside from the [normal tests](#creating-normal-test-cases), there are some special tests.
+
+## Negative parser tests
+
+To check, errors are found and contain the correct messages, one test [`Errors`](/../blob/master/src/test/java/org/jastadd/relast/tests/Errors.java) 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](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)
+
+[create-issue]: https://git-st.inf.tu-dresden.de/jastadd/relational-rags/issues/new

README.md

@@ -35,7 +35,20 @@ Note that you may have to change
 - the directory of `relast.jar`
 - the `.relast` file(s) both as argument(s) and input file(s)
 - the output files
-- parameters of RelAST (in this case, the list classes were renamed)
+- parameters of RelAST (in this case, the list classes were renamed), the following table shows the supported ones
+
+## Supported command-line options
+
+|         Name        |                                             Description                                              |    Default    |
+|---------------------|------------------------------------------------------------------------------------------------------|---------------|
+| `--ast`             | Print AST (ignores `--quiet` option)                                                                 | Do not print  |
+| `--grammarName`     | Directory and file prefix for the generated grammar and jrag created by RelAST.                      | `Grammar`     |
+| `--jastAddList`     | Alternative name for `List` nodes (has to match the option `--List` of JastAdd or its default List). | `List`        |
+| `--listClass`       | Set the class name of the nonterminal reference list                                                 | `ArrayList`   |
+| `--quiet`           | Do not output anything on stdout.                                                                    | Normal output |
+| `--resolverHelper`  | Set to `true` to generate means for lazy resolving.                                                  | `false`       |
+| `--serializer`      | Generate a (de-)serializer. One of {`jackson`, `jackson-json-pointer`, `jackson-manual-references`}. | No serializer |
+| `--useJastAddNames` | Set to `true` to use accessor names for relations matching JastAdd naming convention.                | `false`       |
 
 ## Supported relations
 

build.gradle

@@ -151,49 +151,26 @@ task updateVersion {
 
 processResources.dependsOn updateVersion
 
-task preprocessRelationTest(type: JavaExec, group: 'verification') {
-
-    doFirst {
-        delete 'src/test/jastadd/relations/Relations.ast', 'src/test/jastadd/relations/Relations.jadd'
-    }
-
-    classpath = sourceSets.main.runtimeClasspath
-    main = 'org.jastadd.relast.compiler.Compiler'
-    //noinspection GroovyAssignabilityCheck
-    args 'src/test/jastadd/relations/Relations.relast', '--quiet', '--useJastAddNames', '--file', '--grammarName=src/test/jastadd/relations/Relations'
-}
-
-task doublePreprocessRelationTest(type: JavaExec, group: 'verification') {
-
-    doFirst {
-        delete 'src/test/jastadd/relations/Relations2.ast', 'src/test/jastadd/relations/Relations2.jadd'
-    }
-
-    classpath = sourceSets.main.runtimeClasspath
-    main = 'org.jastadd.relast.compiler.Compiler'
-    //noinspection GroovyAssignabilityCheck
-    args 'src/test/jastadd/relations/Relations.ast', '--quiet', '--useJastAddNames', '--file', '--grammarName=src/test/jastadd/relations/Relations2'
+task firstRelationsRun(type: RelastTest) {
+    relastFiles 'src/test/jastadd/relations/Relations.relast'
+    grammarName = 'src/test/jastadd/relations/Relations'
+    useJastAddNames = true
+    packageName = 'relations.ast'
+    moreInputFiles 'src/test/jastadd/Utils.jadd'
 }
 
-task compileRelationTest(type: JavaExec, group: 'verification') {
+task secondRelationsRun(type: RelastTest, dependsOn: firstRelationsRun) {
+    relastFiles 'src/test/jastadd/relations/Relations.ast'
+    grammarName = 'src/test/jastadd/relations/Relations2'
+    useJastAddNames = true
+    packageName = 'ignored'
 
-    doFirst {
-        delete 'src/test/java-gen/relations'
+    doLast {
+        delete fileTree('src/test/java-gen/ignored')
+        delete 'src/test/java-gen/ignored'
     }
-
-    classpath = sourceSets.main.runtimeClasspath
-    main = 'org.jastadd.JastAdd'
-    //noinspection GroovyAssignabilityCheck
-    args '--o=src/test/java-gen/', '--package=relations.ast',
-            'src/test/jastadd/relations/Relations.ast',
-            'src/test/jastadd/relations/Relations.jadd',
-            'src/test/jastadd/Utils.jadd'
 }
 
-test.dependsOn compileRelationTest
-compileRelationTest.dependsOn doublePreprocessRelationTest
-doublePreprocessRelationTest.dependsOn preprocessRelationTest
-
 task compileConstructorTest(type: RelastTest) {
     relastFiles 'src/test/jastadd/constructors/Constructors.relast'
     grammarName = 'src/test/jastadd/constructors/Constructors'