From 16f6a44d312596ab4d8ec499d6a8976985b6c781 Mon Sep 17 00:00:00 2001 From: Martine Lenders Date: Tue, 3 Dec 2024 20:12:03 +0100 Subject: [PATCH 1/5] tools: provide tool to create doxygen maintainer list --- dist/tools/maintainer-list/maintainer-list.py | 166 ++++++++++++++++++ dist/tools/maintainer-list/requirements.txt | 1 + doc/doxygen/.gitignore | 1 + doc/doxygen/Makefile | 12 +- doc/doxygen/riot.doxyfile | 1 + 5 files changed, 177 insertions(+), 4 deletions(-) create mode 100755 dist/tools/maintainer-list/maintainer-list.py create mode 100644 dist/tools/maintainer-list/requirements.txt diff --git a/dist/tools/maintainer-list/maintainer-list.py b/dist/tools/maintainer-list/maintainer-list.py new file mode 100755 index 000000000000..7783f6a633b7 --- /dev/null +++ b/dist/tools/maintainer-list/maintainer-list.py @@ -0,0 +1,166 @@ +#! /usr/bin/env python3 +# +# Copyright (C) 2024 TU Dresden +# +# This file is subject to the terms and conditions of the GNU Lesser +# General Public License v2.1. See the file LICENSE in the top level +# directory for more details. + +__author__ = "Martine S. Lenders " + +import re +import os +import pathlib +import sys +import urllib.parse + +import requests + + +SCRIPT_PATH = pathlib.Path(__file__).resolve().absolute().parent +RIOTBASE = (SCRIPT_PATH / ".." / ".." / "..").resolve() +TOKEN = os.environ.get("GITHUB_TOKEN") + + +NO_AREA_TEXT = "Has no chosen area of expertise." +MAINTAINER_FILE_BOILERPLATE = f"""# Maintainer List {{#maintainer-list}} + +This file contains the current list of maintainers within the RIOT community. +The file is generated by combining the information from the Maintainers, Owners and +Admin teams from the RIOT-OS GitHub organization and the +[CODEOWNERS](https://github.com/RIOT-OS/RIOT/blob/master/CODEOWNERS) file. + +If a maintainer is marked as "{NO_AREA_TEXT}", they did not have added any ownership +within CODEOWNERS. This does not mean that they do not feel responsible for any part of +the code base, they just did not declare it. + +If a list entry only shows a pattern, it did not resolve to a specific Doxygen group +that may be referenced. This may be intentional, since the maintainer may feel +responsible for a large number of modules / groups within files that match that pattern. +If it is not intentional, please add an `@ingroup` command for an existing Doxygen +group to a file that matches the pattern; the corresponding group will then be linked +here. + +If you are a maintainer and want to declare ownership for a part of a code base (and +receive notifications on pull requests against it), please add yourself and the path to +the part of the code base you want to be responsible for to CODEOWNERS. +""" + + +def get_team_members(team): + members = requests.get( + f"https://api.github.com/orgs/RIOT-OS/teams/{team}/members", + headers={ + "Accept": "application/vnd.github+json", + "Authorization": f"Bearer {TOKEN}", + "X-GitHub-Api-Version": "2022-11-28", + }, + ) + try: + return set(m["login"] for m in members.json()) + except Exception as exc: + print(f"Error fetching team {team}: {exc}", file=sys.stderr) + raise + + +def get_github_user(username): + user = requests.get( + f"https://api.github.com/users/{username}", + headers={ + "Accept": "application/vnd.github+json", + "Authorization": f"Bearer {TOKEN}", + "X-GitHub-Api-Version": "2022-11-28", + }, + ) + return user.json() + + +def get_maintainer_codeowner_patterns(maintainers): + maintainer_patterns = {m: [] for m in maintainers} + + with open(RIOTBASE / "CODEOWNERS") as codeowners_file: + for line in codeowners_file: + if re.search(r"^\s*#", line) or re.match(r"^\s*$", line): + # skip comments and empty lines + continue + pattern, *owners = re.split(r"\s+", line.strip()) + for owner in owners: + owner = owner.lstrip("@") + if owner in maintainer_patterns: + maintainer_patterns[owner].append(pattern) + return maintainer_patterns + + +def collect_maintainer_areas(maintainer_codeownership): + maintainer_areas = {m: set() for m in maintainer_codeownership} + for m in maintainer_areas: + if not maintainer_areas[m] and maintainer_codeownership[m]: + for rule in maintainer_codeownership[m]: + maintainer_areas[m].add(rule) + return maintainer_areas + + +def create_maintainer_markdown_file(maintainer_areas, owners, admins): + with open( + RIOTBASE / "doc" / "doxygen" / "src" / "maintainers.md", "w" + ) as maintainers_file: + print(MAINTAINER_FILE_BOILERPLATE, file=maintainers_file) + for maintainer in sorted(maintainer_areas, key=lambda x: x.lower()): + github_profile = get_github_user(maintainer) + + if ( + not github_profile["name"] + or github_profile["name"] == github_profile["login"] + ): + title = f"[@{github_profile['login']}]({github_profile['html_url']})" + else: + title = ( + f"[{github_profile['name']} (@{github_profile['login']})]" + f"({github_profile['html_url']})" + ) + anchor = urllib.parse.quote(github_profile["login"]) + print(f"## {title} {{#{anchor}}}", file=maintainers_file) + + if maintainer in owners: + print( + "- **Is one of the GitHub owners of RIOT.**", file=maintainers_file + ) + + if maintainer in admins: + print( + "- **Is one of the GitHub admins of RIOT.**", file=maintainers_file + ) + + for area in sorted( + maintainer_areas[maintainer], + ): + print( + f"- `{area.lstrip('/')}`", + file=maintainers_file + ) + if not maintainer_areas[maintainer]: + print("", file=maintainers_file) + print(NO_AREA_TEXT, file=maintainers_file) + print("", file=maintainers_file) + + +def main(): + if not TOKEN: + print( + "Please provide a sufficient GitHub token in `GITHUB_TOKEN` " + "environment variable", + file=sys.stderr, + ) + sys.exit(1) + maintainers = get_team_members("maintainers") + admins = get_team_members("admin") + owners = get_team_members("owners") + maintainers = maintainers.union(admins) + maintainers = maintainers.union(owners) + maintainer_codeownership = get_maintainer_codeowner_patterns(maintainers) + maintainer_areas = collect_maintainer_areas(maintainer_codeownership) + create_maintainer_markdown_file(maintainer_areas, owners, admins) + + +if __name__ == "__main__": + main() diff --git a/dist/tools/maintainer-list/requirements.txt b/dist/tools/maintainer-list/requirements.txt new file mode 100644 index 000000000000..d80d9fc2a3a2 --- /dev/null +++ b/dist/tools/maintainer-list/requirements.txt @@ -0,0 +1 @@ +requests==2.32.3 diff --git a/doc/doxygen/.gitignore b/doc/doxygen/.gitignore index 53e838267f92..28c45f3ae4f3 100644 --- a/doc/doxygen/.gitignore +++ b/doc/doxygen/.gitignore @@ -1,2 +1,3 @@ src/css/variables.less src/changelog.md +src/maintainers.md diff --git a/doc/doxygen/Makefile b/doc/doxygen/Makefile index d3a9e4d453cb..e5d47bffc824 100644 --- a/doc/doxygen/Makefile +++ b/doc/doxygen/Makefile @@ -16,17 +16,17 @@ doc: $(DOCUMENTATION_FORMAT) # by marking html as phony we force make to re-run Doxygen even if the directory exists. .PHONY: html -html: src/changelog.md +html: src/changelog.md src/maintainers.md ( cat riot.doxyfile ; echo "GENERATE_HTML = yes" ) | doxygen - @echo "" @echo "RIOT documentation successfully generated at file://$(RIOTBASE)/doc/doxygen/html/index.html" .PHONY: check -check: src/changelog.md +check: src/changelog.md src/maintainers.md ( cat riot.doxyfile) | doxygen - .PHONY: man -man: src/changelog.md +man: src/changelog.md src/maintainers.md ( cat riot.doxyfile ; echo "GENERATE_MAN = yes" ) | doxygen - src/css/riot.css: src/css/riot.less src/css/variables.less @@ -39,8 +39,12 @@ src/css/variables.less: src/config.json src/changelog.md: src/changelog.md.tmp ../../release-notes.txt @./generate-changelog.py $+ $@ +src/maintainers.md: ../../dist/tools/maintainer-list/maintainer-list.py ../../dist/tools/maintainer-list/requirements.txt ../../CODEOWNERS + -@pip install --upgrade -r ../../dist/tools/maintainer-list/requirements.txt + -@../../dist/tools/maintainer-list/maintainer-list.py + .PHONY: -latex: src/changelog.md +latex: src/changelog.md src/maintainers.md ( cat riot.doxyfile ; echo "GENERATE_LATEX= yes" ) | doxygen - clean: diff --git a/doc/doxygen/riot.doxyfile b/doc/doxygen/riot.doxyfile index 652318ef6fed..b85aeb2cd535 100644 --- a/doc/doxygen/riot.doxyfile +++ b/doc/doxygen/riot.doxyfile @@ -888,6 +888,7 @@ INPUT = ../../doc.txt \ src/release-cycle.md \ src/io-mapping-and-shields.md \ src/changelog.md \ + src/maintainers.md \ ../../LOSTANDFOUND.md \ ../../makefiles/pseudomodules.inc.mk \ ../../makefiles/blob.inc.mk \ From 4b31bfdc5db222837d965d3bc3333d4e3f8f8d30 Mon Sep 17 00:00:00 2001 From: Martine Lenders Date: Tue, 3 Dec 2024 20:12:35 +0100 Subject: [PATCH 2/5] MAINTAINING.md: link to generated maintainer list ... rather than outdated wiki page. --- MAINTAINING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MAINTAINING.md b/MAINTAINING.md index 00ee95522241..8acd614de24e 100644 --- a/MAINTAINING.md +++ b/MAINTAINING.md @@ -181,7 +181,7 @@ In case of security relevant backports (both bug fixes and reverts), the announcement can be skipped and the fix merged once at least two ACKs are there. -[list of maintainers]: https://github.com/RIOT-OS/RIOT/wiki/Maintainers +[list of maintainers]: https://doc.riot-os.org/maintainer-list.html [Best Practices]: https://github.com/RIOT-OS/RIOT/wiki/Best-Practice-for-RIOT-Programming [Comparing build sizes]: https://github.com/RIOT-OS/RIOT/wiki/Comparing-build-sizes [Coding Conventions]: CODING_CONVENTIONS.md From 41d241b3c0e6c73e784be8c510b9ace4eb5db859 Mon Sep 17 00:00:00 2001 From: Martine Lenders Date: Tue, 3 Dec 2024 20:46:39 +0100 Subject: [PATCH 3/5] gh-actions/static-test.yml: add GITHUB_TOKEN to environment --- .github/workflows/static-test.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/static-test.yml b/.github/workflows/static-test.yml index 65b4030df053..f8783fbdc9ca 100644 --- a/.github/workflows/static-test.yml +++ b/.github/workflows/static-test.yml @@ -46,6 +46,7 @@ jobs: docker run --rm \ -e CI_BASE_BRANCH \ -e GITHUB_RUN_ID=${GITHUB_RUN_ID} \ + -e GITHUB_TOKEN=${GITHUB_TOKEN} \ -v $(pwd):/data/riotbuild \ riot/static-test-tools:latest \ make static-test From 83b01c85e8eba104f46fecb8189773a8f2613865 Mon Sep 17 00:00:00 2001 From: Martine Lenders Date: Fri, 6 Dec 2024 14:59:21 +0100 Subject: [PATCH 4/5] fixup! tools: provide tool to create doxygen maintainer list --- dist/tools/maintainer-list/maintainer-list.py | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/dist/tools/maintainer-list/maintainer-list.py b/dist/tools/maintainer-list/maintainer-list.py index 7783f6a633b7..004fb143245a 100755 --- a/dist/tools/maintainer-list/maintainer-list.py +++ b/dist/tools/maintainer-list/maintainer-list.py @@ -105,21 +105,24 @@ def create_maintainer_markdown_file(maintainer_areas, owners, admins): RIOTBASE / "doc" / "doxygen" / "src" / "maintainers.md", "w" ) as maintainers_file: print(MAINTAINER_FILE_BOILERPLATE, file=maintainers_file) - for maintainer in sorted(maintainer_areas, key=lambda x: x.lower()): + for i, maintainer in enumerate( + sorted(maintainer_areas, key=lambda x: x.lower()) + ): github_profile = get_github_user(maintainer) if ( not github_profile["name"] or github_profile["name"] == github_profile["login"] ): - title = f"[@{github_profile['login']}]({github_profile['html_url']})" + title = f"\\@{github_profile['login']}" else: - title = ( - f"[{github_profile['name']} (@{github_profile['login']})]" - f"({github_profile['html_url']})" - ) + title = f"{github_profile['name']} (\\@{github_profile['login']})" anchor = urllib.parse.quote(github_profile["login"]) print(f"## {title} {{#{anchor}}}", file=maintainers_file) + print( + f"[GitHub profile]({github_profile['html_url']})", + file=maintainers_file, + ) if maintainer in owners: print( @@ -141,7 +144,8 @@ def create_maintainer_markdown_file(maintainer_areas, owners, admins): if not maintainer_areas[maintainer]: print("", file=maintainers_file) print(NO_AREA_TEXT, file=maintainers_file) - print("", file=maintainers_file) + if (i + 1) < len(maintainer_areas): + print("", file=maintainers_file) def main(): From ba9c13a8da96eb2dc06abca37bf6374ec2a9e012 Mon Sep 17 00:00:00 2001 From: Martine Lenders Date: Fri, 6 Dec 2024 15:14:51 +0100 Subject: [PATCH 5/5] fixup! tools: provide tool to create doxygen maintainer list --- dist/tools/maintainer-list/maintainer-list.py | 7 ------- 1 file changed, 7 deletions(-) diff --git a/dist/tools/maintainer-list/maintainer-list.py b/dist/tools/maintainer-list/maintainer-list.py index 004fb143245a..2e8af47a4186 100755 --- a/dist/tools/maintainer-list/maintainer-list.py +++ b/dist/tools/maintainer-list/maintainer-list.py @@ -34,13 +34,6 @@ within CODEOWNERS. This does not mean that they do not feel responsible for any part of the code base, they just did not declare it. -If a list entry only shows a pattern, it did not resolve to a specific Doxygen group -that may be referenced. This may be intentional, since the maintainer may feel -responsible for a large number of modules / groups within files that match that pattern. -If it is not intentional, please add an `@ingroup` command for an existing Doxygen -group to a file that matches the pattern; the corresponding group will then be linked -here. - If you are a maintainer and want to declare ownership for a part of a code base (and receive notifications on pull requests against it), please add yourself and the path to the part of the code base you want to be responsible for to CODEOWNERS.