GitLab update scheduled for Friday, January 21th between 08:15 and 08:45 CET. If unpleasant, please contact René or Martin.

CONTRIBUTING.md 7.07 KB
Newer Older
1
2
3
4
# 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.
5
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 `develop`.
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

# 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

66
To check, errors are found and contain the correct messages, one test [`Errors`][Errors.java] is used.
67
68
69
70
71
72
73
74
75
76
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.

77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
# Releases and Publishing (Maintainer only)

Important information:

- Currently, we are publishing to a private Nexus Maven repository only.
- We are using [git-flow][git-flow], so only new merge requests are considered for releases to appear in the `master` branch.
- The version is set in the configuration file [RelASTVersion.properties][RelASTVersion.properties].

The workflow:

1) Finish your work with the current feature(s) and merge those back in `develop`.
1) Choose a new version number `$nextVersion` depending on the introduced changes **following [semantic versioning][semantic-versioning]**.
1) Create a new release branch named `release/$nextVersion` and switch to this branch.
1) Set the version number in the config file calling `./gradlew newVersion -Pvalue=$nextVersion`
1) Commit this change.
1) (Optional) Build a new jar file calling `./gradlew jar` (this is automatically called in the publish step and only used to test the newly set version number)
1) Check, if everything works as planned, e.g., version number is picked up when running the application with `--version`, and all test succeed.
1) Merge the release branch into `master` (using a merge request) and also back into `develop`.
1) Delete the release branch.
1) [Create a new release][create-release]. Choose the following:
    - *Tag name*: the chosen version number
    - *Create from*: leave the default `master`
    - *Message*: "Version " and the chose version number
    - *Release notes*: list the (important) changes compared to the last release, prepend a link to the built jar using the line `[:floppy_disk: publish-relast-poc-$nextVersion.jar](/../../../-/jobs/$jobNumber/artifacts/raw/build/libs/publish-relast-poc-$nextVersion.jar?inline=false)` replacing `$jobNumber` with the `jar` job of the pipeline run after the merge request, and `$nextVersion`
1) Publish the built jar to the maven repository calling `./gradlew publish`

[git-flow]: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow
[Errors.java]: /../blob/master/src/test/java/org/jastadd/relast/tests/Errors.java
[RelASTVersion.properties]: /../-/blob/master/src/main/resources/RelASTVersion.properties
[semantic-versioning]: https://semver.org/
[create-release]: /../-/tags/new
108
[create-issue]: https://git-st.inf.tu-dresden.de/jastadd/relational-rags/issues/new