Contributing to PermaplanT

Getting Started

Before you create any MR or issue, please make sure you read this document and that you have an Onboarding issue. Report all problems you found during getting started, as it is essential that entry barriers get reduced.

For any non-trival work, i.e., not only trivial fixes/updates in documentation or tests, there should be an underlying issue. You can create such issues yourself. Before you work on it, make sure the issue is:

  • clear enough described,
  • assigned to you and
  • "In Progress" in the project

Reporting a bug

If you find a bug in the code or a mistake in the documentation, you can help us by submitting an issue to our issue tracker or you can submit a Merge Request with a fix.

If you encounter a bug then please make sure to include the following information:

  • The version of the code you were using.
  • A clear and concise description of the problem.
  • A minimal, self-contained code sample that reproduces the problem (if possible).
  • Information about the environment in which the problem occurs (e.g. operating system, version of Rust, version of Diesel, etc.)

Using the bug template is the best way.

Pre-requisites

Development

The project uses pre-commit hooks to ensure a consistent style.

  1. Install pre-commit via pip or the package manager of you choice.
  2. If you had husky installed before make sure to remove preexisting hooks. git config --unset core.hooksPath
  3. Run pre-commit install.

Getting MRs merged

Once you created a MR, please request reviews, including also from @markus2330, who will usually also merge. Please never merge your MRs yourself.

Please make sure you fulfilled all basics of MRs (see template).

Commit messages should fulfill:

  • The first line in commit messages should be short.
  • From the third line you can have more elaborate descriptions of the changes.
  • Please refer to #issues/!MRs/@mention as useful, including closing your issues.

If requested, and in any case before you start making fundamental changes, create a decision before creating a code MR.

Branch naming

Branch names should follow this schema:

<name>/<issue-number>/<given-branch-name> where

  • name refers to any unique name that you consistently use throughout all your issues, such as your first name, username, or nickname
  • the issue number helps identify the issue
  • the given branch name should describe the changes concisely

E.g. a branch name could be markus/1287/fix-documentation.

Documentation

We have following pieces of documentation:

  1. General information should be in the mdbook.
  2. For the REST API we use utopia/swagger (in the backend).
  3. For the backend we use cargo doc.
  4. For the frontend we use storybook.

Sub-Projects

You can find more info on the development process here: