How to contribute
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.
Submitting bug reports
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
- Commit your changes to the feature branch
- 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
- 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 prefer line lengths below 80 characters, but do not enforce this militantly. Readability of code is more important than strict adherence to this line length.
This is open source software. Consider the people who will read your code, and make it look nice for them. It's sort of like driving a car: Perhaps you love doing donuts when you're alone, but with passengers the goal is to make the ride as smooth as possible.
The layout and content of this document is partially based on the OpenGovernment project's contribution guidelines.