Skip to content

Improve and split the contributors' guide #361

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 6 commits into
base: v0.x.x
Choose a base branch
from
Draft

Improve and split the contributors' guide #361

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
cc37d5c
Add callouts markdown extension
llucax Feb 25, 2025
8c59c41
Add a new introduction to developing the project
llucax Feb 25, 2025
4be0887
Add a new maintainer' guide
llucax Feb 25, 2025
0f51f2d
Update the contributing guide to be focused on contribution
llucax Feb 25, 2025
b140461
Add a new Community documentation section
llucax Feb 25, 2025
ef91f18
Remove the old CONTRIBUTING section
llucax Feb 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
264 changes: 47 additions & 217 deletions cookiecutter/{{cookiecutter.github_repo_name}}/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Loading
Loading