From 52eeddd92b61b87040f3969245df53b96d8a7a1b Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Thu, 28 Mar 2024 04:57:33 +0100 Subject: [PATCH] Set up regular automated code owner reviews --- .github/CODEOWNERS | 6 +++++- .github/workflows/review.yml | 24 ++++++++++++++++++++++++ README.md | 13 +++++++++---- org-repo.md | 14 +++++++------- review-body.sh | 33 +++++++++++++++++++++++++++++++++ 5 files changed, 78 insertions(+), 12 deletions(-) create mode 100644 .github/workflows/review.yml create mode 100755 review-body.sh diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 5740900..095c559 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1 +1,5 @@ -/org-repo.md @infinisil @zimbatm +# See ./org-repo.md + +/.github/CODEOWNERS @infinisil + +/org-repo.md @infinisil diff --git a/.github/workflows/review.yml b/.github/workflows/review.yml new file mode 100644 index 0000000..b63c140 --- /dev/null +++ b/.github/workflows/review.yml @@ -0,0 +1,24 @@ +name: Regular review +on: + workflow_dispatch: # Allows triggering manually + schedule: + - cron: '54 12 1 * *' # runs every first of the month at 17:10 UTC (chosen somewhat randomly) + +permissions: + issues: write + +jobs: + update: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - run: | + gh api \ + --method POST \ + -H "Accept: application/vnd.github+json" \ + -H "X-GitHub-Api-Version: 2022-11-28" \ + /repos/"$GITHUB_REPOSITORY"/issues \ + -f title="[$(date +'%Y %B')] Regular manual review " \ + -f body="$(./review-body.sh)" + env: + GH_TOKEN: ${{ github.token }} diff --git a/README.md b/README.md index f702ba9..08a451f 100644 --- a/README.md +++ b/README.md @@ -16,12 +16,17 @@ Anybody is welcome to open issues/PRs to add/update documentation or propose org This repository generally doesn't need to follow any specific structure. Organic evolution of the structure is encouraged. -The information in this repository should be kept up-to-date with the state of reality. +Most importantly, the information in this repository should be kept up-to-date with the state of reality. Thus, all organisational changes tracked in this repository should be proposed with a PR, and the changes should only to be implemented when the PR is merged. This may be done manually (e.g. by the person merging the PR) or automatically (e.g. using CD). +All files should have at least somebody in charge of keeping it up-to-date, which should be described with an entry in [CODEOWNERS](./github/CODEOWNERS). Those people will be requested for a review and be given write access to the repository, see also [permissions of this repository](./org-repo.md). + +## Regular manual reviews + Unavoidibly it can also happen for reality to deviate from the documentation without a PR. -Thus, all organisational documentation must also have a process for how such deviations can eventually be mitigated. -This may be done manually (e.g. by having a person regularly check the state) -or automatically (e.g. by regularly scraping and comparing the state). +To mitigate this, all people with [code owner entries](./.github/CODEOWNERS) must regularly review their files. +This is done by [automatically opening an issue every month](./.github/workflows/review.yml) to ping all code owners. + +This serves as an initial fallback, but more automatic approaches could be implemented in the future, e.g. by scraping and comparing the state. diff --git a/org-repo.md b/org-repo.md index 7d60592..dd0ddc6 100644 --- a/org-repo.md +++ b/org-repo.md @@ -2,13 +2,13 @@ This document describes the permissions of this repository. -These GitHub users have explicit write permission and can therefore merge PRs: -- [@infinisil](https://github.com/infinisil) -- [@zimbatm](https://github.com/zimbatm) +Everybody in the [CODEOWNERS](./.github/CODEOWNERS) file should have write permission to the repository. +This allows people to get automatic review requests and merge PRs for the files that concern them. -Furthermore, the GitHub organisation owners unavoidable have owner permission over this repository. +TODO: Enable branch protection to require reviews by code owners. +TODO: Ensure that all files have a code owner -## How updates are implemented +Furthermore, the code owners for the CODEOWNERS file should have permission to give more people write access to this repository. +These people get requested for reviews when new people add themselves to CODEOWNERS, allowing them to give write access when merged. -@infinisil and @zimbatm are responsible for manually implementing any merged PRs that change to this document. -They will get pinged for all PRs touching this file via [CODEOWNERS](../.github/CODEOWNERS). +Furthermore, the GitHub organisation owners unavoidable have owner permission over this repository. diff --git a/review-body.sh b/review-body.sh new file mode 100755 index 0000000..c9e8758 --- /dev/null +++ b/review-body.sh @@ -0,0 +1,33 @@ +#!/usr/bin/env bash +set -euo pipefail + +# This script outputs the contents of the regular review issue, see ./github/workflows/review.yml + +rev=$(git rev-parse HEAD) + +echo "Because the documentation in this repository may slowly deviate from reality, this monthly issue is created to regularly review the files. + +If you're pinged, please ensure that the relevant documentation matches reality. + +- If that's not the case, please investigate how this happened and address this so it doesn't happen again. + + To mitigate the current inconsistency: + - If a PR was merged without updating reality, update reality to match the new documentation, then post a comment in this issue with what was done. + - If reality was updated without a PR, open a PR to update the documentation, then post a comment in this issue with a link to the PR. + +- Once the documentation matches reality, tick the checkmark. + +If all checkmarks are ticked, the issue can be closed. + +## Code owners + +These are all [current code owner entries](../tree/$rev/.github/CODEOWNERS): +" + +# TODO: List all files in the repo, link to them directly and look up codeowners using some glob matching/codeowners library/CLI, warn for files without code owner +while read -r file users; do + if [[ "$file" == "#" || "$file" == "" ]]; then + continue + fi + echo "- [ ] \`$file\`: $users" +done < .github/CODEOWNERS