Skip to content

Contributing

Thanks for your interest in ThermoPot - we welcome your help in improving and extending this package.

This project follows the all-contributors specification. Contributions of any kind are welcome! A full list of possible contribution types can be found here. You do not need to be an experienced programmer to help improve ThermoPot.

All contributions will be recognised on the README.md. You are encouraged to log your own contribution using the all-contributors bot. The project lead(s) will also maintain this list.

ThermoPot contributors are asked to follow the Contributor Covenant Code of Conduct.

Contributions workflow

Code contributions are primarily managed through Github pull requests. For external contributions we prefer the β€œfork and pull” workflow:

  1. open an Issue to discuss the proposed contribution.
  2. make your own project fork and implement the changes there
  3. open a pull requestion (PR) to merge the changes into the main project. Further discussion might also take place at this stage.

Note: Please, where applicable and possible, write tests and documentation for your proposed code contributions (further details below). Support can be given to those who are writing tests and documentation for the first time 😊

Communication

As a rule of thumb, the more public the information exchange, the better! With this in mind, we encourage you to raise an issue on the ThermoPot repository.

However we also understand that this public way of working is not suitable for everyone. As an alternative, you can get get in contact with the project lead Lucy.

Testing

Github Actions and Pytest is used to automatically test all commits to the main branch of the ThermoPot repository. If possible, please write tests for your code when issuing a Pull Request; ./tests/conftest.py contains pytest fixtures which may be of use. Test files and test data can be found in the tests/ folder.

Documentation

Github Actions is used to automatically build and publish code documentation after each commit to the main branch of the ThermoPot repository. All documentation is written in Markdown using the MkDocs framework and the Material theme. This also includes the automatic generation of API documentation using the mkdocstrings plugin.

If possible, please update the documentation when issuing a Pull Request. This includes both the web pages written in Markdown, and in-code docstrings. The latter are particularly important, and we request that these are written Google-style.

All documentation source can be found in the docs/ folder. MkDocs is configured with the /.mkdocs.yml folder in the project root.

Linting

Github Actions and Black are used to automatically re-format all Python code committed to the repository. The code will be formatted according to the PEP8 specification. As this is an automatic step you do not need lint/format your code to any specification before issuing a PR.

Publishing

Github Actions (surprise, surprise!) is used to automatically build and publish the ThermoPot package after every tagged release. Before tagging the release, we need to remember to update the version number in __init__.py. It's so easy to forget!