mirror of https://github.com/knative/docs.git
Clarifying Docs contributor roles (#958)
* Clarifying Docs contributing roles * Clarifying how contributors become members/approvers * Add docs-reviewers alias * Add gyliu513 as docs reviewer * Update DOCS-CONTRIBUTING.md * Update DOCS-CONTRIBUTING.md * Apply suggestions from code review Co-Authored-By: samodell <31352624+samodell@users.noreply.github.com> * Applying comments from DOCS-CONTRIBUTING.md The text in DOCS-CONTRIBUTING was pulled from ROLES, so I'm making the same changes here as I did there. * Update DOCS-CONTRIBUTING.md * Update DOCS-CONTRIBUTING.md
This commit is contained in:
Sam O'Dell
Knative Prow Robot
parent
e095752269
commit
3f7a02ec80
1
OWNERS
1
OWNERS
|
|
@ -5,3 +5,4 @@ approvers:
|
|||
- docs-approvers
|
||||
reviewers:
|
||||
- docs-approvers
|
||||
- docs-reviewers
|
||||
|
|
|
|||
|
|
@ -10,3 +10,5 @@ aliases:
|
|||
- carieshmarie
|
||||
- samodell
|
||||
- richieescarez
|
||||
docs-reviewers:
|
||||
- gyliu513
|
||||
|
|
|
|||
|
|
@ -1,5 +1,9 @@
|
|||
# Contributing to the Knative Documentation
|
||||
|
||||
- [Before you begin](#before-you-begin)
|
||||
- [Contributing to the documentation](#contributing-to-the-documentation)
|
||||
- [Docs contributor roles](#docs-contributor-roles)
|
||||
|
||||
**First off, thanks for taking the time to contribute!**
|
||||
|
||||
The following are guidelines for contributing to the Knative documentation.
|
||||
|
|
@ -20,7 +24,9 @@ Knative documentation follows the
|
|||
[Google Developer Documentation Style Guide](https://developers.google.com/style/);
|
||||
use it as a reference for writing style questions.
|
||||
|
||||
## Reporting documentation issues
|
||||
## Contributing to the documentation
|
||||
|
||||
### Reporting documentation issues
|
||||
|
||||
Knative uses Github issues to track documentation issues and requests. If you
|
||||
see a problem with the documentation, submit an issue using the following steps:
|
||||
|
|
@ -42,7 +48,6 @@ Note that code issues should be filed against the
|
|||
[individual Knative repositories](http://github.com/knative), while
|
||||
documentation issues should go in the `docs` repository.
|
||||
|
||||
## Contributing to the documentation
|
||||
|
||||
### Working group
|
||||
|
||||
|
|
@ -98,3 +103,122 @@ Code samples follow a similar strategy, where most code samples should be
|
|||
located in the `docs` repository. If there are code samples used for testing
|
||||
that are only expected to be used by contributors, those samples are put in the
|
||||
`samples` folder within the component repo.
|
||||
|
||||
## Docs contributor roles
|
||||
|
||||
Because contributing to the documentation requires a different skill set than
|
||||
contributing to the Knative code base, we've defined the roles of
|
||||
documentation contributors seperately from the roles of code contributors.
|
||||
|
||||
If you're looking for code contributor roles, see [ROLES](./ROLES.md).
|
||||
|
||||
### Member
|
||||
|
||||
Established contributor to the Knative docs.
|
||||
|
||||
Members are continuously active contributors in the community. They can have
|
||||
issues and PRs assigned to them, might participate in working group meetings, and
|
||||
pre-submit tests are automatically run for their PRs. Members are expected to
|
||||
remain active contributors to the Knative documentation.
|
||||
|
||||
All members are encouraged to help with PR reviews, although each PR
|
||||
must be reviewed by an official [Approver](#approver). In their review,
|
||||
members should be looking for technical correctness of the documentation,
|
||||
adherence to the [style guide](https://developers.google.com/style/), good spelling and grammar (writing quality),
|
||||
intuitive organization, and strong documentation usability. Members should be
|
||||
proficient in at least one of these review areas.
|
||||
|
||||
### Requirements
|
||||
|
||||
- Has made multiple contributions to the project or community. Contributions might
|
||||
include, but are not limited to:
|
||||
|
||||
- Authoring and reviewing PRs on GitHub in the Docs or Website repos.
|
||||
|
||||
- Filing and commenting on issues on GitHub.
|
||||
|
||||
- Contributing to working group or community discussions.
|
||||
|
||||
- Subscribed to
|
||||
[knative-dev@googlegroups.com](https://groups.google.com/forum/#!forum/knative-dev).
|
||||
|
||||
- Actively contributing to 1 or more areas.
|
||||
|
||||
- Sponsored by 1 approver.
|
||||
|
||||
- Done by adding GitHub user to Knative organization.
|
||||
|
||||
### Responsibilities and privileges
|
||||
|
||||
- Responsive to issues and PRs assigned to them.
|
||||
|
||||
- Active owner of documents they have contributed (unless ownership is explicitly
|
||||
transferred).
|
||||
|
||||
- Addresses bugs or issues in their documentation in a timely manner.
|
||||
|
||||
### Becoming a member
|
||||
|
||||
First, reach out to an approver and ask them to sponsor you so that you can become a member.
|
||||
The easiest way to do this is using Slack.
|
||||
|
||||
If they are supportive of your membership, your sponsor will reach out to the Knative Steering
|
||||
committee to ask that you be added as a member of the Knative org.
|
||||
|
||||
Once your sponsor notifies you that you've been added to the Knative org,
|
||||
open a PR to add yourself as a docs-reviewer in the
|
||||
[OWNERS_ALIASES](../OWNERS_ALIASES) file.
|
||||
|
||||
## Approver
|
||||
|
||||
Docs approvers are able to both review and approve documentation contributions.
|
||||
While documentation review is focused on writing quality and correctness,
|
||||
approval is focused on holistic acceptance of a contribution including:
|
||||
long-term maintainability, adhering to style guide conventions, overall information
|
||||
architecture, and usability from an engineering standpoint. Docs approvers will
|
||||
enlist help from engineers for reviewing code-heavy contributions to the Docs repo.
|
||||
|
||||
### Requirements
|
||||
|
||||
- Reviewer of the Docs repo for at least 3 months.
|
||||
|
||||
- Proficient in reviewing all aspects of writing quality, including grammar and
|
||||
spelling, adherence to style guide conventions, organization, and usability.
|
||||
Can coach newer writers to improve their contributions in these areas.
|
||||
|
||||
- Primary reviewer for at least 10 substantial PRs to the docs, showing substantial
|
||||
ability to coach for writing development.
|
||||
|
||||
- Reviewed or merged at least 30 PRs to the docs.
|
||||
|
||||
- Nominated by an area lead (with no objections from other leads).
|
||||
|
||||
- Done through PR to update an OWNERS file.
|
||||
|
||||
### Responsibilities and privileges
|
||||
|
||||
- Responsible for documentation quality control via PR reviews.
|
||||
|
||||
- Focus on long-term maintainability, adhering to style
|
||||
guide conventions, overall information architecture, and usability from
|
||||
an engineering standpoint.
|
||||
|
||||
- Expected to be responsive to review requests as per
|
||||
[community expectations](REVIEWING.md).
|
||||
|
||||
- Mentor members and contributors to improve their writing.
|
||||
|
||||
- Might approve documentation contributions for acceptance, but will ask for
|
||||
engineering review for code-heavy contributions.
|
||||
|
||||
### Becoming an approver
|
||||
|
||||
If you want to become an approver, make your goal clear to the current
|
||||
Knative Docs approvers, either by contacting them in Slack or announcing
|
||||
your intention to become an approver at a meeting of the Documentation
|
||||
Working Group.
|
||||
|
||||
Once you feel you meet the criteria, you can ask one of the current
|
||||
approvers to nominate you to become an approver. If all existing
|
||||
approvers agree that you meet the criteria open a PR to add yourself
|
||||
as a docs-approver in the [OWNERS_ALIASES](../OWNERS_ALIASES) file.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Knative Community Roles
|
||||
|
||||
This document describes the set of roles individuals may have within the Knative
|
||||
This document describes the set of roles individuals might have within the Knative
|
||||
community, the requirements of each role, and the privileges that each role
|
||||
grants.
|
||||
|
||||
|
|
@ -104,7 +104,7 @@ table describes:
|
|||
|
||||
## Collaborator
|
||||
|
||||
Individuals may be added as an outside collaborator (with READ access) to a repo
|
||||
Individuals can be added as an outside collaborator (with READ access) to a repo
|
||||
in the Knative GitHub organization without becoming a member. This role allows
|
||||
them to be assigned issues and PRs until they become a member, but will not
|
||||
allow tests to be run against their PRs automatically nor allow them to interact
|
||||
|
|
@ -113,11 +113,10 @@ with the PR bot.
|
|||
### Requirements
|
||||
|
||||
- Working on some contribution to the project that would benefit from the
|
||||
ability to have PRs or Issues to be assigned to the contributor
|
||||
ability to have PRs or Issues to be assigned to the contributor.
|
||||
|
||||
- Join [knative-users@](https://groups.google.com/forum/#!forum/knative-users)
|
||||
unrestricted join permissions; this grants read access to documents in the
|
||||
Team Drive
|
||||
, which grants read access to documents in the Team Drive.
|
||||
|
||||
## Member
|
||||
|
||||
|
|
@ -126,7 +125,7 @@ principles in this document, familiarity with project organization, roles,
|
|||
policies, procedures, conventions, etc., and technical and/or writing ability.
|
||||
|
||||
Members are continuously active contributors in the community. They can have
|
||||
issues and PRs assigned to them, may participate in working group meetings, and
|
||||
issues and PRs assigned to them, participate in working group meetings, and
|
||||
pre-submit tests are automatically run for their PRs. Members are expected to
|
||||
remain active contributors to the community.
|
||||
|
||||
|
|
@ -134,41 +133,41 @@ All members are encouraged to help with the code review burden, although each PR
|
|||
must be reviewed by an official [Approver](#approver).
|
||||
|
||||
When reviewing, members should focus on code quality and correctness, including
|
||||
testing and factoring. Members may also review for more holistic issues, but
|
||||
testing and factoring. Members might also review for more holistic issues, but
|
||||
this is not a requirement.
|
||||
|
||||
### Requirements
|
||||
|
||||
- Has made multiple contributions to the project or community. Contributions may
|
||||
- Has made multiple contributions to the project or community. Contributions might
|
||||
include, but are not limited to:
|
||||
|
||||
- Authoring or reviewing PRs on GitHub
|
||||
- Authoring and reviewing PRs on GitHub.
|
||||
|
||||
- Filing or commenting on issues on GitHub
|
||||
- Filing and commenting on issues on GitHub.
|
||||
|
||||
- Contributing to working group or community discussions
|
||||
- Contributing to working group or community discussions.
|
||||
|
||||
- Subscribed to
|
||||
[knative-dev@googlegroups.com](https://groups.google.com/forum/#!forum/knative-dev)
|
||||
[knative-dev@googlegroups.com](https://groups.google.com/forum/#!forum/knative-dev).
|
||||
|
||||
- Actively contributing to 1 or more areas.
|
||||
|
||||
- Sponsored by 1 approver.
|
||||
|
||||
- Done by adding GitHub user to Knative organization
|
||||
- Done by adding GitHub user to Knative organization.
|
||||
|
||||
### Responsibilities and privileges
|
||||
|
||||
- Responsive to issues and PRs assigned to them
|
||||
- Responsive to issues and PRs assigned to them.
|
||||
|
||||
- Active owner of code they have contributed (unless ownership is explicitly
|
||||
transferred)
|
||||
transferred).
|
||||
|
||||
- Code is well tested
|
||||
- Code is well tested.
|
||||
|
||||
- Tests consistently pass
|
||||
- Tests consistently pass.
|
||||
|
||||
- Addresses bugs or issues discovered after code is accepted
|
||||
- Addresses bugs or issues discovered after code is accepted.
|
||||
|
||||
Members who frequently contribute code are expected to proactively perform code
|
||||
reviews and work towards becoming an approver for the area that they are active
|
||||
|
|
@ -188,9 +187,9 @@ status is scoped to a part of the codebase.
|
|||
The following apply to the part of the codebase for which one would be an
|
||||
approver in an OWNERS file:
|
||||
|
||||
- Reviewer of the codebase for at least 3 months or 50% of project lifetime,
|
||||
whichever is shorter
|
||||
- Reviewer of the codebase for at least 3 months.
|
||||
|
||||
- Primary reviewer for at least 10 substantial PRs to the codebase.
|
||||
- One path for getting the necessary reviews is to add yourself to the
|
||||
`reviewers` section of the OWNERS file. Note that this does not give
|
||||
you any additional privileges. By having yourself listed in this
|
||||
|
|
@ -199,36 +198,32 @@ approver in an OWNERS file:
|
|||
discretion of an approver after enough evidence of quality
|
||||
contributions.
|
||||
|
||||
- Primary reviewer for at least 10 substantial PRs to the codebase
|
||||
- Reviewed or merged at least 30 PRs to the codebase.
|
||||
|
||||
- Reviewed or merged at least 30 PRs to the codebase
|
||||
- Nominated by an area lead (with no objections from other leads).
|
||||
|
||||
- Nominated by an area lead
|
||||
|
||||
- With no objections from other leads
|
||||
|
||||
- Done through PR to update an OWNERS file
|
||||
- Done through PR to update an OWNERS file.
|
||||
|
||||
### Responsibilities and privileges
|
||||
|
||||
The following apply to the part of the codebase for which one would be an
|
||||
approver in an OWNERS file:
|
||||
|
||||
- Approver status may be a precondition to accepting large code contributions
|
||||
- Approver status can be a precondition to accepting large code contributions.
|
||||
|
||||
- Demonstrate sound technical judgement
|
||||
- Demonstrate sound technical judgement.
|
||||
|
||||
- Responsible for project quality control via [code reviews](REVIEWING.md)
|
||||
- Responsible for project quality control via [code reviews](REVIEWING.md).
|
||||
|
||||
- Focus on holistic acceptance of contribution such as dependencies with other
|
||||
features, backward / forward compatibility, API and flag definitions, etc
|
||||
features, backward / forward compatibility, API and flag definitions, etc.
|
||||
|
||||
- Expected to be responsive to review requests as per
|
||||
[community expectations](REVIEWING.md)
|
||||
[community expectations](REVIEWING.md).
|
||||
|
||||
- Mentor members and contributors
|
||||
- Mentor members and contributors.
|
||||
|
||||
- May approve code contributions for acceptance
|
||||
- Might approve code contributions for acceptance.
|
||||
|
||||
## Lead
|
||||
|
||||
|
|
@ -240,23 +235,23 @@ and approve design decisions for their area of ownership.
|
|||
|
||||
Getting to be a lead of an existing working group:
|
||||
|
||||
- Recognized as having expertise in the group’s subject matter
|
||||
- Recognized as having expertise in the group’s subject matter.
|
||||
|
||||
- Approver for some part of the codebase for at least 3 months
|
||||
- Approver for some part of the codebase for at least 3 months.
|
||||
|
||||
- Member for at least 1 year or 50% of project lifetime, whichever is shorter
|
||||
- Member for at least 1 year or 50% of project lifetime, whichever is shorter.
|
||||
|
||||
- Primary reviewer for 20 substantial PRs
|
||||
- Primary reviewer for 20 substantial PRs.
|
||||
|
||||
- Reviewed or merged at least 50 PRs
|
||||
- Reviewed or merged at least 50 PRs.
|
||||
|
||||
- Sponsored by the technical oversight committee
|
||||
- Sponsored by the technical oversight committee.
|
||||
|
||||
Additional requirements for leads of a new working group:
|
||||
|
||||
- Originally authored or contributed major functionality to the group's area
|
||||
- Originally authored or contributed major functionality to the group's area.
|
||||
|
||||
- An approver in the OWNERS file for the group’s code
|
||||
- An approver in the OWNERS file for the group’s code.
|
||||
|
||||
### Responsibilities and privileges
|
||||
|
||||
|
|
@ -270,23 +265,23 @@ The following apply to the area / component for which one would be an owner.
|
|||
|
||||
- Perform issue triage on GitHub.
|
||||
|
||||
- Apply/remove/create/delete GitHub labels and milestones
|
||||
- Apply/remove/create/delete GitHub labels and milestones.
|
||||
|
||||
- Write access to repo (assign issues/PRs, add/remove labels and milestones,
|
||||
edit issues and PRs, edit wiki, create/delete labels and milestones)
|
||||
edit issues and PRs, edit wiki, create/delete labels and milestones).
|
||||
|
||||
- Capable of directly applying lgtm + approve labels for any PR
|
||||
- Capable of directly applying lgtm + approve labels for any PR.
|
||||
|
||||
- Expected to respect OWNERS files approvals and use
|
||||
[standard procedure for merging code](REVIEWING.md#merging-prs).
|
||||
|
||||
- Expected to work to holistically maintain the health of the project through:
|
||||
|
||||
- Reviewing PRs
|
||||
- Reviewing PRs.
|
||||
|
||||
- Fixing bugs
|
||||
- Fixing bugs.
|
||||
|
||||
- Mentoring and guiding approvers, members, and contributors
|
||||
- Mentoring and guiding approvers, members, and contributors.
|
||||
|
||||
## Administrator
|
||||
|
||||
|
|
@ -299,15 +294,15 @@ Administrators are responsible for the bureaucratic aspects of the project.
|
|||
### Responsibilities and privileges
|
||||
|
||||
- Manage the Knative GitHub repo, including granting membership and controlling
|
||||
repo read/write permissions
|
||||
repo read/write permissions.
|
||||
|
||||
- Manage the Knative Slack team
|
||||
- Manage the Knative Slack team.
|
||||
|
||||
- Manage the Knative Google group forum
|
||||
- Manage the Knative Google group forum.
|
||||
|
||||
- Manage any additional Knative technical collaboration assets
|
||||
- Manage any additional Knative technical collaboration assets.
|
||||
|
||||
- Expected to be responsive to membership and permission change requests
|
||||
- Expected to be responsive to membership and permission change requests.
|
||||
<!-- TODO SLA for admin response -->
|
||||
|
||||
<!-- * TODO Manage the Google Search Console settings for knative.dev -->
|
||||
|
|
|
|||
Loading…
Reference in New Issue