Contribution Guidelines

• 1: Pull Request Etiquette
• 2: Style Guide
• 3: PR Check List

git commit --allow-empty -m "trigger CI" && git push

1 - Pull Request Etiquette

Authors

PRs should adhere to the following rules.

• Familiarize yourself with coding style, ./architectural patterns, and other contribution guidelines.
• No surprise PRs. Before submitting a PR, open a discussion or an issue outlining the planned work and give people time to comment. Unsolicited PRs may get ignored or rejected.
• Create focused PRs. Work should be focused on one particular feature or bug. Do not create broad-scoped PRs that solve multiple issues or span signficant portions of the codebase as they will be rejected outright.
• Provide a clear PR description and motivation. This makes the reviewer’s life much easier. It is also helpful to outline the broad changes that were made, e.g. “Changes the schema of XYZ-Entity: the age field changed from long to String”.
• If 3rd party dependencies are introduced, note them in the PR description and explain why they are necessary.
• Stick to the established code style, please refer to the styleguide document.
• All tests should be green, especially when your PR is in "Ready for review"
• Mark PRs as "Ready for review" only when the PR is complete. No additional commits should be pushed other than to incorporate review comments.
• Merge conflicts should be resolved by squashing all commits on the PR branch, rebasing onto main, and force-pushing. Do this when your PR is ready to review.
• If you require a reviewer’s input while it’s still in draft, please contact the designated reviewer using the @mention feature and let them know what you’d like them to look at.
• Request a review from one of the technical committers. Requesting a review from anyone else is still possible, and sometimes may be advisable, but only committers can merge PRs, so be sure to include them early on.
• Re-request reviews after all remarks have been adopted. This helps reviewers track their work in GitHub.
• If you disagree with a committer’s remarks, feel free to object and argue, but if no agreement is reached, you’ll have to either accept the committer’s decision or withdraw your PR.
• Be civil and objective. No foul language, insulting or otherwise abusive language will be tolerated.
• The PR titles must follow Conventional Commits.
  • The title must follow the format as <type>(<optional scope>): <description>. build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test are allowed for the <type>.
  • The length must be kept under 80 characters.
  See check-pull-request-title job of GitHub workflow for checking details.

Reviewers

• Please complete reviews within two business days or delegate to another committer, removing yourself as a reviewer.
• If you have been requested as reviewer, but cannot do the review for any reason (time, lack of knowledge in particular area, etc.) please comment that in the PR and remove yourself as a reviewer, suggesting a stand-in. The CODEOWNERS document should help with that.
• Don’t be overly pedantic.
• Don’t argue basic principles (code style, architectural decisions, etc.)
• Use the suggestion feature of GitHub for small/simple changes.
• The following could serve you as a review checklist:
  • No unnecessary dependencies in build.gradle.kts
  • Sensible unit tests, prefer unit tests over integration tests wherever possible (test runtime). Also check the usage of test tags.
  • Code style
  • Simplicity and “uncluttered-ness” of the code
  • Overall focus of the PR
• Don’t just wave through any PR. Please take the time to look at them carefully.
• Be civil and objective. No foul language, insulting or otherwise abusive language will be tolerated. The goal is to encourage contributions.

The technical committers

(as of Sept 15, 2024)

• @wolf4ood
• @jimmarino
• @bscholtes1A
• @ndr_brt
• @ronjaquensel
• @juliapampus
• @paullatzelsperger

2 - Style Guide

In order to maintain a coherent codebase, every contributor must adhere to the project style guidelines. We assume contributors will use a modern code editor with support for automatic code formatting.

Checkstyle configuration

Checkstyle is a tool that statically analyzes source code against a set of given rules formulated in an XML document. Checkstyle rules are included in all EDC code repositories. Many modern IDEs have a plugin that runs Checkstyle analysis in the background.

Our checkstyle config is based on the Google Style with a few additional rules such as the naming of constants and Types.

Note: currently we do not enforce the generation of Javadoc comments, even though documenting code is highly recommended.

Running Checkstyle

Checkstyle is run through the checkstyle Gradle Plugin during gradle build for all code repositories. In addition, Checkstyle is enabled in all GitHub Actions pipelines for PR validation. If checkstyle any violations are found, the pipeline will fail. We therefore recommend configuring your IDE to run Checkstyle:

• IntelliJ IDEA plugin [recommended]
• Eclipse IDE [recommended]

IntelliJ Code Style Configuration

If you are using Jetbrains IntelliJ IDEA, we have created a specific code style configuration that will automatically format your source code according to that style guide. This should eliminate most of the potential Checkstyle violations from the get-go. However, some code may need to be reformatted manually.

Intellij SaveActions Plugin

To assist with automated code formatting, you may want to use the SaveActions plugin for IntelliJ IDEA. Unfortunately, SaveActions has no export feature, so you will need to manually apply this configuration:

Generic .editorConfig

For most other editors and IDEs we’ve supplied .editorConfig files. Refer to the official documentation for configuration details since they depend on the editor and OS.

3 - PR Check List

It’s recommended to submit a draft pull request early on and add people previously working on the same code as reviewers. Make sure all automatic checks pass before marking it as “ready for review”:

Before submitting a PR, please follow the steps below.

Open a Discussion or File an Issue

Do not submit a PR without first opening an issue (if the PR resolves a bug) or creating a discussion. If a bug fix requires a significant change or touches on critical code paths (e.g. security-related), open a discussion first.

Coding Style

All code contributions must strictly adhere to the Style Guide and design principles outlined in the Contributor Technical Documentation. PRs that do not adhere to these rules will be rejected.

All artifacts must include the following copyright header, replacing the fields enclosed by curly brackets “{}” with your own identifying information. (Don’t include the curly brackets!) Enclose the text in the appropriate comment syntax for the file format.

Copyright (c) {year} {owner}[ and others]

This program and the accompanying materials are made available under the
terms of the Apache License, Version 2.0 which is available at
https://www.apache.org/licenses/LICENSE-2.0

SPDX-License-Identifier: Apache-2.0

Contributors:
  {name} - {description}

Commit Messages

Git commit messages should comply with the following format:

<prefix>(<scope>): <description>

Use the imperative mood as in “Fix bug” or “Add feature” rather than “Fixed bug” or “Added feature” and mention the GitHub issue e.g. chore(transfer process): improve logging.

All committers and all commits, are bound to the Developer Certificate of Origin. As such, all parties involved in a contribution must have valid ECAs. Additionally, commits can include a “Signed-off-by” entry.

Testing and Documentation

All submissions must include extensive test coverage and be fully documented:

• Add meaningful unit tests and integration tests when appropriate to verify your submission acts as expected.
• All code must be documented. Interfaces and implementation classes must have Javadoc. Include inline documentation where code blocks are not self-explanatory.
• If a new module has been added or a significant part of the code has been changed, and you should be seen as the contact person for any further changes, please add appropriate information to the CODEOWNERS file. You can find instructions on how to do this at https://help.github.com/articles/about-codeowners/. Please note that this file does not represent all contributions to the code. What persons and organizations actually contributed to each file can be seen on GitHub and is documented in the license headers.