Contributing Guidelines

First off, thanks for considering to contribute to this project!

These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Versioning and changelog

This project adheres to Semantic Versioning.
The CHANGELOG format tries to complies with Keep a Changelog but it’s mainly a concatenation of autogenerated release notes by GitHub Release.

Git hooks

We use git hooks through pre-commit to enforce and automatically check some “rules”. Please install it before any commit: pre-commit install.

See the relevant configuration file: .pre-commit-config.yaml.

Code Style

Make sure your code roughly follows PEP-8 and keeps things consistent with the rest of the code:

  • docstrings: sphinx-style is used to write technical documentation.

  • formatting, imports and static analisis: ruff is used to automatically format the code without debate, sort imports and run a bunch of flake8 lint checks

Security

As the aim of this project is to be carried out on large-scale IT infrastructures, security is one of the development challenges. It’s enforced through automated checks, which are mainly executed in CI. But there are a few best practices to bear in mind:

  • give preference to the standard Python library, even it’s longer to develop

  • or consider adding an additional third-party dependency (interest, consequences, linked dependencies, etc.)

  • take security alerts into account

Read the security section in documentation.

IDE

Feel free to use the IDE you love. Here come configurations for some popular IDEs to fit those guidelines.

Visual Studio Code

It’s the IDE used by the main developer, so the configuration is tracked on this repository until new contributors with other IDEs are joining the project.

Configuration is under: .vscode/settings.json

AI Policy

Contributors can use whatever tools they would like to craft their contributions, but there must be a human in the loop.

Contributors must read and review all LLM-generated code before marking a pull request as ready for review. The contributor is always the author and is fully accountable for their contributions, which includes ensuring their contributions are aligned with guidelines.

Contributors should be sufficiently confident that their contribution is high enough quality that asking for a review is a good use of scarce maintainer time, and they should be able to answer questions about their work during review.

Disclosure

Community members are expected to be transparent and disclose AI usage in contributions submitted for review that contain substantial amounts of LLM-generated content.

“Substantial” means different things depending on the type of contribution:

  • Code: any generation beyond single-line autocomplete, such as whole functions, tests, or algorithms.

  • Documentation: anything more than a few words.

Disclosure is not penalized during PR review.

Contributors should note details on tool usage (such as models and prompts used) in PR descriptions.