Skip to content

Commit 9923e60

Browse files
llucaxllucax
committed
Add a new maintainer' guide
This document extract the parts relevant to maintenance of the project from the CONTRIBUTING guide to have a central place where maintainers can learn and document maintenance processes. Signed-off-by: Leandro Lucarella <[email protected]>
1 parent 2d9d466 commit 9923e60

File tree

12 files changed

+580
-0
lines changed

12 files changed

+580
-0
lines changed

‎cookiecutter/{{cookiecutter.github_repo_name}}/MAINTAINERS.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Maintainers' Guide
2+
3+
This document describes the process for maintaining the project.
4+
5+
## Releasing
6+
7+
These are the steps to create a new release:
8+
9+
1. Get the latest head you want to create a release from.
10+
11+
2. Update the `RELEASE_NOTES.md` file if it is not complete, up to date, and
12+
remove template comments (`<!-- ... ->`) and empty sections. Submit a pull
13+
request if an update is needed, wait until it is merged, and update the
14+
latest head you want to create a release from to get the new merged pull
15+
request.
16+
17+
3. Create a new signed tag using the release notes and
18+
a [semver](https://semver.org/) compatible version number with a `v` prefix,
19+
for example:
20+
21+
```sh
22+
git tag -s --cleanup=whitespace -F RELEASE_NOTES.md v0.0.1
23+
```
24+
25+
4. Push the new tag.
26+
27+
5. A GitHub action will test the tag and if all goes well it will create
28+
a [GitHub
29+
Release](https://github.com/{{cookiecutter.github_org}}/{{cookiecutter.github_repo_name}}/releases),
30+
and upload a new package to
31+
[PyPI](https://pypi.org/project/{{cookiecutter.pypi_package_name}}/)
32+
automatically.
33+
34+
6. Once this is done, reset the `RELEASE_NOTES.md` with the template:
35+
36+
```sh
37+
cp .github/RELEASE_NOTES.template.md RELEASE_NOTES.md
38+
```
39+
40+
Commit the new release notes and create a PR (this step should be automated
41+
eventually too).
42+
43+
7. Celebrate!
44+
45+
## Upgrading dependencies
46+
47+
### [repo-config]
48+
49+
Frequenz projects have a common structure, so we use [cookiecutter] templates
50+
to generate them. [repo-config] provides this template, and also many small tools to
51+
ensure consistency across repositories and to glue and fill some gaps when
52+
combining the tools we use.
53+
54+
Some work is needed when upgrading [repo-config] to a new version. Usually
55+
following the release notes and the [upgrade
56+
guide](https://frequenz-floss.github.io/frequenz-repo-config-python/latest/user-guide/update-an-existing-project/)
57+
is enough.
58+
59+
[repo-config]: https://frequenz-floss.github.io/frequenz-repo-config-python/
60+
[cookiecutter]: https://cookiecutter.readthedocs.io/
61+
{%- if cookiecutter.type == "api" %}
62+
63+
### [frequenz-api-common]
64+
65+
If you want to update the dependency `frequenz-api-common`, then you need to:
66+
67+
1. Update the submodule `frequenz-api-common`
68+
2. Update the version of the `frequenz-api-common` package in `pyproject.toml`
69+
70+
The version of `frequenz-api-common` used in both places mentioned above should
71+
be the same.
72+
73+
Here is an example of upgrading the `frequenz-api-common` dependency to version
74+
`v0.2.0`:
75+
```sh
76+
ver="0.2.0"
77+
ver_minor=$(echo $ver | cut -d. -f1,2)
78+
79+
cd submodules/frequenz-api-common
80+
git remote update
81+
git checkout v${ver}
82+
cd -
83+
84+
sed 's/frequenz-api-common == [0-9]\.[0-9]\.[0-9]/frequenz-api-common == '"${ver}/" -i pyproject.toml
85+
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
86+
```
87+
{%- endif %}
88+
89+
## Cross-Arch Testing
90+
91+
This project has built-in support for testing across multiple architectures.
92+
Currently, our CI conducts tests on `arm64` machines using QEMU emulation. We
93+
also have the flexibility to expand this support to include additional
94+
architectures in the future.
95+
96+
This project contains Dockerfiles that can be used in the CI to test the
97+
python package in non-native machine architectures, e.g., `arm64`. The
98+
Dockerfiles exist in the directory `.github/containers/nox-cross-arch`, and
99+
follow a naming scheme so that they can be easily used in build matrices in the
100+
CI, in `nox-cross-arch` job. The naming scheme is:
101+
102+
```
103+
<arch>-<os>-python-<python-version>.Dockerfile
104+
```
105+
106+
E.g.,
107+
108+
```
109+
arm64-ubuntu-20.04-python-3.11.Dockerfile
110+
```
111+
112+
If a Dockerfile for your desired target architecture, OS, and python version
113+
does not exist here, please add one before proceeding to add your options to
114+
the test matrix.

‎cookiecutter/{{cookiecutter.github_repo_name}}/mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,3 +143,4 @@ watch:
143143
- README.md
144144
- CONTRIBUTING.md
145145
- DEVELOPMENT.md
146+
- MAINTAINERS.md

‎tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/MAINTAINERS.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Maintainers' Guide
2+
3+
This document describes the process for maintaining the project.
4+
5+
## Releasing
6+
7+
These are the steps to create a new release:
8+
9+
1. Get the latest head you want to create a release from.
10+
11+
2. Update the `RELEASE_NOTES.md` file if it is not complete, up to date, and
12+
remove template comments (`<!-- ... ->`) and empty sections. Submit a pull
13+
request if an update is needed, wait until it is merged, and update the
14+
latest head you want to create a release from to get the new merged pull
15+
request.
16+
17+
3. Create a new signed tag using the release notes and
18+
a [semver](https://semver.org/) compatible version number with a `v` prefix,
19+
for example:
20+
21+
```sh
22+
git tag -s --cleanup=whitespace -F RELEASE_NOTES.md v0.0.1
23+
```
24+
25+
4. Push the new tag.
26+
27+
5. A GitHub action will test the tag and if all goes well it will create
28+
a [GitHub
29+
Release](https://github.com/frequenz-floss/frequenz-actor-test/releases),
30+
and upload a new package to
31+
[PyPI](https://pypi.org/project/frequenz-actor-test/)
32+
automatically.
33+
34+
6. Once this is done, reset the `RELEASE_NOTES.md` with the template:
35+
36+
```sh
37+
cp .github/RELEASE_NOTES.template.md RELEASE_NOTES.md
38+
```
39+
40+
Commit the new release notes and create a PR (this step should be automated
41+
eventually too).
42+
43+
7. Celebrate!
44+
45+
## Upgrading dependencies
46+
47+
### [repo-config]
48+
49+
Frequenz projects have a common structure, so we use [cookiecutter] templates
50+
to generate them. [repo-config] provides this template, and also many small tools to
51+
ensure consistency across repositories and to glue and fill some gaps when
52+
combining the tools we use.
53+
54+
Some work is needed when upgrading [repo-config] to a new version. Usually
55+
following the release notes and the [upgrade
56+
guide](https://frequenz-floss.github.io/frequenz-repo-config-python/latest/user-guide/update-an-existing-project/)
57+
is enough.
58+
59+
[repo-config]: https://frequenz-floss.github.io/frequenz-repo-config-python/
60+
[cookiecutter]: https://cookiecutter.readthedocs.io/
61+
62+
## Cross-Arch Testing
63+
64+
This project has built-in support for testing across multiple architectures.
65+
Currently, our CI conducts tests on `arm64` machines using QEMU emulation. We
66+
also have the flexibility to expand this support to include additional
67+
architectures in the future.
68+
69+
This project contains Dockerfiles that can be used in the CI to test the
70+
python package in non-native machine architectures, e.g., `arm64`. The
71+
Dockerfiles exist in the directory `.github/containers/nox-cross-arch`, and
72+
follow a naming scheme so that they can be easily used in build matrices in the
73+
CI, in `nox-cross-arch` job. The naming scheme is:
74+
75+
```
76+
<arch>-<os>-python-<python-version>.Dockerfile
77+
```
78+
79+
E.g.,
80+
81+
```
82+
arm64-ubuntu-20.04-python-3.11.Dockerfile
83+
```
84+
85+
If a Dockerfile for your desired target architecture, OS, and python version
86+
does not exist here, please add one before proceeding to add your options to
87+
the test matrix.

‎tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,3 +138,4 @@ watch:
138138
- README.md
139139
- CONTRIBUTING.md
140140
- DEVELOPMENT.md
141+
- MAINTAINERS.md

‎tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/MAINTAINERS.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Maintainers' Guide
2+
3+
This document describes the process for maintaining the project.
4+
5+
## Releasing
6+
7+
These are the steps to create a new release:
8+
9+
1. Get the latest head you want to create a release from.
10+
11+
2. Update the `RELEASE_NOTES.md` file if it is not complete, up to date, and
12+
remove template comments (`<!-- ... ->`) and empty sections. Submit a pull
13+
request if an update is needed, wait until it is merged, and update the
14+
latest head you want to create a release from to get the new merged pull
15+
request.
16+
17+
3. Create a new signed tag using the release notes and
18+
a [semver](https://semver.org/) compatible version number with a `v` prefix,
19+
for example:
20+
21+
```sh
22+
git tag -s --cleanup=whitespace -F RELEASE_NOTES.md v0.0.1
23+
```
24+
25+
4. Push the new tag.
26+
27+
5. A GitHub action will test the tag and if all goes well it will create
28+
a [GitHub
29+
Release](https://github.com/frequenz-floss/frequenz-api-test/releases),
30+
and upload a new package to
31+
[PyPI](https://pypi.org/project/frequenz-api-test/)
32+
automatically.
33+
34+
6. Once this is done, reset the `RELEASE_NOTES.md` with the template:
35+
36+
```sh
37+
cp .github/RELEASE_NOTES.template.md RELEASE_NOTES.md
38+
```
39+
40+
Commit the new release notes and create a PR (this step should be automated
41+
eventually too).
42+
43+
7. Celebrate!
44+
45+
## Upgrading dependencies
46+
47+
### [repo-config]
48+
49+
Frequenz projects have a common structure, so we use [cookiecutter] templates
50+
to generate them. [repo-config] provides this template, and also many small tools to
51+
ensure consistency across repositories and to glue and fill some gaps when
52+
combining the tools we use.
53+
54+
Some work is needed when upgrading [repo-config] to a new version. Usually
55+
following the release notes and the [upgrade
56+
guide](https://frequenz-floss.github.io/frequenz-repo-config-python/latest/user-guide/update-an-existing-project/)
57+
is enough.
58+
59+
[repo-config]: https://frequenz-floss.github.io/frequenz-repo-config-python/
60+
[cookiecutter]: https://cookiecutter.readthedocs.io/
61+
62+
### [frequenz-api-common]
63+
64+
If you want to update the dependency `frequenz-api-common`, then you need to:
65+
66+
1. Update the submodule `frequenz-api-common`
67+
2. Update the version of the `frequenz-api-common` package in `pyproject.toml`
68+
69+
The version of `frequenz-api-common` used in both places mentioned above should
70+
be the same.
71+
72+
Here is an example of upgrading the `frequenz-api-common` dependency to version
73+
`v0.2.0`:
74+
```sh
75+
ver="0.2.0"
76+
ver_minor=$(echo $ver | cut -d. -f1,2)
77+
78+
cd submodules/frequenz-api-common
79+
git remote update
80+
git checkout v${ver}
81+
cd -
82+
83+
sed 's/frequenz-api-common == [0-9]\.[0-9]\.[0-9]/frequenz-api-common == '"${ver}/" -i pyproject.toml
84+
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
85+
```
86+
87+
## Cross-Arch Testing
88+
89+
This project has built-in support for testing across multiple architectures.
90+
Currently, our CI conducts tests on `arm64` machines using QEMU emulation. We
91+
also have the flexibility to expand this support to include additional
92+
architectures in the future.
93+
94+
This project contains Dockerfiles that can be used in the CI to test the
95+
python package in non-native machine architectures, e.g., `arm64`. The
96+
Dockerfiles exist in the directory `.github/containers/nox-cross-arch`, and
97+
follow a naming scheme so that they can be easily used in build matrices in the
98+
CI, in `nox-cross-arch` job. The naming scheme is:
99+
100+
```
101+
<arch>-<os>-python-<python-version>.Dockerfile
102+
```
103+
104+
E.g.,
105+
106+
```
107+
arm64-ubuntu-20.04-python-3.11.Dockerfile
108+
```
109+
110+
If a Dockerfile for your desired target architecture, OS, and python version
111+
does not exist here, please add one before proceeding to add your options to
112+
the test matrix.

‎tests_golden/integration/test_cookiecutter_generation/api/frequenz-api-test/mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,3 +138,4 @@ watch:
138138
- README.md
139139
- CONTRIBUTING.md
140140
- DEVELOPMENT.md
141+
- MAINTAINERS.md

0 commit comments

Comments
 (0)