We're really glad you're reading this, because we need volunteer developers to help this project come to fruition.
Some of the resources to look at if you're interested in contributing:
- Join us on Gitter to chat!
- Look at our milestones and projects on GitHub for an idea on where development is headed
- Look at open issues tagged with "help wanted" and "good first issue"
- Look at the development guide in our documentation
By contributing to Calliope, e.g. through opening a pull request or submitting a patch, you represent that your contributions are your own original work and that you have the right to license them, and you agree that your contributions are licensed under the Apache 2.0 license.
Open an issue on GitHub to report bugs or other problems.
If reporting an error when running Calliope on the command line, please re-run your command with the --debug option, e.g.:
calliope run my_model.yaml --debug
Then post the full output from the debug run as part of your GitHub issues.
If reporting an error when running Calliope interactively in a Python session, please include a full traceback in your issue.
Look at the development guide in our documentation for information on how to get set up for development.
To contribute changes:
- Fork the project on GitHub
- Create a feature branch to work on in your fork (
git checkout -b new-fix-or-feature) - Add your name to the
AUTHORSfile - Commit your changes to the feature branch after running black to format your code (formatting is automatic if the
pre-commithooks have been installed; see below for more info) - Push the branch to GitHub (
git push origin new-fix-or-feature) - On GitHub, create a new pull request from the feature branch
Our development guide gives a more detailed description of each step, if you're new to working with GitHub.
Before submitting a pull request, check whether you have:
- Added your changes to
changelog.rst - Added or updated documentation for your changes
- Added tests if you implemented new functionality
When opening a pull request, please provide a clear summary of your changes!
Please try to write clear commit messages. One-line messages are fine for small changes, but bigger changes should look like this:
A brief summary of the commit
A paragraph or bullet-point list describing what changed and its impact,
covering as many lines as needed.
We have existing test coverage for the key functionality of Calliope.
All tests are in the calliope/test directory and use pytest.
Our test coverage is not perfect and an easy way to contribute code is to work on better tests.
Start reading our code and you'll get the hang of it.
We mostly follow the official Style Guide for Python Code (PEP8).
We have chosen to use the uncompromising code formatter, black. If run from the root directory of this repo, pyproject.toml should ensure the line lengths are restricted to 88. The philosophy behind using black is to have uniform style throughout the project dictated by code. Since black is designed to minimise diffs, and make patches more human readable, this also makes code reviews more efficient. To make this a smooth experience, you should add a black formatting script to your git pre-commit hooks before creating a PR. We provide a quick and easy way to set this up as part of the development guide in our documentation.
The layout and content of this document is partially based on the OpenGovernment project's contribution guidelines.