Coding and Git guidelines

Code

• We adhere to the Kotlin Coding Conventions as described here: https://kotlinlang.org/docs/coding-conventions.html
• That includes directory structure, filenames, formatting and naming schemes. Keep in mind to use descriptive names.
• Set the kotlin formatter in the IDE to achieve consistent code formatting (how-to).
• Use TODO: xxx comments for uncompleted work and do not leave unnecessary code as comment.

Inclusion of MIT license in the source code

• use the REUSE SOFTWARE format to declare license and copyright
  • Documentation
  • Tutorial
  • API
• Each file needs to contain SPDX-FileCopyrightText and SPDX-License-Identifier tags in the header (this will automatically be checked by the reuse pre-commit git hook, see pre-commit).

  /*
  * SPDX-License-Identifier: MIT)
  * SPDX-FileCopyrightText: 2023 firstname lastname <email>
  * SPDX-FileCopyrightText: 2023 firstname lastname <email>
  */
  

Git

Main branch

• The main-branch is solely for production ready code.
• Commits to the main-branch are only allowed through approved pull requests (PR) without any outstanding change requests and through merge commits.
• Approval of pull requests should only be done after at least one peer has reviewed the proposed changes.
• If automated tests exist, these have to complete successfully before the PR can be merged.
• Only submit a PR when the feature/task/... is completely done.
• When creating a PR make sure to link it to the respective issue as shown here.

Any feature branches are created off of the main branch.

These rules should be persisted in the repositories branch protection rules.

Git Hooks & Pre-Commit

• Git Hooks are scripts that are run before a commit to check for issues in code such as missing semicolons, trailing whitespace, and debug statements.
• Pre-commit is a package manager for git hooks.
• Install pre-commit to automatically run the git hooks specified in .pre-commit-config.yaml when committing code.
• The pre-commit config contains a reuse hook for checking that all files contain a license tag. When committing an image (e.g. myimage.png), an additional file with the same name followed by the license extension (e.g. myimage.png.license) containing the SPDX-FileCopyrightText and SPDX-License-Identifier tags should also be committed for the reuse hook to pass.

Naming conventions

Branches

• Branches should follow the following naming strategy:

  <category>/<issue number>-<feature-name>
  

Please use hyphens ('-') instead of white spaces for the feature name.

Possible categories include

• feature
• bugfix
• hotfix
• ...

Following these branching naming rules helps in easily identifying the purpose of each branch and understanding its role in the development process.

Make sure that there exists only one branch per issue.

Commits

• Write meaningful and descriptive commit messages that succinctly describe the changes made.
• Use imperative language and start with a verb in the present tense for the commit message.

Potential workflow

A potential workflow could look something like this:

• Create a feature branch from main, for example feature/22-plugin-ui-tests
• Do some development, and commit the changes. start with a verb in the present tense
• Push the feature branch to your remote repository
• Create a Pull Request once the work on the feature is done
• Make changes that might be requested by reviewers
• Make sure that tests complete successfully
• If approval is given, rebase the branch and merge into main

Pull Request workflows:

• Whoever creates a PR is responsible for merging it
• Assign reviewers based on who you think is best able to perform a review. In general everybody should be able to review a PR
• As a reviewer: Here is a good description of how to review a PR

General

• Do not push code that does not build!

• Use only one account and one email

• Sign-off your commits!

  git commit -m "Text" --signoff
  

• Pair Programming:

  Include an empty line between the commit text and the Co-authored-by entries. Also be careful with the empty space between the name and the email of the authors.

  git commit -a -m "Description of commit
  
  > Co-authored-by: firstname lastname <email>
  > Co-authored-by: firstname lastname <email>
  "