Add the 'docs-approved' label

[AA-Turner]

In a couple of recent documentation meetings¹, we've discussed workflow changes to fast-track documentation contributions. One of those ideas was to have a 'docs-approved' ² label that a group of trusted reviewers can attach to a PR, so interested core developers are able to filter on that label for merging PRs (this could also be something the developer-in-residence periodically looks at).

A

Footnotes

1. https://docs-community.readthedocs.io/en/latest/monthly-meeting/2022-05.html#improving-documentation-pr-review ↩

2. Other ideas: 'docs-reviewed', 'docs-fast-track', etc. ↩

[AlexWaygood]

What's the proposed process by which people would get added to the group of trusted reviewers? Is the proposal that this group would be a superset of the current group of triagers, or a subset?

[ezio-melotti]

If we create a GitHub team of docs reviewers, it could be requested as reviewer for docs PR (either manually, or automatically through the CODEOWNERS file or bedevere) and then members of the team can review the PR on behalf of the team.

This should make the workflow easier since they can just submit a review instead of (or in addition to) remembering to go back to the PR page to add a label. It will also make the review more authoritative, since only the team members can review on behalf of the team (whereas any triager can add a label).

Core devs can then filter these PRs using reviewed-by:python/docs-team (or whatever name we settle on, and possibly in combination with review:approved), to find these PRs.

[AlexWaygood]

If we create a GitHub team of docs reviewers, it could be requested as reviewer for docs PR (either manually, or automatically through the CODEOWNERS file or bedevere) and then members of the team can review the PR on behalf of the team.

I like this idea more. I still don't feel clear on who would be in this team, though. Would any triager who wanted to join be allowed to join the team? Only those who've had a certain number of docs PRs accepted? Only those involved with the docs-community? Would non-triagers be allowed to join the team?

[AA-Turner]

This wasn't a fully developed idea! I also like the team approach more.

I still don't feel clear on who would be in this team, though. Would any triager who wanted to join be allowed to join the team? Only those who've had a certain number of docs PRs accepted? Only those involved with the docs-community? Would non-triagers be allowed to join the team?

For triagers, I think the trust level is enough to allow self-nomination if you feel confident reviewing documentation PRs. I would say we should let non-triagers join the team, as it is somewhat orthogonal to the core triage role (copyediting and technical/formal writing etc). On how that happens, I expect the process would be somewhat similar to triage team requests at the moment -- you would need a sponsor, but it wouldn't be too onerous.

If we go down the team route, we should add a quick link to the search terms @ezio-melotti mentioned, as they're not the easiest to remember / combine correctly!

A

[AlexWaygood]

This wasn't a fully developed idea!

Heh, sorry for the barrage of questions ;) thank you for starting this discussion!

For triagers, I think the trust level is enough to allow self-nomination if you feel confident reviewing documentation PRs. I would say we should let non-triagers join the team, as it is somewhat orthogonal to the core triage role (copyediting and technical/formal writing etc). On how that happens, I expect the process would be somewhat similar to triage team requests at the moment -- you would need a sponsor, but it wouldn't be too onerous.

All sounds good to me :)

[ezio-melotti]

If we go down the team route, we should add a quick link to the search terms @ezio-melotti mentioned, as they're not the easiest to remember / combine correctly!

Ideally we should document both the team and the workflow of requesting reviews from this team in the devguide, so that would be a good place to add the link.

On how that happens, I expect the process would be somewhat similar to triage team requests at the moment -- you would need a sponsor, but it wouldn't be too onerous.

If we start adding more teams, then we might want to come up with a more generic process to request membership, but that's a separate issue/discussion.