Skip to content

Contributing to pacsanini#

The pacsanini project welcomes contributions from all developers and users in the open source community. Contributions can be made in a number of ways. A few examples are:

  • Code patches via pull requests
  • Documentation improvements
  • Bug reports and patch reviews
  • Feature enhancement proposals

Code of Conduct#

Please refer to pacsanini's Code of Conduct to learn about the values we adhere to and promote.

Reporting Issues and Submitting PRs#

We are always happy to receive pull requests. Before opening one, please ensure that you have opened an issue so that the rationale for your changes can be better understood by the community.

Reporting Issues#

When submitting an issue, please be as detailed as possible. We use GitHub issues to track requests and bugs.

If the issue a code bug, please follow the guidelines provided in this excellent blog post.

Submitting PRs#

Before submitting PRs to GitHub, please ensure that:

  • you have read and consent to the Developer Certificate of Origin (DCO) policy (which can be found in the docs).
  • the changes provided by your contributions are tested (see the running tests section).Although test suites are automatically run when you will submit the PR, it is easier for the reviewer to review it when there is less trouble.

Setting Up Your Environment#

To get started with the development of pacsanini, you'll first need to fork and clone the repository.

Once you have a local copy, make sure that you are using a python version greater or equal to 3.7 (preferably within a virtual environment). You should ensure that you have installed poetry in that python environment.

How to install poetry Installing poetry can be done using the following command. For more details, see the official documentation [here](https://python-poetry.org/docs/#installation) 
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -

At that point, you can simply run make setup. This will instruct poetry to install all the dependencies you need and setup your pre-commit hooks. At that point, you'll have the good python environment to start developing!

To simplify the setup process you can run make setup.

Why pre-commit hooks? Pre-commit hooks are in place so that we can focus on what we actually want to do: develop. The pre-commit hooks take care of our coding style (`black` and `isort`) and also ensure that we didn't forget to resolve a merge conflict for example. We find that rather than trying to enforce rules and guidelines as humans, we are much better off letting machines (with whom it's hard to argue with) dictate these things.

To be able to run all tests, you will also need to have docker (see here for and installation guide). This is used to run test suites.

Running tests#

Although tests are automatically run when new pull requests are submitted, you are encouraged to run tests locally. Testing is done with the pytest framework. This is useful for running quick tests.

make test
# or
# pytest -m <name of testing module>
# or
# pytest tests/my/file_test.py

When you are ready to submit your pull request, run the project's tests using tox. This allows testing the project against the multiple supported python versions.

make tox
# or
# tox

Updating Dependencies#

If dependencies need to be updated in the project, you should use poetry. If the dependency you are updating or adding impacts the project's core code, use poetry add <package_name>. If the dependency is for development purposes (eg: testing or linting), use poetry add -D <package_name>.