Skip to content

Add CODEOWNERS and update maintainer guidelines #16690

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

Merged
srittau merged 1 commit into from
Nov 4, 2026
Merged

Add CODEOWNERS and update maintainer guidelines #16690

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
11 changes: 11 additions & 0 deletions .github/CODEOWNERS
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# See docs/maintainer-guide.md#subscribing-to-changes-with-codeowners
# Last matching pattern wins: list all subscribers to a path on one line.

@Avasam Avasam Nov 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#16663 (comment)

I also just realize, maintainers could subscribe to changes to the contribution or maintainers guide with this.
I'm sure I've missed some updates in the past, and typeshed's best practices is constantly evolving.

For instance, we could do the following for every name found in this file:

docs/maintainer-guide.md @X @Y @Z
CONTRIBUTING.md @X @Y @Z


/stdlib/distutils/ @Avasam

/stubs/keyboard/ @Avasam
/stubs/PyAutoGUI/ @Avasam
/stubs/pyinstaller/ @Avasam
/stubs/python-xlib/ @Avasam
/stubs/pywin32/ @Avasam
/stubs/setuptools/ @Avasam
1 change: 1 addition & 0 deletions .vscode/extensions.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
"bierner.github-markdown-preview",
"charliermarsh.ruff",
"editorconfig.editorconfig",
"jasonnutter.vscode-codeowners",
"ms-python.black-formatter",
"ms-python.flake8",
"ms-python.mypy-type-checker",
Expand Down
14 changes: 14 additions & 0 deletions docs/maintainer-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,20 @@ When merging pull requests, follow these guidelines:
and assume that the reader has no access to the diff.
* Delete branches for merged PRs (by maintainers pushing to the main repo).

## Subscribing to Changes with CODEOWNERS

@Avasam Avasam Nov 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Style wise: There's already a mix of manual wrapping and no manual wrapping for this MD file.

Personally I prefer to never manually wrap. Most IDEs can easily be configured to auto-wrap only in MD files. GitHub also auto-wraps. Let readers use their full available screen width for text.

But CONTRIBUTING.md also mostly has manual wrapping around 80-90 chars width.

@srittau srittau Nov 3, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably at least run an auto formatter (e.g. prettier) over all our Markdown files. I'm not sure it's worth to add one to pre-commit.

@Avasam Avasam Nov 3, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you add one, may as well.

I'm a big fan of dprint. But maybe something else would better fit this project (especially given pre-commit isolation issues)


@Avasam Avasam Nov 3, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section could go in CONTRIBUTING.md considering it can affect contributors. But I think it's more maintainer facing to know about the what/where/who/how of CODEOWNERS.

The part about "trusted contributors" could move or be duplicated. But I wanted to keep everything in one place.

The [`.github/CODEOWNERS`](../.github/CODEOWNERS) file lets Contributors and Maintainers subscribe to changes to specific stubs. GitHub automatically requests a review from everyone listed for the paths a pull request touches.

Despite its name, this file is not about who "owns" the code. Being listed is only a way to get notified. It grants no extra permissions, and a review from a listed person is not required to merge a PR.

Maintainers can freely add and remove themselves.

Trusted contributors who are actively involved with specific stubs (for example, the original author of those stubs) may request to be added by opening a PR that edits the file. This is limited to trusted and involved contributors, so that maintainers don't have to constantly edit the file. By requesting to be added, a contributor acknowledges that:

* They will be requested as a reviewer on every PR touching those stubs.
* Maintainers will not necessarily wait for their review before merging.
* Requests to be removed from the file also go through a PR, and may take some time to be merged.
Comment on lines +51 to +55

@AlexWaygood AlexWaygood Nov 4, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

per https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners

Users and teams must have explicit write access to the repository

So I don't think this is going to work for trusted contributors unless we give them write access -- and I don't know why we'd do that without granting them the maintainer role

@Avasam Avasam Nov 4, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh. If that's the case let's remove that part, yeah. Still a useful tools for maintainers who'd want specific updates.

@Avasam Avasam Nov 4, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose to reach the same effect for contributors, a GitHub action to automatically request reviews may be required.

@AlexWaygood AlexWaygood Nov 4, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah, definitely not opposing the addition of the file for maintainers! Just think we should get rid of the guidance for third-party contributors, since it won't work unfortunately

@Avasam Avasam Nov 4, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I'm currently remote, on my phone. If you wanna do it I can immediatly approve.

I don't think anyone will oppose removing a faulty text that just got added.

Can add it back if we go the actions route. (Which is a bit more involved)

@AlexWaygood AlexWaygood Nov 4, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#16700

@JelleZijlstra JelleZijlstra Nov 4, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What we did on CPython was to give triagers "write" access but use branch protection rules so they can't actually merge or create branches. That's also a bit confusing though so I'm not sure it's worth it.

@AlexWaygood AlexWaygood Nov 4, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that made sense in CPython, where it's a much bigger project with many more maintainers and a dedicated "triagers" team that sits between the core devs and random OSS contributors in terms of trust level. I'm not sure it makes so much sense to add a dedicated "triagers" team over here


## Marking PRs as "deferred"

*See also the [guidelines in the CONTRIBUTING file](../CONTRIBUTING.md#marking-prs-as-deferred).*
Expand Down
Loading