diff --git a/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md b/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md index 5442e29f..1b1668c7 100644 --- a/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md +++ b/cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md @@ -1,235 +1,65 @@ -# Contributing to {{cookiecutter.title}} +# Contributing Guide -## Build +We are very glad that you want to contribute to {{cookiecutter.title}}. Welcome! -You can use `build` to simply build the source and binary distribution: +This guide will help you get started with the project and explain how you can +contribute to it. -```sh -python -m pip install build -python -m build -``` -## Local development -{%- if cookiecutter.type == "api" %} +## Reporting bugs or requesting new features or enhancements -You need to make sure you have the `git submodules` updated: +If you find a bug or want to propose a change or enhancement, please [open an +issue]. -```sh -git submodule update --init -``` +Make sure to include a clear description of the bug and steps to reproduce it. +The most comprehensive and clear the report, the more chances are that we can +act on it. -### Running protolint +## Contributing code -To make sure some common mistakes are avoided and to ensure a consistent style -it is recommended to run `protolint`. After you [installed -`protolint`](https://github.com/yoheimuta/protolint#installation), just run: +If you plan to contribute code, you probably want to check out the [development +guide]. This guide explains how to install dependencies and run tests. -```sh -protolint lint proto -``` +If you want to fix a small bug or contribute some small improvements, you are +very welcome to [submit a pull request](#submitting-a-pull-request) directly. -### Python setup -{%- endif %} +When a contribution is expected to take a non-trivial amount of time, we prefer +if you first [open an issue] (in case of a bug fix or a small improvement), or +[submit an idea] (in case of a big feature or change) to make sure that your +contribution fits the project's goals and that you are not duplicating work. -You can use editable installs to develop the project locally (it will install -all the dependencies too): +This will help avoid wasting time and effort, either because the change doesn't +fit our goals or because it could have been addressed differently, and it also +helps keeping frustration low and motivation high. -```sh -python -m pip install -e . -``` -{%- if cookiecutter.type == "api" %} +After the details on how the issue or enhancement should be addressed, you can +start working on it with the confidence that the results have a high change of +getting accepted and [submit a pull request](#submitting-a-pull-request) with +the results of your work. -This will also generate the Python files from the `proto/` files and leave them -in `py/`, so you can inspect them. -{%- endif %} +### Submitting a pull request -Or you can install all development dependencies (`mypy`, `pylint`, `pytest`, -etc.) in one go too: -```sh -python -m pip install -e .[dev] -``` +If you are not familiar with how, please read [GitHub's guide on how to create +a pull +request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request). -If you don't want to install all the dependencies, you can also use `nox` to -run the tests and other checks creating its own virtual environments: +At a bare minimum you should follow this checklist: -```sh -python -m pip install .[dev-noxfile] -nox -``` +- [x] All tests and checks pass. Please check the [development guide] for more + information on how to run tests and checks. +- [x] Both code comments (*docstrings*, etc.) and user documentation + (`README.md`, `docs/`, etc.) are up-to-date and reflect the changes you + made. +- [x] The generated documentation can be built, and it looks good. Please also + check the [development guide] for more information on this. +- [x] Update the `RELEASE_NOTES.md` file in case there are user-visible + changes. +- [x] Appropriately [link the corresponding + issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue) + if the pull request is addressing one. -You can also use `nox -R` to reuse the current testing environment to speed up -test at the expense of a higher chance to end up with a dirty test environment. -{%- if cookiecutter.type == "api" %} -### Upgrading dependencies - -If you want to update the dependency `frequenz-api-common`, then you need to: - -1. Update the submodule `frequenz-api-common` -2. Update the version of the `frequenz-api-common` package in `pyproject.toml` - -The version of `frequenz-api-common` used in both places mentioned above should -be the same. - -Here is an example of upgrading the `frequenz-api-common` dependency to version -`v0.2.0`: -```sh -ver="0.2.0" -ver_minor=$(echo $ver | cut -d. -f1,2) - -cd submodules/frequenz-api-common -git remote update -git checkout v${ver} -cd - - -sed 's/frequenz-api-common == [0-9]\.[0-9]\.[0-9]/frequenz-api-common == '"${ver}/" -i pyproject.toml -sed 's|https://frequenz-floss.github.io/frequenz-api-common/v[0-9]\.[0-9]/objects.inv|https://frequenz-floss.github.io/frequenz-api-common/v'${ver_minor}'/objects.inv|' -i mkdocs.yml -``` -{%- endif %} - -### Running tests / checks individually - -For a better development test cycle you can install the runtime and test -dependencies and run `pytest` manually. - -```sh -python -m pip install .[dev-pytest] # included in .[dev] too - -# And for example -pytest tests/test_*.py -``` - -Or you can use `nox`: - -```sh -nox -R -s pytest -- test/test_*.py -``` - -The same appliest to `pylint` or `mypy` for example: - -```sh -nox -R -s pylint -- test/test_*.py -nox -R -s mypy -- test/test_*.py -``` - -### Building the documentation - -To build the documentation, first install the dependencies (if you didn't -install all `dev` dependencies): - -```sh -python -m pip install -e .[dev-mkdocs] -``` - -Then you can build the documentation (it will be written in the `site/` -directory): - -```sh -mkdocs build -``` - -Or you can just serve the documentation without building it using: - -```sh -mkdocs serve -``` - -Your site will be updated **live** when you change your files (provided that -you used `pip install -e .`, beware of a common pitfall of using `pip install` -without `-e`, in that case the API reference won't change unless you do a new -`pip install`). - -To build multi-version documentation, we use -[mike](https://github.com/jimporter/mike). If you want to see how the -multi-version sites looks like locally, you can use: - -```sh -mike deploy my-version -mike set-default my-version -mike serve -``` - -`mike` works in mysterious ways. Some basic information: - -* `mike deploy` will do a `mike build` and write the results to your **local** - `gh-pages` branch. `my-version` is an arbitrary name for the local version - you want to preview. -* `mike set-default` is needed so when you serve the documentation, it goes to - your newly produced documentation by default. -* `mike serve` will serve the contents of your **local** `gh-pages` branch. Be - aware that, unlike `mkdocs serve`, changes to the sources won't be shown - live, as the `mike deploy` step is needed to refresh them. - -Be careful not to use `--push` with `mike deploy`, otherwise it will push your -local `gh-pages` branch to the `origin` remote. - -That said, if you want to test the actual website in **your fork**, you can -always use `mike deploy --push --remote your-fork-remote`, and then access the -GitHub pages produced for your fork. - -## Releasing - -These are the steps to create a new release: - -1. Get the latest head you want to create a release from. - -2. Update the `RELEASE_NOTES.md` file if it is not complete, up to date, and - remove template comments (`