diff --git a/content/en/docs/contribute/_index.md b/content/en/docs/contribute/_index.md index 64abcae3f1..164797446e 100644 --- a/content/en/docs/contribute/_index.md +++ b/content/en/docs/contribute/_index.md @@ -13,68 +13,39 @@ we're happy to have your help! Anyone can contribute, whether you're new to the project or you've been around a long time, and whether you self-identify as a developer, an end user, or someone who just can't stand seeing typos. -For information on the Kubernetes documentation - content and style, see the - [Documentation style overview](/docs/contribute/style/). +{{% /capture %}} {{% capture body %}} -## Types of docs contributors +## Getting Started -- A _member_ of the Kubernetes organization who has [signed the CLA](/docs/contribute/start#sign-the-cla) - and contributed some time and effort to the project. See - [Community membership](https://github.com/kubernetes/community/blob/master/community-membership.md) - for specific criteria for membership. -- A SIG Docs _reviewer_ is a member of the Kubernetes organization who has - expressed interest in reviewing documentation pull requests and who has been - added to the appropriate GitHub group and `OWNERS` files in the GitHub - repository, by a SIG Docs Approver. -- A SIG Docs _approver_ is a member in good standing who has shown a continued - commitment to the project. An approver can merge pull requests - and publish content on behalf of the Kubernetes organization. - Approvers can also represent SIG Docs in the larger Kubernetes community. - Some of the duties of a SIG Docs approver, such as coordinating a release, - require a significant time commitment. +Anyone can open an issue describing problems or desired improvements with documentation, or contribute a change with a pull request (PR). +Some tasks require more trust and need more access in the Kubernetes organization. +See [Participating in SIG Docs](/docs/contribute/participating/) for more details about +of roles and permissions. -## Ways to contribute to documentation +Kubernetes documentation resides in a GitHub repository. While we welcome +contributions from anyone, you do need basic comfort with git and GitHub to +operate effectively in the Kubernetes community. -This list is divided into things anyone can do, things Kubernetes organization -members can do, and things that require a higher level of access and familiarity -with SIG Docs processes. Contributing consistently over time can help you -understand some of the tooling and organizational decisions that have already -been made. +To get involved with documentation: -This is not an exhaustive list of ways you can contribute to the Kubernetes -documentation, but it should help you get started. +1. Sign the CNCF [Contributor License Agreement](https://github.com/kubernetes/community/blob/master/CLA.md). +2. Familiarize yourself with the [documentation repository](https://github.com/kubernetes/website) and the website's [static site generator](https://gohugo.io). +3. Make sure you understand the basic processes for [improving content](https://kubernetes.io/docs/contribute/start/#improve-existing-content) and [reviewing changes](https://kubernetes.io/docs/contribute/start/#review-docs-pull-requests). -- [Anyone](/docs/contribute/start/) - - Open actionable issues -- [Member](/docs/contribute/start/) - - Improve existing docs - - Bring up ideas for improvement on [Slack](http://slack.k8s.io/) or the [SIG docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs) - - Improve docs accessibility - - Provide non-binding feedback on PRs - - Write a blog post or case study -- [Reviewer](/docs/contribute/intermediate/) - - Document new features - - Triage and categorize issues - - Review PRs - - Create diagrams, graphics assets, and embeddable screencasts / videos - - Localization - - Contribute to other repos as a docs representative - - Edit user-facing strings in code - - Improve code comments, Godoc -- [Approver](/docs/contribute/advanced/) - - Publish contributor content by approving and merging PRs - - Participate in a Kubernetes release team as a docs representative - - Propose improvements to the style guide - - Propose improvements to docs tests - - Propose improvements to the Kubernetes website or other tooling - - -## Additional ways to contribute +## Other ways to contribute - To contribute to the Kubernetes community through online forums like Twitter or Stack Overflow, or learn about local meetups and Kubernetes events, visit the [Kubernetes community site](/community/). - To contribute to feature development, read the [contributor cheatsheet](https://github.com/kubernetes/community/tree/master/contributors/guide/contributor-cheatsheet) to get started. {{% /capture %}} + +{{% capture whatsnext %}} + +- For more information about the basics of contributing to documentation, read [Start contributing](/docs/contribute/start/). +- Follow the [Kubernetes documentation style guide](/docs/contribute/style/style-guide/) when proposing changes. +- For more information about SIG Docs, read [Participating in SIG Docs](/docs/contribute/participating/). +- For more information about localizing Kubernetes docs, read [Localizing Kubernetes documentation](/docs/contribute/localization/). + +{{% /capture %}} diff --git a/content/en/docs/contribute/participating.md b/content/en/docs/contribute/participating.md index c9785388ab..b63c33e915 100644 --- a/content/en/docs/contribute/participating.md +++ b/content/en/docs/contribute/participating.md @@ -19,7 +19,7 @@ SIG Docs welcomes content and reviews from all contributors. Anyone can open a pull request (PR), and anyone is welcome to file issues about content or comment on pull requests in progress. -Within SIG Docs, you may also become a [member](#members), +You can also become a [member](#members), [reviewer](#reviewers), or [approver](#approvers). These roles require greater access and entail certain responsibilities for approving and committing changes. See [community-membership](https://github.com/kubernetes/community/blob/master/community-membership.md) @@ -34,51 +34,47 @@ aspects of Kubernetes -- the Kubernetes website and documentation. ## Roles and responsibilities -When a pull request is merged to the branch used to publish content (currently -`master`), that content is published and available to the world. To ensure that -the quality of our published content is high, we limit merging pull requests to -SIG Docs approvers. Here's how it works. +- **Anyone** can contribute to Kubernetes documentation. To contribute, you must [sign the CLA](/docs/contribute/start#sign-the-cla) and have a GitHub account. +- **Members** of the Kubernetes organization are contributors who have spent time and effort on the Kubernetes project, usually by opening pull requests with accepted changes. See [Community membership](https://github.com/kubernetes/community/blob/master/community-membership.md) for membership criteria. +- A SIG Docs **Reviewer** is a member of the Kubernetes organization who has + expressed interest in reviewing documentation pull requests, and has been + added to the appropriate GitHub group and `OWNERS` files in the GitHub + repository by a SIG Docs Approver. +- A SIG Docs **Approver** is a member in good standing who has shown a continued + commitment to the project. An approver can merge pull requests + and publish content on behalf of the Kubernetes organization. + Approvers can also represent SIG Docs in the larger Kubernetes community. + Some duties of a SIG Docs approver, such as coordinating a release, + require a significant time commitment. -- When a pull request has both the `lgtm` and `approve` labels and has no `hold` - labels, the pull request merges automatically. -- Kubernetes organization members and SIG Docs approvers can add comments to - prevent automatic merging of a given pull request (by adding a `/hold` comment - or withholding a `/lgtm` comment). -- Any Kubernetes member can add the `lgtm` label, by adding a `/lgtm` comment. -- Only an approver who is a member of SIG Docs can cause a pull request to merge - by adding an `/approve` comment. Some approvers also perform additional - specific roles, such as [PR Wrangler](#pr-wrangler) or - [SIG Docs chairperson](#sig-docs-chairperson). +## Anyone -For more information about expectations and differences between the roles of -Kubernetes organization member and SIG Docs approvers, see -[Types of contributor](/docs/contribute#types-of-contributor). The following -sections cover more details about these roles and how they work within -SIG Docs. +Anyone can do the following: -### Anyone +- Open a GitHub issue against any part of Kubernetes, including documentation. +- Provide non-binding feedback on a pull request/ +- Bring up ideas for improvement on [Slack](http://slack.k8s.io/) or the [SIG docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs). +- Use the `/lgtm` Prow command (short for "looks good to me") to recommend the changes in a pull request for merging. + {{< note >}} + If you are not a member of the Kubernetes organization, using `/lgtm` has no effect on automated systems. + {{< /note >}} -Anyone can file an issue against any part of Kubernetes, including documentation. +After [signing the CLA](/docs/contribute/start#sign-the-cla), anyone can also: +- Open a pull request to improve existing content, add new content, or write a blog post or case study. -Anyone who has signed the CLA can submit a pull request. If you cannot sign the -CLA, the Kubernetes project cannot accept your contribution. +## Members -### Members +Members are contributors to the Kubernetes project who meet the [membership criteria](https://github.com/kubernetes/community/blob/master/community-membership.md#member). SIG Docs welcomes contributions from all members of the Kubernetes community, +and frequently requests reviews from members of other SIGs for technical accuracy. -Any member of the [Kubernetes organization](https://github.com/kubernetes) can -review a pull request, and SIG Docs team members frequently request reviews from -members of other SIGs for technical accuracy. -SIG Docs also welcomes reviews and feedback regardless of a person's membership -status in the Kubernetes organization. You can indicate your approval by adding -a comment of `/lgtm` to a pull request. If you are not a member of the -Kubernetes organization, your `/lgtm` has no effect on automated systems. +Any member of the [Kubernetes organization](https://github.com/kubernetes) can do the following: -Any member of the Kubernetes organization can add a `/hold` comment to prevent -the pull request from being merged. Any member can also remove a `/hold` comment -to cause a PR to be merged if it already has both `/lgtm` and `/approve` applied -by appropriate people. +- Everything listed under [Anyone](#anyone) +- Use the `/lgtm` comment to add the LGTM (looks good to me) label to a pull request. +- Use the `/hold` command to prevent a pull request from being merged, if the pull request already has the LGTM and approve labels. +- Use the `/assign` comment to assign a reviewer to a pull request. -#### Becoming a member +### Becoming a member After you have successfully submitted at least 5 substantive pull requests, you can request [membership](https://github.com/kubernetes/community/blob/master/community-membership.md#member) @@ -86,11 +82,11 @@ in the Kubernetes organization. Follow these steps: 1. Find two reviewers or approvers to [sponsor](/docs/contribute/advanced#sponsor-a-new-contributor) your membership. - - Ask for sponsorship in the [#sig-docs channel on the + + Ask for sponsorship in the [#sig-docs channel on the Kubernetes Slack instance](https://kubernetes.slack.com) or on the [SIG Docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs). - + {{< note >}} Don't send a direct email or Slack direct message to an individual SIG Docs member. @@ -108,20 +104,29 @@ in the Kubernetes organization. Follow these steps: GitHub issue to show approval and then closes the GitHub issue. Congratulations, you are now a member! -If for some reason your membership request is not accepted right away, the +If your membership request is not accepted, the membership committee provides information or steps to take before applying again. -### Reviewers +## Reviewers Reviewers are members of the [@kubernetes/sig-docs-pr-reviews](https://github.com/orgs/kubernetes/teams/sig-docs-pr-reviews) -GitHub group. See [Teams and groups within SIG Docs](#teams-and-groups-within-sig-docs). +GitHub group. Reviewers review documentation pull requests and provide feedback on proposed +changes. Reviewers can: -Reviewers review documentation pull requests and provide feedback on proposed -changes. +- Do everything listed under [Anyone](#anyone) and [Members](#members) +- Document new features +- Triage and categorize issues +- Review pull requests and provide binding feedback +- Create diagrams, graphics assets, and embeddable screencasts and videos +- Localization +- Edit user-facing strings in code +- Improve code comments -Automation assigns reviewers to pull requests, and contributors can request a +### Assigning reviewers to pull requests + +Automation assigns reviewers to all pull requests. You can request a review from a specific reviewer with a comment on the pull request: `/assign [@_github_handle]`. To indicate that a pull request is technically accurate and requires no further changes, a reviewer adds a `/lgtm` comment to the pull @@ -129,18 +134,14 @@ request. If the assigned reviewer has not yet reviewed the content, another reviewer can step in. In addition, you can assign technical reviewers and wait for them to -provide `/lgtm`. +provide a `/lgtm` comment. -For a trivial change or one that needs no technical review, the SIG Docs -[approver](#approvers) can provide the `/lgtm` as well. +For a trivial change or one that needs no technical review, SIG Docs +[approvers](#approvers) can provide the `/lgtm` as well. -A `/approve` comment from a reviewer is ignored by automation. +An `/approve` comment from a reviewer is ignored by automation. -For more about how to become a SIG Docs reviewer and the responsibilities and -time commitment involved, see -[Becoming a reviewer or approver](#becoming-an-approver-or-reviewer). - -#### Becoming a reviewer +### Becoming a reviewer When you meet the [requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#reviewer), @@ -161,26 +162,27 @@ If you are approved, request that a current SIG Docs approver add you to the GitHub group. Only members of the `kubernetes-website-admins` GitHub group can add new members to a GitHub group. -### Approvers +## Approvers Approvers are members of the [@kubernetes/sig-docs-maintainers](https://github.com/orgs/kubernetes/teams/sig-docs-maintainers) GitHub group. See [Teams and groups within SIG Docs](#teams-and-groups-within-sig-docs). -Approvers have the ability to merge a PR, and thus, to publish content on the -Kubernetes website. To approve a PR, an approver leaves an `/approve` comment on -the PR. If someone who is not an approver leaves the approval comment, -automation ignores it. +Approvers can do the following: + +- Everything listed under [Anyone](#anyone), [Members](#members) and [Reviewers](#reviewers) +- Publish contributor content by approving and merging pull requests using the `/approve` comment. + If someone who is not an approver leaves the approval comment, automation ignores it. +- Participate in a Kubernetes release team as a docs representative +- Propose improvements to the style guide +- Propose improvements to docs tests +- Propose improvements to the Kubernetes website or other tooling If the PR already has a `/lgtm`, or if the approver also comments with `/lgtm`, the PR merges automatically. A SIG Docs approver should only leave a `/lgtm` on a change that doesn't need additional technical review. -For more about how to become a SIG Docs approver and the responsibilities and -time commitment involved, see -[Becoming a reviewer or approver](#becoming-an-approver-or-reviewer). - -#### Becoming an approver +### Becoming an approver When you meet the [requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#approver), @@ -201,34 +203,29 @@ If you are approved, request that a current SIG Docs approver add you to the GitHub group. Only members of the `kubernetes-website-admins` GitHub group can add new members to a GitHub group. -#### Approver responsibilities +### Approver responsibilities Approvers improve the documentation by reviewing and merging pull requests into the website repository. Because this role carries additional privileges, approvers have additional responsibilities: - Approvers can use the `/approve` command, which merges PRs into the repo. A careless merge can break the site, so be sure that when you merge something, you mean it. - -- Make sure that proposed changes meet the contribution guidelines. + +- Make sure that proposed changes meet the [contribution guidelines](/docs/contribute/style/content-guide/#contributing-content). If you ever have a question, or you're not sure about something, feel free to call for additional review. -- Verify that netlify tests pass before you `/approve` a PR. +- Verify that Netlify tests pass before you `/approve` a PR. Netlify tests must pass before approving -- Visit the netlify page preview for a PR to make sure things look good before approving. +- Visit the Netlify page preview for a PR to make sure things look good before approving. -#### PR Wrangler - -SIG Docs approvers participate in the -[PR Wrangler rotation scheduler](https://github.com/kubernetes/website/wiki/PR-Wranglers) -for weekly rotations. SIG Docs expects all approvers to participate in this -rotation. See -[Be the PR Wrangler for a week](/docs/contribute/advanced#be-the-pr-wrangler-for-a-week) +- Participate in the [PR Wrangler rotation scheduler](https://github.com/kubernetes/website/wiki/PR-Wranglers) for weekly rotations. SIG Docs expects all approvers to participate in this +rotation. See [Be the PR Wrangler for a week](/docs/contribute/advanced#be-the-pr-wrangler-for-a-week) for more details. -#### SIG Docs chairperson +## SIG Docs chairperson Each SIG, including SIG Docs, selects one or more SIG members to act as chairpersons. These are points of contact between SIG Docs and other parts of @@ -285,6 +282,24 @@ The combination of OWNERS files and front-matter in Markdown files determines the advice PR owners get from automated systems about who to ask for technical and editorial review of their PR. +## How merging works + +When a pull request is merged to the branch used to publish content (currently +`master`), that content is published and available to the world. To ensure that +the quality of our published content is high, we limit merging pull requests to +SIG Docs approvers. Here's how it works. + +- When a pull request has both the `lgtm` and `approve` labels, has no `hold` + labels, and all tests are passing, the pull request merges automatically. +- Kubernetes organization members and SIG Docs approvers can add comments to + prevent automatic merging of a given pull request (by adding a `/hold` comment + or withholding a `/lgtm` comment). +- Any Kubernetes member can add the `lgtm` label by adding a `/lgtm` comment. +- Only SIG Docs approvers can merge a pull request + by adding an `/approve` comment. Some approvers also perform additional + specific roles, such as [PR Wrangler](#pr-wrangler) or + [SIG Docs chairperson](#sig-docs-chairperson). + {{% /capture %}} {{% capture whatsnext %}} @@ -295,5 +310,3 @@ For more information about contributing to the Kubernetes documentation, see: - [Documentation style](/docs/contribute/style/) {{% /capture %}} - -