documentation and configuration for the AI coding assistant aider AI (#174)

Co-authored-by: Michael Hoennig <michael@hoennig.de>
Reviewed-on: https://dev.hostsharing.net/hostsharing/hs.hsadmin.ng/pulls/174
Reviewed-by: Timotheus Pokorra <timotheus.pokorra@hostsharing.net>

CONVENTIONS.md

@@ -0,0 +1,111 @@
+# Code Generting Conventions
+
+This document outlines the coding conventions for this project to be used by any AI agent.
+Ask the user to add these files to the AI agent before generating anything.
+
+## Initially
+
+At the beginning of each code generation session, determine all files which are not yet added, but might need to be changed and new files which might need to be created.
+
+Consider:
+- related Java-classes (*.java), including test classes
+- also Java-classes files in the same package as the mainly related class, e.g. patcher
+- related liquibase changesets (*.sql)
+- related openapi specs (*.yaml)
+- related i18n files (*.properties)
+
+Make sure production code and test code stay in sync,
+a change in one usually means the other has also to be changed.
+
+## Java Conventions (`*.java` files)
+
+### General Rules for Java Files
+
+These rules apply to all `.java` files in `src/**/*.java` but not those located in `**/generated/**`, `build/**`, or `.gradle/**` directories.
+
+1.  **Imports**: No wildcard imports. Unused imports must be removed.
+2.  **Indentation**: Use 4 spaces for indentation. Do not use tabs.
+3.  **End of File**: All files must end with a newline character.
+4.  **Formatting Control**: Spotless formatting can be temporarily disabled for specific code blocks using comments:
+    ```java
+    // spotless:off
+    // ... code that should not be formatted ...
+    // spotless:on
+    ```
+*   Follow existing code style and patterns within the project.
+    - Avoid reassigning variables and use `final var` where possible.
+    - Use `final` for method parameters.
+*   Use meaningful names for variables, methods, and classes.
+*   Write clear and concise comments where necessary to explain complex logic or intent.
+
+### toString via Stringify
+
+For assertions, keep in mind, that the Stringify implementation of the toString method skips null values. Thus, do not add null values in assertions if a Stringify-based toString implementation is tested!
+
+
+## PostgreSQL Conventions (`*.sql` files)
+
+Do only Liquibase changesets if they got created in the same branch.
+
+If they already exist in the master branch, generate a new Liquibase changeset.
+
+Add new Liquibase changesets to existing files where they belong,
+e.g. add a changeset with an ALTER TABLE directly after the related CREATE TABLE changeset. 
+
+If creating a new Liquibase changeset, there is no need to check if the change already exists, Liquibase will check that.
+
+## i18n Conventions (`*.properties` files)
+
+Use the English translation as the key in the `messages_*.properties` file,
+'=' and ' ' need to be quoted.
+
+## YAML Conventions (*.yaml files)
+
+Always use exactly 4 spaces for indentation.
+
+## General Conventions
+
+### general strategy
+
+At the beginning of each task, always determine all files which might need to be changed and new files which might need to be created. 
+
+### adding/deleting/amending fields/properties
+
+If a field in a database table is added, deleted or amended, the following steps must be taken:
+
+- The property must be added to the Java class on which the entity/entities are based; it must also be included in the toString method. Also amend the related unit test.
+
+- If the related entity has a patcher class, also add the new property to the patcher (usually ending with EntityPatcher) and its unit test (usually ending with EntityPatcherUnitTest).
+
+- The property must be included in (potentially 3) JSON resources (POST, GET, PATCH) in the OpenAPI specification.
+
+- The property must be added to the SQL table, so either enforce it via Liquibase or create a new Liquibase changeset.
+
+- The property must be included in the restricted view, which must be dropped and recreated due to the structural change; this view is generated by a stored procedure from the RBAC system.
+
+- The property must be added to the RBAC update trigger; for this, the RBAC DSL, the static method rbac() in the entity class(es), must be adjusted. The generator should automatically force Liquibase to reapply the changeset.
+
+- The tests may need to be adjusted; the new field should also be tested in an integration test for POST, GET, and PATCH.
+
+## While Generating CHanges
+
+Check all added files, if they need to be changed for the new feature.
+Most likely, all added files need some sort of change.
+
+Make sure production code and test code stay in sync,
+a change in one usually means the other has also to be changed.
+
+## Executing Commands
+
+### Generating from OpenAPI
+
+If OpenAPI specs (*.yaml) got changed, `gw openApiGenerate` needs to be executed.
+
+### Generating from RBAC DSL
+
+If any RBAC spec of an entity has changed, the static rbac() method in an entity class, `gw rbacGenerate` has to be executed before any test can run.
+
+### Test Execution
+
+Use the alias `gw-test` to run the tests with a proper environment.
+Do not suggest to run `./gradlew test`, it won't work without a correect environment.