Contributor’s Guide¶

Welcome to the open source community building this toolkit! We’re thrilled you’re interested in contributing – your ideas and efforts are what make this project thrive.

We encourage you to explore the guide and familiarize yourself with our collaborative development process. If you have any questions or need help getting started, feel free to reach out on our GitHub issue tracker.

Be Courteous¶

In the spirit of collaboration, we emphasize the importance of maintaining a respectful and inclusive environment.

In this project, we uphold a golden rule that applies to all forms of contribution, including bug reports and feature requests: treat everyone involved with respect. We value the diverse perspectives and experiences of our contributors and encourage constructive and courteous interactions.

See the Code of Conduct for details.

Contribution Suitability¶

The final decision regarding the suitability of a contribution for the project rests with the project maintainers. While we carefully consider all contributions, there may be instances where certain contributions are not aligned with the project’s current goals or needs, and as a result, they may be declined.

Need some feedback on whether your idea is suitable for the project? Open a GitHub issue. We’re happy to discuss your ideas and provide feedback!

Code Contributions¶

Steps for Submitting Code¶

Here are a sequence of steps to help with your code contribution:

Fork the project repository on GitHub.
Create a feature branch from the development branch.
Install the package by running poetry install at the command line.
Verify that all tests pass on your system by running poetry run pytest at the command line. In case of failures, conduct a thorough investigation. If you require assistance in diagnosing the issue, follow the guidelines for filing Bug Reports.
Construct test cases that effectively illustrate the bug or feature.
Implement your changes, including any relevant documentation updates following our Documentation Contributions guidelines.
Re-run the complete test suite to ensure the success of all tests.
Format and analyze your code according to our Code Format and Analysis guidelines.
Ensure the docs build following the Documentation Contributions guidelines.
Check that the sdist and wheels build by running poetry build at the command line.
Commit your work following our Commit Messages guidelines.
Submit a GitHub Pull Request to the development branch of the upstream repository.

Code Review¶

Once contributions have undergone a code review process, they will be merged. It is generally recommended to incorporate any feedback received during the code review, unless there are strong objections. If, after submitting your objections, it is determined that the original feedback is still applicable, you will have to either implement the suggested changes or retract your contribution.

Code Format and Analysis¶

Our project uses a couple tools to ensure the code base has a consistent style and format as it grows. We use Black for code formatting and Pylint for static code analysis. Both can be run from the command line:

poetry run black src/ tests/
poetry run pylint src/ tests/

Documentation Contributions¶

We greatly appreciate any efforts to enhance the project documentation! The documentation files reside within the docs/ directory and are written in reStructuredText. We utilize Sphinx to generate a comprehensive suite of documentation. The API documentation is automatically generated by Sphinx from docstrings formatted according to PEP 287.

Build the docs from the command line:

poetry run make --directory=docs clean html

Bug Reports¶

We value your help in improving this project! To avoid duplicate reports, it’s helpful to quickly check the existing GitHub issues to see if the bug has already been reported.

If you are reporting a bug, please use the Bug report issue template. We appreciate it!

Feature Requests¶

Feature requests help this project grow with the user community. If you have an idea for a new feature, we’d love to hear about it! Before submitting a feature request, we kindly request you to check the existing GitHub issues to ensure that the feature hasn’t been requested.

If you are proposing a feature, please use the Feature request issue template. Thanks!

Commit Messages¶

Commit messages are incredibly valuable for understanding the project’s code. When crafting your commit message, please provide context about the changes being made and the reasons behind them.

To ensure readability, we recommend to keep the commit message header under 52 characters and the body within 72 characters.