From 372eec8f5c9839682ebcfcf4f928b3116659f28b Mon Sep 17 00:00:00 2001
From: Joseph Heck <heckj@mac.com>
Date: Sat, 17 Feb 2018 00:10:38 -0800
Subject: [PATCH] Roles sigdocs (#7133)
* strawman structure
* updates from PR review/feedback
* consolidate usage of SIG Docs and how to volunteer into a single location
* adding into ToC
* updates for Zach
* re-organizing and adding back approver lgtm comment
---
_data/docs-home.yml | 1 +
docs/home/contribute/participating.md | 109 ++++++++++++++++++++++++++
editdocs.md | 5 ++
3 files changed, 115 insertions(+)
create mode 100644 docs/home/contribute/participating.md
diff --git a/_data/docs-home.yml b/_data/docs-home.yml
index bdb1e7c935..2458cf4ec5 100644
--- a/_data/docs-home.yml
+++ b/_data/docs-home.yml
@@ -10,6 +10,7 @@ toc:
landing_page: /editdocs/
section:
- editdocs.md
+ - docs/home/contribute/participating.md
- docs/home/contribute/create-pull-request.md
- docs/home/contribute/write-new-topic.md
- docs/home/contribute/stage-documentation-changes.md
diff --git a/docs/home/contribute/participating.md b/docs/home/contribute/participating.md
new file mode 100644
index 0000000000..d86fb1910a
--- /dev/null
+++ b/docs/home/contribute/participating.md
@@ -0,0 +1,109 @@
+---
+title: Participating in SIG-DOCS
+---
+
+{% capture overview %}
+
+SIG-DOCS is one of the [special interest groups](https://github.com/kubernetes/community/blob/master/sig-list.md) within the Kubernetes project, focused on writing, updating, and maintaining the documentation for Kubernetes as a whole.
+
+{% endcapture %}
+
+{% capture body %}
+
+SIG Docs welcomes content and reviews from all contributors. Anyone can open a pull request (PR), and anyone is welcome to comment on content or pull requests in progress.
+
+Within the Kubernetes project, you may also become a member, reviewer, or approver.
+These roles confer additional privileges and responsibilities when it comes to approving and committing changes.
+See [community-membership](https://github.com/kubernetes/community/blob/master/community-membership.md) for more information on how membership works within the Kubernetes community.
+
+## Roles and Responsibilities
+
+The automation reads `/hold`, `/lgtm`, and `/approve` comments and sets labels on the pull request.
+When a pull request has the `lgtm` and `approve` labels without any `hold` labels, the pull request merges automatically.
+Kubernetes org members, and reviewers and approvers for SIG Docs can add comments to control the merge automation.
+
+- Members
+
+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 Kubernetes org membership.
+You can indicate your approval by adding a comment of `/lgtm` to a pull request.
+
+- Reviewers
+
+Reviewers are individuals who review documentation pull requests.
+
+Automation assigns reviewers to pull requests, and contributors can request a review with a comment on the pull request: `/assign [@_github_handle]`.
+To indicate that a pull request requires no further changes, a reviewer should add comment to the pull request `/lgtm`.
+A reviewer indicates technical accuracy with a `lgtm` comment.
+
+Reviewers can add a `/hold` comment to prevent the pull request from being merged.
+Another reviewer or approver can remove a hold with the comment: `/hold cancel`.
+
+When a reviewer is assigned a pull request to review it is not a sole responsibility, and any other reviewer may also offer their opinions on the pull request.
+If a reviewer is requested, it is generally expected that the PR will be left to that reviewer to do their editorial pass on the content.
+If a PR author or SIG Docs maintainer requests a review, refrain from merging or closing the PR until the requested reviewer completes their review.
+
+- Approvers
+
+Approvers have the ability to merge a PR.
+
+Approvers can indicate their approval with a comment to the pull request: `/approve`.
+An approver is indicating editorial approval with the an `/approve` comment.
+
+Approvers can add a `/hold` comment to prevent the pull request from being merged.
+Another reviewer or approver can remove a hold with the comment: `/hold cancel`.
+
+Approvers may skip further reviews for small pull requests if the proposed changes appear trivial and/or well-understood.
+An approver can indicate `/lgtm` or `/approve` in a PR comment to have a pull request merged, and all pull requests require at least one approver to provide their vote in order for the PR to be merged.
+
+**Note:** There is a special case when an approver uses the comment: `/lgtm`. In these cases, the automation will add both `lgtm` and `approve` tags, skipping any further review.
++{: .note }
+
+For PRs that require no review (typos or otherwise trivial changes), approvers can enter an `lgtm` comment, indicating no need for further review and flagging the PR with approval to merge.
+
+### Teams and groups within SIG Docs
+
+You can get an overview of [SIG Docs from the community github repo](https://github.com/kubernetes/community/tree/master/sig-docs).
+The SIG Docs group defines two teams on Github:
+ - [@kubernetes/sig-docs-maintainers](https://github.com/orgs/kubernetes/teams/sig-docs-maintainers)
+ - [@kubernetes/sig-docs-pr-reviews](https://github.com/orgs/kubernetes/teams/sig-docs-pr-reviews)
+
+These groups maintain the [Kubernetes website repository](https://github.com/kubernetes/website), which houses the content hosted at this site.
+Both can be referenced with their `@name` in github comments to communicate with everyone in that group.
+
+These teams overlap, but do not exactly match, the groups used by the automation tooling.
+For assignment of issues, pull requests, and to support PR approvals, the automation uses information from the OWNERS file.
+
+To volunteer as a reviewer or approver, make a pull request and add your Github handle to the relevant section in the [OWNERS file](https://github.com/kubernetes/community/blob/master/contributors/devel/owners.md).
+
+**Note:** Reviewers and approvers must meet requirements for participation.
+For more information, see the [Kubernetes community](https://github.com/kubernetes/community/blob/master/community-membership.md#membership) repository.
+{: .note }
+
+Documentation for the [OWNERS](https://github.com/kubernetes/community/blob/master/contributors/devel/owners.md) explains how to maintain OWNERS for each repository that enables it.
+
+The [Kubernetes website repository](https://github.com/kubernetes/website) has two automation (prow) [plugins enabled](https://github.com/kubernetes/test-infra/blob/master/prow/plugins.yaml#L210):
+- blunderbuss
+- approve
+
+These two plugins use the [OWNERS](https://github.com/kubernetes/website/blob/master/OWNERS) and [OWNERS_ALIAS](https://github.com/kubernetes/website/blob/master/OWNERS_ALIAS) files in our repo for configuration.
+
+{% endcapture %}
+
+{% capture whatsnext %}
+For more information about contributing to the Kubernetes documentation, see:
+
+* Review the SIG Docs [Style Guide](/docs/home/contribute/style-guide/).
+* Learn how to [stage your documentation changes](/docs/home/contribute/stage-documentation-changes/).
+* Learn about [writing a new topic](/docs/home/contribute/write-new-topic/).
+* Learn about [using page templates](/docs/home/contribute/page-templates/).
+* Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/).
+* Learn about [creating a pull request](/docs/home/contribute/create-pull-request/).
+* How to generate documentation:
+ * Learn how to [generate Reference Documentation for Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
+ * Learn how to [generate Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/)
+ * Learn how to [generate Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/)
+ * Learn how to [generate Reference Pages for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/)
+{% endcapture %}
+
+{% include templates/concept.md %}
diff --git a/editdocs.md b/editdocs.md
index 4c7b257ba1..73d62db8ab 100644
--- a/editdocs.md
+++ b/editdocs.md
@@ -58,3 +58,8 @@ For more information about contributing to the Kubernetes documentation, see:
* [Staging Your Documentation Changes](/docs/home/contribute/stage-documentation-changes/)
* [Using Page Templates](/docs/home/contribute/page-templates/)
* [Documentation Style Guide](/docs/home/contribute/style-guide/)
+* How to work with generated documentation
+ * [Generating Reference Documentation for Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
+ * [Generating Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/)
+ * [Generating Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/)
+ * [Generating Reference Pages for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/)