Contributor's Guide
First of all, thank you for contributing to Cachalot!
This document provides guidelines for contributing to the project. They are written to ensure its consistency and maintainability. All contributions are welcome, as long as you follow these guidelines. If you have any questions, please contact me.
There are many ways to contribute to the project, including, but not limited to, submitting bug reports and feature requests, improving documentation or writing code.
How to Report Bugs
Bug reports are hugely important, but please make sure to avoid duplicate reports. Before you submit one, please check Cachalot issues, both open and closed, and make sure, that the bug has not been reported before.
When filing an issue, include answers to the following five questions: 1. What version of Cachalot are you using? 2. What operating system and Python version are you using? 3. What did you do? 4. What was the expected result? 5. What was the actual result?
How to Suggest a Feature
If you have a suggestion for a feature or an enhancement, please feel free to open an issue. In your feature request, include the following: 1. What should the feature do? 2. Why do you need it? 3. How should it work?
Note that I reserve a right to reject a feature request, if I feel it does not align with the project's goals.
Contributing Code
If this is your first time contributing code on Gitlab, take a look at Gitlab's How to create a merge request. After you read it, you follow this checklist to make a merge request:
1. Fork the repository.
2. Setup development environment using poetry install --dev
3. Run the tests using pytest tests
to make sure they pass on your system.
4. Write tests for the feature you are adding. They should fail.
5. Add your feature.
6. Run the test suite again, ensuring all tests, including the ones you have written, pass.
7. Make a merge request on Gitlab.
Code Style
- Cachalot adheres to Pep 8 and Pep 257 coding conventions.
- It also takes advantage of type hints. For an explanation of how they work, read Pep 483
- Use Google style docstrings.
- Use imports for packages and modules only.
- Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert.
Updating Documentation
If you have found any mistakes, want to add examples, or just improve the documentation in general, you are more than welcome! Just make your change and send a merge request.
Closing Words
Thank you for taking the time to read the Contributor's Guide!
Radek Sprta
Maintainer