Contributing to PermaplanT

Getting Started

Before you create any Merge-Request (MR) or issue, please make sure you read this document and started with your 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.

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

  • The version of the code you were using (SHA-1 or branch).
  • A clear and concise description of the problem, what did you expect and what is the case.
  • 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.

For more information how to create issues read here.

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.

Furthermore, to increase code quality please use following code plugins:

Before creating MRs

  • Make sure to review about three times more MRs than you create MRs.
  • Make sure an issue exist, is assigned to you and is in the iteration.
  • If requested, and in any case before you start making fundamental changes, create a decision before creating a MR.

When Creating MRs

  • Make sure to use the template "Merge Requests" (.gitlab/merge_request_templates/Merge Request.md)
  • Make sure links to check tasks and to fill out what reviewers should check
  • Keep "Delete source branch when merge request is accepted. " ticked
  • If it is not ready to be looked at yet, start with a draft to avoid unnecessary reviews.
  • Branch name should be <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.
  • (optional) write in the MR or issue what was done or where you are stuck after changes were pushed (maybe with SHA to refer to code)

For more information how to do it read here.

Getting MRs Merged

Once you finished a MR (you do not plan to push any further commits):

  • please make sure you fulfilled all basics of MRs (see template)
  • please request reviews, from at least two people, e.g. your buddy (you get assigned in the first meeting)
  • set the issue to status::in review
  • set the MR as MRs::please review

Once you:

  • got two approval
  • CI passes
  • etc.

Then:

  • set the MR to MRs::please merge and
  • request the review of @markus.raab

Please never merge your MRs yourself. Exception: Fixing broken CI.

You are generally allowed to push commits to other MRs, especially if this fixes the CI etc. Suggestions are the preferred way during reviews, as they are very clear and easier to apply.

Commit Messages

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.

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:

Iteration

We have weekly iterations with a meeting on Monday 9:00. To prepare for the next iteration, everything related to the iteration planning etc. should be done until Thursday 23:59. Late Sunday or Monday morning are the worst times for actions related to iteration planning. Make sure to:

  • Write in advance to @markus.raab and @e12313407 if you cannot come.
  • Do all the "Tasks for Everyone", including:
    • review at least 2+2*X (X = number of created MRs), including meeting MR
    • fix own MRs to get it ready to merge
    • finish your assigned tasks of the iteration
    • Schedule your working time in PermaplanTWork calendar.
      • Create a new Event for each timeslot you plan to work and name it "{Name} (available)" example: "Liza (available)".