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.gitCreate 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:
"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 |
|---|---|
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 |
"select the scope of the change.": this should be the name of your branch, e.g.: “PR-123“.
"choose a gitmoji.": Select 'None'.
"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“.
"provide a longer description of the change.": Give a detailed explanation of the modifications you made and their advantages.
"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 🔍
Ensure all CI checks pass
PR must reference an existing issue
One maintainer approvals required before merge
Community🤝
Join us on:
✨ Thank you for helping make pib better!