Contributing to pib🚀

Contributing to pib🚀

 

First off, thank you for considering contributing to pib! We welcome all contributions, including bug reports, feature requests, documentation improvements, and code changes.🎉

This page will allow you to delve into ways to develop an open source project, as well as introduce you the basic things in the process of developing software for pib.

Make sure you read the Community Development process.

If you want to help us, but still don’t quite know how and where to start, read the Development Environment Setup.

 


Code Contributions 💻

If You Are a Contributor


Clone the repository to your local machine using the following command:

git clone <repository-url>

If You Do Not Have Write Access


You have to Fork the repository using GitHub interface (ensure you deselect “Fork only main”)
Choose the develop branch in your fork repository.

Clone your fork locally.
Clone the repository to your local machine using the following command:

git clone https://github.com/your-username/pib-backend.git git remote add upstream https://github.com/pib-rocks/pib-backend.git

Create a new branch

 

Start your branch from develop for any new feature, fix or code refactor.
Make a new branch for your modifications using the following command:

git checkout -b PR-XXX(your ticket number)

Don’t forget to write a ticket number which always must be contained in the name, for example: PR-111
This makes it simpler to manage and isolate your changes.


Development

 

  • Add new features

  • Write tests for new features

  • Update documentation when needed

  • Please also consider the mentioned coding guidelines


Commit your changes

 

The commit messages should follow the Conventional Commits specification. The easiest way to ensure that this is achieved, is by using the Conventional Commits VS-Code extension. With the extension installed and with VS-Code opened, type ‘Ctrl+Shift+P' to open the command palette and select 'Conventional Commits’. The extension now presents you multiple prompts and builds the commit message from your input:

  1. "select the type of change that you're committing.": The plugin will provide you a list of types, from which you have to pick exactly one. Here is a short guide that will help you to select the correct type:

type

description

type

description

feat

a new feature was implemented

fix

a bug was fixed

refactor

code was refactored

test

tests were implemented/adjusted/fixed

perf

changes were done that improve performance

revert

this commit reverts previous commits

ci

changes to the 'continuuous integration' were made

docs

the documentation was changed

build

changes to the build/dependencies were made

chore

other types of changes, that are not covered by the previous categories

  1. "select the scope of the change.": this should be the name of your branch, e.g.: “PR-123“.

  2. "choose a gitmoji.": Select 'None'.

  3. "write a short, imperative tense description of the change.": as the prompt indicates, you should briefly describe your changes in imperative tense. Assume that you have implemented the feature, that motor-settings are persisted to the database. Your description could in this case be something like “motor-settings are persisted to the database“.

  4. "provide a longer description of the change.": Give a detailed explanation of the modifications you made and their advantages.

  5. "list any breaking changes or issues closed by this change.": Leave this input blank and continue.

The plugin will now have rendered a commit-message from your input and you can now commit your changes.


Push your changes


Push your branch to the forked repository back using following command:

git push origin PR-XXX(your ticket number)

Create a Pull Request


Create a pull request from your branch to the “develop” branch.
Use the given template for the pull request, you will need to modify it so that it matches your ticket.
The title must follow this rule:

<source-branch-name> => <target-branch-name>

Review


Your pull request will be examined by the pib team, who will also recommend any necessary modifications.
We´ll collaborate with you to ensure a seamless integration of your contributions.

After your contribution fullfils our checklist from the Pull Request Template we will approve your pull request. Your contribution will be merged as soon as possible.

We will also test your pull request and tell you if there are any issues.


Code Guidelines📜

  • Testing: 80%+ test coverage required for new features

  • Documentation: Update (both) code comments and (project docs)

  • Formatting: Use Black Python code formatter for the backend

Pull Request Process 🔍

  1. Ensure all CI checks pass

  2. PR must reference an existing issue

  3. One maintainer approvals required before merge

Community🤝

Join us on:

 

Thank you for helping make pib better!