diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..422738fd --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,19 @@ +# Contributing guidelines + +:tada: **First off, thank you for considering contributing to our project!** :tada: + +This is a community-driven project, so it's people like you that make it useful and +successful. +These are some of the ways to contribute: + +* Submitting bug reports and feature requests +* Fixing typos and improving the documentation +* Writing code for everyone to use + +## Ground rules + +The goal is to maintain a diverse community that's pleasant for everyone. **Please be considerate and respectful of others.** + +## Quick links + +* [Contributors Guide](https://benchcab.readthedocs.io/en/latest/dev_guide/contributing/) \ No newline at end of file diff --git a/docs/dev_guide/contributing.md b/docs/dev_guide/contributing.md new file mode 100644 index 00000000..49978e87 --- /dev/null +++ b/docs/dev_guide/contributing.md @@ -0,0 +1,34 @@ +# Contributors Guide + +## Ways to contribute + +We welcome a range of contributions to this open-source software: + +- open a GitHub issue to convey a problem or send a bug report or propose an enhancement +- update the documentation to fix a typo, improve the clarity or the readability, add missing sections, etc. +- contribute to the code to fix an open issue. + +Before contributing to the documentation or the code-base, consider becoming a member of the CABLE-LSM GitHub organisation. Doing so allows you to create a branch within the `benchcab` repository instead of working from a fork which simplifies the contribution process. To request an invitation to the organisation please [open an issue][new_issue] on the `benchcab` repository. + +## Contributing documentation + +The documentation is written in Markdown using [Material for Mkdocs][Material] and distributed through [ReadTheDocs][ReadTheDocs]. +The `benchcab` repository has continuous integration set up to build a preview of the documentation for all pull requests which means you are not required to build the documentation locally. + +If you would like to build the documentation locally, you can use the [`pip` requirements file][mkdocs-requirements] to install all the required packages. Once the packages are installed, you can use `mkdocs serve` from the top level of the `benchcab` repository to build a local version. + +## Contributing code + +`benchcab` is written in python 3. It is using the following packages and standards for formatting: + +- [flake8][flake8] for linting +- [black][black] for code formatting + +### Testing +You can use this [conda environment file][benchcab-dev] to install a development environment to test your changes locally. + +[Material]: https://squidfunk.github.io/mkdocs-material/ +[ReadTheDocs]: https://about.readthedocs.com/ +[mkdocs-requirements]: https://github.com/CABLE-LSM/benchcab/blob/master/mkdocs-requirements.txt +[new_issue]: https://github.com/CABLE-LSM/benchcab/issues/new +[benchcab-dev]: https://github.com/CABLE-LSM/benchcab/blob/master/.conda/benchcab-dev.yaml diff --git a/mkdocs.yml b/mkdocs.yml index 2cb5b05a..62854387 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -79,3 +79,5 @@ nav: - user_guide/default_science_configurations.md - user_guide/running_CABLE_v2.md - user_guide/expected_output.md + - Development Guide: + - dev_guide/contributing.md