Contributing
We would love for you to contribute and improve the explabox
!
If you are unable to contribute yourself, feel free to post a feature request or bug report for the developers and maintainers at the Netherlands National Police Lab AI (NPAI).
1. Getting started
Make sure you have a GitHub account
Submit a ticket for your issue, assuming one does not already exist
Fork the repository on GitHub
2. Setting up your environment
To ensure you are able to interactively edit and test your code, when contributing we recommend you install your forked version of the explabox
with the -e
(editable; i.e. pip3 install -e .
) flag. Depending on where you want to contribute to, we have also provided you with the necessary optional packages required for quality checks and/or package building. These are:
General development:
pip3 install -e ".[dev]"
Only working on documentation:
pip3 install -e ".[docs]"
3. How to contribute
Choose a topic branch (typically
master
) to start your contribution fromMake commits of logical units
Ensure that if you contributed code you also include accompanying tests in the
explabox/test
folderPerform all quality checks when you are finished
Update the changelog to state which contributions you made
Push your changes to a topic branch and create a merge request, describing your contribution
Actively watch if your contribution requires any further changes
3.1 Quality checks
When contributing to the explabox
, you are required to adhere to several quality criteria, as described in the table below.
These are checked automatically when making a commit to the main
branch (using pre-commit
), and are included in the
Makefile
(run make quality
and make coverage
in your terminal, or run make.bat
if on Windows). In addition, they can be run manually with the command provided in the Manual check column below.
Quality |
Tool |
Description |
Manual check |
---|---|---|---|
Import order |
Imports in |
|
|
Linter |
Automatic formatting of your |
|
|
Linter |
Minimal code style quality check, also weakened to a line length of 120. |
|
|
Security |
Software is checked for known security vulnerabilities. |
|
|
Unit and integration testing |
Software should be tested in seperate units and in combined pipelines. |
|
|
|
Check if all required files are also shipped with the Python package. |
|
|
Documentation linter |
Style checks for the documentation files that are used to generate explabox.rtfd.io |
|
These tools are automatically included when installing the explabox
with the [dev]
and [all]
options. The documentation linter is installed with the [doc]
, [dev]
and [all]
options.
If you are contributing to the documentation (i.e. editing any .md
or .rst
file), ensure you run make docs
(or make.bat
for Windows) when you are finished to ensure the updated files are copied to the /docs
folder.
3.2 Updating CHANGELOG.md
Update the changelog using the Keep a Changelog standard, under the [Unreleased]
section of CHANGELOG.md
. Contributions should be grouped under ### Added
, ### Changed
, ### Fixed
or ### Removed
. Note that you should not repeat the verb (e.g. added) of the group in a bullet point.
3.3 Merge request
Clearly state your contributions when making a merge request. Reference any prior issues you are aiming to solve. If you require new dependencies or new versions thereof, also explicitly state why these are required.
Your contribution will be reviewed, potentially requiring changes to the code/documentation you have contributed. When passing all quality checks and the code review, your contribution will become part of the next version of the explabox
.
3.4 New version release
After a succesful merge request, the developers/maintainers of the explabox
will ensure your contribution is pushed with the next version of the explabox
.