Update the contributing guide to be focused on contribution

The contributing guide was mainly a development and maintainer' guide,
not really saying much about how to contribute itself.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

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 (`<!-- ... ->`) and empty sections. Submit a pull
-   request if an update is needed, wait until it is merged, and update the
-   latest head you want to create a release from to get the new merged pull
-   request.
-
-3. Create a new signed tag using the release notes and
-   a [semver](https://semver.org/) compatible version number with a `v` prefix,
-   for example:
-
-   ```sh
-   git tag -s --cleanup=whitespace -F RELEASE_NOTES.md v0.0.1
-   ```
-
-4. Push the new tag.
-
-5. A GitHub action will test the tag and if all goes well it will create
-   a [GitHub
-   Release](https://github.com/{{cookiecutter.github_org}}/{{cookiecutter.github_repo_name}}/releases),
-   and upload a new package to
-   [PyPI](https://pypi.org/project/{{cookiecutter.pypi_package_name}}/)
-   automatically.
-
-6. Once this is done, reset the `RELEASE_NOTES.md` with the template:
-
-   ```sh
-   cp .github/RELEASE_NOTES.template.md RELEASE_NOTES.md
-   ```
-
-   Commit the new release notes and create a PR (this step should be automated
-   eventually too).
-
-7. Celebrate!
-
-##  Cross-Arch Testing
-
-This project has built-in support for testing across multiple architectures.
-Currently, our CI conducts tests on `arm64` machines using QEMU emulation. We
-also have the flexibility to expand this support to include additional
-architectures in the future.
-
-This project contains Dockerfiles that can be used in the CI to test the
-python package in non-native machine architectures, e.g., `arm64`. The
-Dockerfiles exist in the directory `.github/containers/nox-cross-arch`, and
-follow a naming scheme so that they can be easily used in build matrices in the
-CI, in `nox-cross-arch` job. The naming scheme is:
-
-```
-<arch>-<os>-python-<python-version>.Dockerfile
-```
-
-E.g.,
-
-```
-arm64-ubuntu-20.04-python-3.11.Dockerfile
-```
-
-If a Dockerfile for your desired target architecture, OS, and python version
-does not exist here, please add one before proceeding to add your options to
-the test matrix.
+[open an issue]: https://github.com/{{cookiecutter.github_org}}/{{cookiecutter.github_repo_name}}/issues/new/choose
+[submit an idea]: https://github.com/{{cookiecutter.github_org}}/{{cookiecutter.github_repo_name}}/discussions/new?category=ideas
+[submit a pull]: https://github.com/{{cookiecutter.github_org}}/{{cookiecutter.github_repo_name}}/compare
+[development guide]: DEVELOPMENT.md