1. Branching model

The project uses "trunk based development" as the branching model.

Trunk-based development is a Git branching model where all developers work collaboratively on a single central branch called main, integrating their changes frequently — often multiple times per day.
The goal is to avoid long-lived feature branches, minimize complex merges, and keep the codebase continuously releasable through automated testing and continuous integration.
This approach supports rapid delivery cycles and helps teams prevent "merge hell" by making small, incremental commits instead of large, infrequent integrations.

Each pull request requires at least 2 reviews, one of which must be done by a member of @infoteam-Software-AG/kg-java.
The main branch is protected, thus direct pushes to main are not allowed.

Further reading: https://trunkbaseddevelopment.com/

1.1. Branch names

Creating branches for issues is automated via chat messages.

When you need a branch to resolve an issue, simply add a comment to the issue containing /create-issue-branch or /cib.

The preconfigured branch prefixes are as follows:

- label: enhancement
  prefix: feature/
- label: task
  prefix: feature/
- label: Story
  prefix: feature/
- label: bug
  prefix: bugfix/
- label: documentation
  prefix: docs/
- label: '*'
  prefix: issues/

2. Quality of life

2.1. Custom Git settings for project

If you want to use a specific real name or e-mail for the project, go to the project root folder and type:

git config --local user.email "other-email@to-be.used"
git config --local user.name "My Other Name"

2.2. Git hook to check formatting

As ill-formatted code will break CI/CD builds, it is a good idea to set up a pre-commit hook.
The hook will apply the Spotless rules to the whole project.

To set up the hook, create file in the project root at .git/hooks/pre-commit and make it executable:

touch .git/hooks/pre-commit
chmod 664 .git/hooks/pre-commit

Open the file in your favorite text editor and add:

#!/bin/sh
mvn spotless:apply

then save and your hook is ready.

3. IntelliJ IDEA recommendations

3.1. Required plugins

3.2. Recommended plugins

  • Spotless Applier by Dimitrii Lipiridi
    Homepage: https://plugins.jetbrains.com/plugin/22455-spotless-applier
    The plugin enhances your development workflow by seamlessly integrating Spotless Maven tasks directly within the IntelliJ IDE.

    This requires the plugin’s shortcuts to be redefined as the original shortcuts cannot be reached with a German keyboard layout:

    • open "File" > "Settings"

    • go to "Keymap" in the left-hand menu

    • in the main area open the "Plugins" folder and the look for the "Spotless Applier" folder

    • in the "Spotless Applier" folder double-click each shortcut, choose "Add Keyboard Shortcut" and redefine as follows

      • Reformat File With Spotless: CTRL+ALT+,

      • Reformat Project With Spotless: CTRL+ALT+SHIFT+,

3.3. Suggested plugins

4. Maven cheat sheet

4.1. Default build

mvn clean verify

4.2. Run the application with Maven

mvn spring-boot:run

4.3. Build the application enforcing quality gates

mvn clean verify -PqualityGates

4.4. Build the Asciidoc documentation:

mvn verify -PgenerateDocs

HTML is published in target/docs