Coding and Documentation Guideline

Environment

• Git on Codeberg (repositories here)
• Kotlin
• Gradle
• Intellij Idea community edition

Development rules

The project language in all documents, artifacts and conversations is english.

Writing code

1. Develop test driven
2. Strive for 100% test coverage¹
3. Do not suppress warnings and issues²
4. Only issue pull requests after successful ./gradlew fcheck

Writing documents

With regard to issue tracking, pull requests, branching, etc, for writing documents or UML diagrams, the same rules apply as for writing code (as far as possible).

Text documents are in markdown format, UMl diagrams in PlantUML

Development process

The development process is issue-driven. When you start contributing anything that is commited to the git repository, you need an issue for that.

For all release-related issues (i.e issues not for the Àpproved` milestone), the issue shall also be documented in the issues folder of the git repo:

1. From the ODO checkout folder, call: ./issues.sh start issue-number (e.g. ./issues.sh start 27). The issue number must belong to an existing issue.
2. Do whatever changes you have to do for the issues

3. All commits for the issue shall be prefixed by a hash sign and the issue number. Example:

   • #27 Updated Contrinution info
4. When all changes are done, execute ./gradlew fcheck and fix all issues found during this check run
5. Create a pull request for the release integration branch
6. Fix all issues found during code reviews
7. From the ODO checkout folder, call: ./issues.sh finish issue-number (e.g. ./issues.sh finish 27). The issue number must belong to a started issue.
8. Commit again

This way, the state of a branch with respect to the implemented or started issues is always clear.

Code reviews

Pull request include code reviews. Code reviews should not merely rubber-stamp the changes. The primary task is to ensure code quality: understandability, robustness, maintainability. Finding bugs in code reviews is also a good thing, but not the primary purpose. All comments from code reviews must be resolved in consensus between reviewer and author.

Branches

Main Branch

The main branch contains the most recent “officially released” version of ODO. It does not directly receive commits, but only merges from release integration branches (see below). In special cases, it may also get merges directly from issue branches, if the changes are independent of a specific release (e.g. website or code of conduct updates).

Release Integration Branches

Each release shall have an integration branch, where the work for that release is brought together. All issue branches (see below) for the release are merged here.

Issue Branches

Issue branch names shall start with the number of an issue, optionally followed by a description. All commit messages for changes made for the issue shall be prefixed with a hash sign and the issue number.

When an issue branch is merged to the integration branch or main branch, it shall be deleted.

Footnotes

¹ Jacoco is used for code coverage detection. Since this is a java tool, it sometimes has difficulties with jvm code generated by kotlin. If you have throughly investigated the code coverage and cannot see where the missing branches are, you may exclude small portions of the code from code coverage using the @Generated attribute.

² If you have a very good reason and tried hard to write suppression free code, you can suppress a warning or an issue. Please document your justification in the code.