Document maintainers repo permissions

building/config.json

@@ -67,6 +67,12 @@
     "path": "building/github/maintainers-pull-request-guide.md",
     "title": "Maintainers Pull Request Guide"
   },
+  {
+    "uuid": "3598be40-752a-4223-8828-c08dc3320a20",
+    "slug": "github/maintainers-repo-permissions",
+    "path": "building/github/maintainers-repo-permissions.md",
+    "title": "Maintainers Repo Permissions"
+  },
   {
     "uuid": "7cc6cb11-2502-49ea-b7c1-6e501720c9ae",
     "slug": "github/gha-best-practices",

building/github/README.md

@@ -20,6 +20,7 @@ We also have several Exercism-specific Pull Request guides:
 - [How to make a great Pull Request][how-to-make-a-great-pr]
 - [The Contributors' Guide to Pull Requests][contributors-pr-guide]
 - [The Maintainers' Guide to Pull Requests][maintainers-pr-guide]
+- [Maintainers Repo Permissions][maintainers-repo-permissions]
 
 ## Tooling
 
@@ -40,6 +41,7 @@ There is also GitHub-specific tooling you can use:
 [great-pr]: https://exercism.org/docs/community/being-a-good-community-member/pull-requests
 [contributors-pr-guide]: /docs/building/github/contributors-pull-request-guide
 [maintainers-pr-guide]: /docs/building/github/maintainers-pull-request-guide
+[maintainers-repo-permissions]: /docs/building/github/maintainers-repo-permissions
 [how-to-make-a-great-pr]: /docs/community/being-a-good-community-member/pull-requests
 [pro-git]: https://git-scm.com/book/en/v2
 [git]: https://git-scm.com/

building/github/maintainers-repo-permissions.md

@@ -0,0 +1,54 @@
+# Maintainers Repo Permissions
+
+A track maintainer is someone who is a member of the track's GitHub team.
+Becoming a member of a track team is _invitation only_.
+
+```exercism/note
+If you'd like to become a track mainainer, please open a topic on the [forum](https://forum.exercism.org/c/exercism/building-exercism/125).
+```
+
+## Maintenance category
+
+The are five maintenance categories:
+
+1. `wip-track`
+2. `unmaintained`
+3. `maintained-solitary`
+4. `maintained-autonomous`
+5. `maintained`
+
+A tracks' maintenance category is determined by three variables:
+
+1. Whether the track is active (i.e. students can join the track on the website)
+2. The number of track maintainers
+3. The number of track maintainers who are also in the `guardians` GitHub team
+
+To determine the maintenance category, find the first category that matches the track from this table:
+
+| Category                | Active? | Number of maintainers | Number of guardian maintainers |
+| ----------------------- | ------- | --------------------- | ------------------------------ |
+| `wip-track`             | No      | Any                   | Any                            |
+| `unmaintained`          | Yes     | 0                     | 0                              |
+| `maintained-solitary`   | Yes     | 1                     | 0                              |
+| `maintained-autonomous` | Yes     | > 0                   | = Number of maintainers        |
+| `maintained`            | Yes     | > 0                   | < Number of maintainers        |
+
+## Repo permissions
+
+The maintenance category is used to set the track's GitHub repo(s) permission(s).
+
+| Category                | Requires PR | Requires PR approval | Cross-track team reviews |
+| ----------------------- | ----------- | -------------------- | ------------------------ |
+| `wip-track`             | No          | No                   | No                       |
+| `unmaintained`          | Yes         | Yes                  | Yes                      |
+| `maintained-solitary`   | Yes         | Yes                  | Yes                      |
+| `maintained-autonomous` | Yes         | No                   | No                       |
+| `maintained`            | Yes         | No                   | No                       |
+
+```exercism/caution
+The `wip-track` category is the only category that allows maintainers to push to `main`.
+```
+
+```exercism/caution
+Tooling repos will _always_ require PR approval, as their contents are protected via a [CODEOWNERS file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners).
+```

building/tracks/README.md

@@ -100,6 +100,10 @@ csharp
 
 ## Maintenance
 
+### Repo permissions
+
+Each track is (automatically) assigned a [maintenance category](/docs/building/github/maintainers-repo-permissions#maintenance-category), which determines the [track maintainer's GitHub repo permissions](/docs/building/github/maintainers-repo-permissions#repo-permissions).
+
 ### Avoiding triggering unnecessary test runs
 
 When you merge a track PR that touches an exercise, it triggers _all_ the latest published iteration of students' solutions to be re-tested.