-
Notifications
You must be signed in to change notification settings - Fork 14.3k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Reorganize docs contrib guide (#9510)
* Reorganize docs contrib guide * Address first round of feedback from Brad, Jared * Standardize on 'SIG Docs' * Address more feedback * Rewrites to participating.md * Tweak navigation titles * Document PR Wrangler * Document SIG Docs chairperson * Fix codeblock that shows how to use <codenew> It was being interpreted as a Hugo shortcode.
- Loading branch information
1 parent
4920a51
commit 5ae0d0d
Showing
38 changed files
with
1,891 additions
and
860 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,6 +1,9 @@ | ||
>^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
> Please delete this note before submitting the pull request. | ||
> For 1.12 Features: set Milestone to 1.12 and Base Branch to release-1.12 | ||
> Help editing and submitting pull requests: https://deploy-preview-9510--kubernetes-io-master-staging.netlify.com/docs/contribute/start/#submit-a-pull-request. | ||
> Help choosing which branch to use, see | ||
> https://kubernetes.io/docs/contribute/start#choose-which-git-branch-to-use. | ||
>^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ||
> | ||
> Please delete this note before submitting the pull request. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,73 @@ | ||
--- | ||
content_template: templates/concept | ||
title: Contribute to Kubernetes docs | ||
linktitle: Contribute | ||
main_menu: true | ||
weight: 80 | ||
--- | ||
|
||
{{% capture overview %}} | ||
|
||
If you would like to help contribute to the Kubernetes documentation or website, | ||
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. | ||
|
||
Looking for the [style guide](/docs/contribute/style/style-guide/)? | ||
{{% /capture %}} | ||
|
||
{{% capture body %}} | ||
|
||
## Types of contributor | ||
|
||
- A _member_ of the Kubernetes organization has [signed the CLA](/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 and is granted the ability to merge pull requests | ||
and thus to 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. | ||
|
||
## Ways to contribute | ||
|
||
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. | ||
|
||
This is not an exhaustive list of ways you can contribute to the Kubernetes | ||
documentation, but it should help you get started. | ||
|
||
- [Anyone](/docs/contribute/start/) | ||
- File actionable bugs | ||
- [Member](/docs/contribute/start/) | ||
- Improve existing docs | ||
- Bring up ideas for improvement on Slack or SIG docs mailing list | ||
- 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 | ||
|
||
{{% /capture %}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,87 @@ | ||
--- | ||
title: Advanced contributing | ||
slug: advanced | ||
content_template: templates/concept | ||
weight: 30 | ||
--- | ||
|
||
{{% capture overview %}} | ||
|
||
This page assumes that you've read and mastered the | ||
[Start contributing](/docs/contribute/start/) and | ||
[Intermediate contributing](/docs/contribute/intermediate/) topics and are ready | ||
to learn about more ways to contribute. You need to use the Git command line | ||
client and other tools for some of these tasks. | ||
|
||
{{% /capture %}} | ||
|
||
{{% capture body %}} | ||
|
||
## Be the PR Wrangler for a week | ||
|
||
SIG Docs approvers are added to the | ||
[PR Wrangler rotation scheduler](https://github.com/kubernetes/website/wiki/PR-Wranglers) | ||
for weekly rotations. The PR wrangler's duties include: | ||
|
||
- Review incoming pull requests daily. | ||
- Help new contributors sign the CLA, and close any PR where the CLA hasn't | ||
been signed for two weeks. PR authors can reopen the PR after signing the | ||
CLA, so this is a low-risk way to make sure nothing gets merged without a | ||
signed CLA. | ||
- Provide feedback on proposed changes, including helping facilitate technical | ||
review from members of other SIGs. | ||
- Merge PRs when they are ready, or close PRs that shouldn't be accepted. | ||
- Triage and tag incoming issues daily. See | ||
[Intermediate contributing](/docs/contribute/intermediate/) for guidelines | ||
about how SIG Docs uses metadata. | ||
|
||
## Propose improvements | ||
|
||
After you've been contributing to the Kubernetes documentation for a while, you | ||
may have ideas for improvement to the style guide, the toolchain used to build | ||
the documentation, the website style, the processes for reviewing and merging | ||
pull requests, or other aspects of the documentation. For maximum transparency, | ||
these types of proposals need to be discussed in a SIG Docs meeting or on the | ||
[kubernetes-sig-docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs). | ||
In addition, it can really help to have some context about the way things | ||
currently work and why past decisions have been made before proposing sweeping | ||
changes. The quickest way to get answers to questions about how the documentation | ||
currently works is to ask in the `#sig-docs` Slack channel on | ||
[kubernetes.slack.com](https://kubernetes.slack.com) | ||
|
||
After discussion has taken place and the sig is in agreement about the desired | ||
outcome, you can work on the proposed changes in the way that is the most | ||
appropriate. For instance, an update to the style guide or the website's | ||
functionality might involve opening a pull request, while a change related to | ||
documentation testing might involve working with sig-testing. | ||
|
||
## Coordinate docs for a Kubernetes release | ||
|
||
Each Kubernetes release is coordinated by a team of people participating in the | ||
sig-release special interest group (SIG). Others on the release team for a given | ||
release include an overall release lead, as well as representatives from sig-pm, | ||
sig-testing, and others. To find out more about Kubernetes release processes, | ||
refer to | ||
[https://github.com/kubernetes/sig-release](https://github.com/kubernetes/sig-release). | ||
|
||
The SIG Docs representative for a given release coordinates the following tasks: | ||
|
||
- Monitor the feature-tracking spreadsheet for new or changed features with an | ||
impact on documentation. If documentation for a given feature won't be ready | ||
for the release, the feature may not be allowed to go into the release. | ||
- Attend sig-release meetings regularly and give updates on the status of the | ||
docs for the release. | ||
- Review and copyedit feature documentation drafted by the sig responsible for | ||
implementing the feature. | ||
- Merge release-related pull requests and maintain the Git feature branch for | ||
the release. | ||
- Mentor other SIG Docs contributors who want to learn how to do this role in | ||
the future. This is known as "shadowing". | ||
- Publish the documentation changes related to the release when the release | ||
artifacts are published. | ||
|
||
Coordinating a release is typically a 3-4 month commitment, and the duty is | ||
rotated among SIG Docs approvers. | ||
|
||
{{% /capture %}} | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
--- | ||
title: Reference docs overview | ||
main_menu: true | ||
weight: 80 | ||
--- | ||
|
||
Much of the Kubernetes reference documentation is generated from Kubernetes | ||
source code, using scripts. The topics in this section document how to generate | ||
this type of content. |
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
Oops, something went wrong.