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.pull/9770/head
Misty Linville
k8s-ci-robot
parent
4920a51665
commit
5ae0d0dd8d
|
|
@ -1,4 +1,5 @@
|
|||
<!-- Thanks for filing an issue! Before submitting, please fill in the following information. -->
|
||||
<!-- See https://kubernetes.io/docs/contribute/start/ for guidance on writing an actionable issue description. -->
|
||||
|
||||
<!--Required Information-->
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
11
README.md
11
README.md
|
|
@ -8,13 +8,10 @@ Once your pull request is created, a Kubernetes reviewer will take responsibilit
|
|||
|
||||
For more information about contributing to the Kubernetes documentation, see:
|
||||
|
||||
* [Contributing to the Kubernetes Documentation](http://kubernetes.io/editdocs/)
|
||||
* [Creating a Documentation Pull Request](http://kubernetes.io/docs/home/contribute/create-pull-request/)
|
||||
* [Writing a New Topic](http://kubernetes.io/docs/home/contribute/write-new-topic/)
|
||||
* [Review Issues](http://kubernetes.io/docs/home/contribute/review-issues/)
|
||||
* [Staging Your Documentation Changes](http://kubernetes.io/docs/home/contribute/stage-documentation-changes/)
|
||||
* [Using Page Templates](http://kubernetes.io/docs/home/contribute/page-templates/)
|
||||
* [Documentation Style Guide](http://kubernetes.io/docs/home/contribute/style-guide/)
|
||||
* [Start contributing](http://kubernetes.io/contribute/start/)
|
||||
* [Staging Your Documentation Changes](http://kubernetes.io/docs/contribute/intermediate#view-your-changes-locally)
|
||||
* [Using Page Templates](http://kubernetes.io/docs/contribute/style/page-templates/)
|
||||
* [Documentation Style Guide](http://kubernetes.io/docs/contribute/style/style-guide/)
|
||||
|
||||
## Building the site using Docker
|
||||
|
||||
|
|
|
|||
|
|
@ -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 %}}
|
||||
|
|
@ -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 %}}
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
@ -0,0 +1,789 @@
|
|||
---
|
||||
title: Intermediate contributing
|
||||
slug: intermediate
|
||||
content_template: templates/concept
|
||||
weight: 20
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
This page assumes that you've read and mastered the tasks in the
|
||||
[start contributing](/docs/contribute/start/) topic and are ready to
|
||||
learn about more ways to contribute.
|
||||
|
||||
{{< note >}}
|
||||
**Note:** Some tasks require you to use the Git command line client and other
|
||||
tools.
|
||||
{{< /note >}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
Now that you've gotten your feet wet and helped out with the Kubernetes docs in
|
||||
the ways outlined in the [start contributing](/docs/contribute/start/) topic,
|
||||
you may feel ready to do more. These tasks assume that you have, or are willing
|
||||
to gain, deeper knowledge of the following topic areas:
|
||||
|
||||
- Kubernetes concepts
|
||||
- Kubernetes documentation workflows
|
||||
- Where and how to find information about upcoming Kubernetes features
|
||||
- Strong research skills in general
|
||||
|
||||
These tasks are not as sequential as the beginner tasks. There is no expectation
|
||||
that one person does all of them all of the time.
|
||||
|
||||
## Review pull requests
|
||||
|
||||
In any given week, a specific docs approver volunteers to do initial triage
|
||||
and review of [pull requests and issues](#triage-and-categorize-issues). This
|
||||
person is the "PR Wrangler" for the week. The schedule is maintained using the
|
||||
[PR Wrangler scheduler(https://github.com/kubernetes/website/wiki/PR-Wranglers).
|
||||
To be added to this list, attend the weekly SIG Docs meeting and volunteer. Even
|
||||
if you are not on the schedule for the current week, you can still review pull
|
||||
requests (PRs) that are not already under active review.
|
||||
|
||||
In addition to the rotation, an automated system comments on each new PR and
|
||||
suggests reviewers and approvers for the PR, based on the list of approvers and
|
||||
reviewers in the affected files. The PR author is expected to follow the
|
||||
guidance of the bot, and this also helps PRs to get reviewed quickly.
|
||||
|
||||
We want to get pull requests (PRs) merged and published as quickly as possible.
|
||||
To ensure the docs are accurate and up to date, each PR needs to be reviewed by
|
||||
people who understand the content, as well as people with experience writing
|
||||
great documentation.
|
||||
|
||||
Reviewers and approvers need to provide actionable and constructive feedback to
|
||||
keep contributors engaged and help them to improve. Sometimes helping a new
|
||||
contributor get their PR ready to merge takes more time than just rewriting it
|
||||
yourself, but the project is better in the long term when we have a diversity of
|
||||
active participants.
|
||||
|
||||
Before you start reviewing PRs, make sure you are familiar with the
|
||||
[Documentation Style Guide](/docs/contribute/style/style-guide/)
|
||||
and the [code of conduct]() <!-- TODO when #9355 is merged -->
|
||||
|
||||
### Find a PR to review
|
||||
|
||||
To see all open PRs, go to the **Pull Requests** tab in the Github repository.
|
||||
A PR is eligible for review when it meets all of the following criteria:
|
||||
|
||||
- Has the `cnf-cla:yes` tag
|
||||
- Does not have WIP in the description
|
||||
- Does not a have tag including the phrase `do-not-merge`
|
||||
- Has no merge conflicts
|
||||
- Is based against the correct branch (usually `master` unless the PR relates to
|
||||
a feature that has not yet been released)
|
||||
- Is not being actively reviewed by another docs person (other technical
|
||||
reviewers are fine), unless that person has explicitly asked for your help. In
|
||||
particular, leaving lots of new comments after other review cycles have
|
||||
already been completed on a PR can be discouraging and counter-productive.
|
||||
|
||||
If a PR is not eligible to merge, leave a comment to let the author know about
|
||||
the problem and offer to help them fix it. If they've been informed and have not
|
||||
fixed the problem in several weeks or months, eventually their PR will be closed
|
||||
without merging.
|
||||
|
||||
If you're new to reviewing, or you don't have a lot of bandwidth, look for PRs
|
||||
with the `size/XS` or `size/S` tag set. The size is automatically determined by
|
||||
the number of lines the PR changes.
|
||||
|
||||
#### Reviewers and approvers
|
||||
|
||||
The Kubernetes website repo operates differently than some of the Kubernetes
|
||||
code repositories when it comes to the roles of reviewers and approvers. For
|
||||
more information about the responsibilities of reviewers and approvers, see
|
||||
[Participating](/docs/contribute/participating/). Here's an overview.
|
||||
|
||||
- A reviewer reviews pull request content for technical accuracy. A reviewer
|
||||
indicates that a PR is technically accurate by leaving a `/lgtm` comment on
|
||||
the PR.
|
||||
|
||||
{{< note >}}Don't add an `/lgtm` unless you are confident in the technical
|
||||
accuracy of the documentation modified or introduced in the PR.{{< /note >}}
|
||||
|
||||
- An approver reviews pull request content for docs quality and adherence to
|
||||
SIG Docs guidelines, such as the
|
||||
[style guide](/docs/contribute/style/style-guide). Only people listed as
|
||||
approvers in the
|
||||
[`OWNERS`](https://github.com/kubernetes/website/blob/master/OWNERS) file can
|
||||
approve a PR. To approve a PR, leave an `/approved` comment on the PR.
|
||||
|
||||
A PR is merged when it has both a `/lgtm` comment from anyone in the Kubernetes
|
||||
organization and an `/approved` comment from an approver in the
|
||||
`sig-docs-maintainers` group, as long as it is not on hold and the PR author
|
||||
has signed the CLA.
|
||||
|
||||
### Review a PR
|
||||
|
||||
1. Read the PR description and read any attached issues or links, if
|
||||
applicable. "Drive-by reviewing" is sometimes more harmful than helpful, so
|
||||
make sure you have the right knowledge to provide a meaningful review.
|
||||
|
||||
2. If someone else is the best person to review this particular PR, let them
|
||||
know by adding a comment with `/assign @<github-username>`. If you have
|
||||
asked a non-docs person for technical review but still want to review the PR
|
||||
from a docs point of view, keep going.
|
||||
|
||||
3. Go to the **Files changed** tab. Look over all the changed lines. Removed
|
||||
content has a red background, and those lines also start with a `-` symbol.
|
||||
Added content has a green background, and those lines also start with a `+`
|
||||
symbol. Within a line, the actual modified content has a slightly darker
|
||||
green background than the rest of the line.
|
||||
|
||||
- Especially if the PR uses tricky formatting or changes CSS, Javascript,
|
||||
or other site-wide elements, you can preview the website with the PR
|
||||
applied. Go to the **Conversation** tab and click the **Details** link
|
||||
for the `deploy/netlify` test, near the bottom of the page. It opens in
|
||||
the same browser window by default, so open it in a new window so you
|
||||
don't lose your partial review. Switch back to the **Files changed** tab
|
||||
to resume your review.
|
||||
- Make sure the PR complies with the
|
||||
[Documentation Style Guide](/docs/contribute/style/style-guide/)
|
||||
and link the author to the relevant part of the style guide if not.
|
||||
- If you have a question, comment, or other feedback about a given
|
||||
change, hover over a line and click the blue-and-white `+` symbol that
|
||||
appears. Type your comment and click **Start a review**.
|
||||
- If you have more comments, leave them in the same way.
|
||||
- By convention, if you see a small problem that does not have to do with
|
||||
the main purpose of the PR, such as a typo or whitespace error, you can
|
||||
call it out, prefixing your comment with `nit:` so that the author knows
|
||||
you consider it trivial. They should still address it.
|
||||
- When you're reviewed everything, or if you didn't have any comments, go
|
||||
back to the top of the page and click **Review changes**. Choose either
|
||||
**Comment** or **Request Changes**. Add a summary of your review, and
|
||||
add appropriate
|
||||
[Prow commands](https://prow.k8s.io/command-help) to separate lines in
|
||||
the Review Summary field. SIG Docs follows the
|
||||
[Kubernetes code review process](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md#the-code-review-process).
|
||||
All of your comments will be sent to the PR author in a single
|
||||
notification.
|
||||
|
||||
- If you think the PR is ready to be merged, add the text `/approve` to
|
||||
your summary.
|
||||
- If the PR does not need additional technical review, add the
|
||||
text `/lgtm` as well.
|
||||
- If the PR *does* need additional technical review, add the text
|
||||
`/assign` with the Github username of the person who needs to
|
||||
provide technical review. Look at the `reviewers` field in the
|
||||
front-matter at the top of a given Markdown file to see who can
|
||||
provide technical review.
|
||||
- To prevent the PR from being merged, add `/hold`. This sets the
|
||||
label `do-not-merge/hold`.
|
||||
- If a PR has no conflicts and has the `lgtm` and `approved` label but
|
||||
no `hold` label, it is merged automatically.
|
||||
- If a PR has the `lgtm` and/or `approved` labels and new changes are
|
||||
detected, these labels are removed automatically.
|
||||
|
||||
See
|
||||
[the list of all available slash commands](https://prow.k8s.io/command-help)
|
||||
that can be used in PRs.
|
||||
|
||||
- If you previously selected **Request changes** and the PR author has
|
||||
addressed your concerns, you can change your review status either in the
|
||||
**Files changed** tab or at the bottom of the **Conversation** tab. Be
|
||||
sure to add the `/approve` tag and assign technical reviewers if necessary,
|
||||
so that the PR can be merged.
|
||||
|
||||
### Commit into another person's PR
|
||||
|
||||
Leaving PR comments is helpful, but there may be times when you need to commit
|
||||
into another person's PR, rather than just leaving a review.
|
||||
|
||||
Resist the urge to "take over" for another person unless they explicitly ask
|
||||
you to, or you want to resurrect a long-abandoned PR. While it may be faster
|
||||
in the short term, it deprives the person of the chance to contribute.
|
||||
|
||||
The process you use depends on whether you need to edit a file that is already
|
||||
in the scope of the PR or a file that the PR has not yet touched.
|
||||
|
||||
You can't commit into someone else's PR if either of the following things is
|
||||
true:
|
||||
|
||||
- If the PR author pushed their branch directly to the
|
||||
[https://github.com/kubernetes/website/](https://github.com/kubernetes/website/)
|
||||
repository, only a reviewer with push access can commit into their PR.
|
||||
Authors should be encouraged to push their branch to their fork before
|
||||
opening the PR.
|
||||
- If the PR author explicitly disallowed edits from approvers, you can't
|
||||
commit into their PR unless they change this setting.
|
||||
|
||||
#### If the file is already changed by the PR
|
||||
|
||||
This method uses the Github UI. If you prefer, you can use the command line
|
||||
even if the file you want to change is part of the PR, if you are more
|
||||
comfortable working that way.
|
||||
|
||||
1. Click the **Files changed** tab.
|
||||
2. Scroll down to the file you want to edit, and click the pencil icon for
|
||||
that file.
|
||||
3. Make your changes, add a commit message in the field below the editor, and
|
||||
click **Commit changes**.
|
||||
|
||||
Your commit is now pushed to the branch the PR represents (probably on the
|
||||
author's fork) and now shows up in the PR and your changes are reflected in
|
||||
the **Files changed** tab. Leave a comment letting the PR author know you
|
||||
changed the PR.
|
||||
|
||||
If the author is using the command line rather than the Github UI to work on
|
||||
this PR, they need to fetch their fork's changes and rebase their local branch
|
||||
on the branch in their fork, before doing additional work on the PR.
|
||||
|
||||
#### If the file has not yet been changed by the PR
|
||||
|
||||
If changes need to be made to a file that is not yet included in the PR, you
|
||||
need to use the command line. You can always use this method, if you prefer it
|
||||
to the Github UI.
|
||||
|
||||
1. Get the URL for the author's fork. You can find it near the bottom of the
|
||||
**Conversation** tab. Look for the text "Add more commits by pushing to".
|
||||
The first link after this phrase is to the branch, and the second link is
|
||||
to the fork. Copy the second link. Note the name of the branch for later.
|
||||
|
||||
2. Add the fork as a remote. In your terminal, go to your clone of the
|
||||
repository. Decide on a name to give the remote (such as the author's
|
||||
Github username), and add the remote using the following syntax:
|
||||
|
||||
```bash
|
||||
git remote add <name> <url-of-fork>
|
||||
```
|
||||
|
||||
3. Fetch the remote. This doesn't change any local files, but updates your
|
||||
clone's notion of the remote's objects (such as branches and tags) and
|
||||
their current state.
|
||||
|
||||
```bash
|
||||
git remote fetch <name>
|
||||
```
|
||||
|
||||
4. Check out the remote branch. This command will fail if you already have a
|
||||
local branch with the sane name.
|
||||
|
||||
```bash
|
||||
git checkout <branch-from-PR>
|
||||
```
|
||||
|
||||
5. Make your changes, use `git add` to add them, and commit them.
|
||||
|
||||
6. Push your changes to the author's remote.
|
||||
|
||||
```bash
|
||||
git push <remote-name> <branch-name>
|
||||
```
|
||||
|
||||
7. Go back to the Github IU and refresh the PR. Your changes appear. Leave the
|
||||
PR author a comment letting them know you changed the PR.
|
||||
|
||||
If the author is using the command line rather than the Github UI to work on
|
||||
this PR, they need to fetch their fork's changes and rebase their local branch
|
||||
on the branch in their fork, before doing additional work on the PR.
|
||||
|
||||
## Work from a local clone
|
||||
|
||||
For changes that require multiple files or changes that involve creating new
|
||||
files or moving files around, working from a local Git clone makes more sense
|
||||
than relying on the Github UI. These instructions use the `git` command and
|
||||
assume that you have it installed locally. You can adapt them to use a local
|
||||
graphical Git client instead.
|
||||
|
||||
### Clone the repository
|
||||
|
||||
You only need to clone the repository once per physical system where you work
|
||||
on the Kubernetes documentation.
|
||||
|
||||
1. In a terminal window, use `git clone` to clone the repository. You do not
|
||||
need any credentials to clone the repository.
|
||||
|
||||
```bash
|
||||
git clone https://github.com/kubernetes/website
|
||||
```
|
||||
|
||||
The new directory `website` is created in your current directory, with
|
||||
the contents of the Github repository.
|
||||
|
||||
2. Change to the new `website` directory. Rename the default `origin` remote
|
||||
to `upstream`.
|
||||
|
||||
```bash
|
||||
cd website
|
||||
|
||||
git remote rename origin upstream
|
||||
```
|
||||
|
||||
3. If you have not done so, create a fork of the repository on Github. In your
|
||||
web browser, go to
|
||||
[https://github.com/kubernetes/website](https://github.com/kubernetes/website)
|
||||
and click the **Fork** button. After a few seconds, you are redirected to
|
||||
the URL for your fork, which is typically something like
|
||||
`https://github.com/<username>/website` unless you already had a repository
|
||||
called `website`. Copy this URL.
|
||||
|
||||
4. Add your fork as a second remote, called `origin`:
|
||||
|
||||
```bash
|
||||
git remote add origin <FORK-URL>
|
||||
```
|
||||
|
||||
### Work on the local repository
|
||||
|
||||
Before you start a new unit of work on your local repository, you need to figure
|
||||
out which branch to base your work on. The answer depends on what you are doing,
|
||||
but the following guidelines apply:
|
||||
|
||||
- For general improvements to existing content, start from `master`.
|
||||
- For new content that is about features that already exist in a released
|
||||
version of Kubernetes, start from `master`.
|
||||
- For long-running efforts that multiple SIG Docs contributors will collaborate on,
|
||||
such as content reorganization, use a specific feature branch created for that
|
||||
effort.
|
||||
- For new content that relates to upcoming but unreleased Kubernetes versions,
|
||||
use the pre-release feature branch created for that Kubernetes version.
|
||||
|
||||
For more guidance, see
|
||||
[Choose which branch to use](docs/contribute/start#choose-which-git-branch-to-use).
|
||||
|
||||
After you decide which branch to start your work (or _base it on_, in Git
|
||||
terminology), use the following workflow to be sure your work is based on the
|
||||
most up-to-date version of that branch.
|
||||
|
||||
1. Fetch both the `upstream` and `origin` branches. This updates your local
|
||||
notion of what those branches contain, but does not change your local
|
||||
branches at all.
|
||||
|
||||
```bash
|
||||
git fetch upstream
|
||||
git fetch origin
|
||||
```
|
||||
|
||||
2. Create a new tracking branch based on the branch you decided is the most
|
||||
appropriate. This example assumes you are using `master`.
|
||||
|
||||
```bash
|
||||
git checkout -b <my_new_branch> upstream/master
|
||||
```
|
||||
|
||||
This new branch is based on `upstream/master`, not your local `master`.
|
||||
It tracks `upstream/master`.
|
||||
|
||||
3. With your new branch checked out, make your changes using a text editor.
|
||||
At any time, use the `git status` command to see what you've changed.
|
||||
|
||||
4. When you are ready to submit a pull request, commit your changes. First
|
||||
use `git status` to see what changes need to be added to the changeset.
|
||||
There are two important sections: `Changes staged for commit` and
|
||||
`Changes not staged for commit`. Any files that show up in the latter
|
||||
section under `modified` or `untracked` need to be added if you want them to
|
||||
be part of this commit. For each file that needs to be added, use `git add`.
|
||||
|
||||
```bash
|
||||
git add example-file.md
|
||||
```
|
||||
|
||||
When all your intended changes are included, create a commit, using the
|
||||
`git commit` command:
|
||||
|
||||
```bash
|
||||
git commit -m "Your commit message"
|
||||
```
|
||||
|
||||
{{< note >}}
|
||||
Do not reference a Github issue or pull request by ID or URL in the
|
||||
commit message. If you do, it will cause that issue or pull request to get
|
||||
a notification every time the commit shows up in a new Git branch. You can
|
||||
link issues and pull requests together later, in the Github UI.
|
||||
{{< /note >}}
|
||||
|
||||
5. Optionally, you can test your change by staging the site locally using the
|
||||
`hugo` command. See [View your changes locally](#view-your-changes-locally).
|
||||
You'll be able to view your changes after you submit the pull request, as
|
||||
well.
|
||||
|
||||
6. Before you can create a pull request which includes your local commit, you
|
||||
need to push the branch to your fork, which is the endpoint for the `origin`
|
||||
remote.
|
||||
|
||||
```bash
|
||||
git push origin <my_new_branch>
|
||||
```
|
||||
|
||||
Technically, you can omit the branch name from the `push` command, but
|
||||
the behavior in that case depends upon the version of Git you are using.
|
||||
The results are more repeatable if you include the branch name.
|
||||
|
||||
7. At this point, if you go to https://github.com/kubernetes/website in your
|
||||
web browser, Github detects that you pushed a new branch to your fork and
|
||||
offers to create a pull request. Fill in the pull request template.
|
||||
|
||||
- The title should be no more than 50 characters and summarize the intent
|
||||
of the change.
|
||||
- The long-form description should contain more information about the fix,
|
||||
including a line like `Fixes #12345` if the pull request fixes a Github
|
||||
issue. This will cause the issue to be closed automatically when the
|
||||
pull request is merged.
|
||||
- You can add labels or other metadata and assign reviewers. See
|
||||
[Triage and categorize issues](#triage-and-categorize-issues) for the
|
||||
syntax.
|
||||
|
||||
Click **Create pull request**.
|
||||
|
||||
8. Several automated tests will run against the state of the website with your
|
||||
changes applied. If any of the tests fails, click the **Details** link for
|
||||
more information. If the Netlify test completes successfully, its
|
||||
**Details** link goes to a staged version of the Kubernetes website with
|
||||
your changes applied. This is how reviewers will check your changes.
|
||||
|
||||
9. If you notice that more changes need to be made, or if reviewers give you
|
||||
feedback, address the feedback locally, then repeat step 4 - 6 again,
|
||||
creating a new commit. The new commit is added to your pull request and the
|
||||
tests run again, including re-staging the Netlify staged site.
|
||||
|
||||
10. If a reviewer adds changes to your pull request, you need to fetch those
|
||||
changes from your fork before you can add more changes. Use the following
|
||||
commands to do this, assuming that your branch is currently checked out.
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
git rebase origin/<your-branch-name>
|
||||
```
|
||||
|
||||
After rebasing, you need to add the `-f` flag to force-push new changes to
|
||||
the branch to your fork.
|
||||
|
||||
```bash
|
||||
git push -f origin <your-branch-name>
|
||||
```
|
||||
|
||||
11. If someone else's change is merged into the branch your work is based on,
|
||||
and you have made changes to the same parts of the same files, a conflict
|
||||
might occur. If the pull request shows that there are conflicts to resolve,
|
||||
you can resolve them using the Github UI or you can resolve them locally.
|
||||
|
||||
First, do step 10 to be sure that your fork and your local branch are in
|
||||
the same state.
|
||||
|
||||
Next, fetch `upstream` and rebase your branch on the branch it was
|
||||
originally based on, like `upstream/master`.
|
||||
|
||||
```bash
|
||||
git fetch upstream
|
||||
git rebase upstream/master
|
||||
```
|
||||
|
||||
If there are conflicts Git can't automatically resolve, you can see the
|
||||
conflicted files using the `git status` command. For each conflicted file,
|
||||
edit it and look for the conflict markers `>>>`, `<<<`, and `===`. Resolve
|
||||
the conflict and remove the conflict markers. Then add the changes to the
|
||||
changeset using `git add <filename>` and continue the rebase using
|
||||
`git rebase --continue`. When all commits have been applied and there are
|
||||
no more conflicts, `git status` will show that you are not in a rebase and
|
||||
there are no changes that need to be committed. At that point, force-push
|
||||
the branch to your fork, and the pull request should no longer show any
|
||||
conflicts.
|
||||
|
||||
If you're having trouble resolving conflicts or you get stuck with
|
||||
anything else related to your pull request, ask for help on the `#sig-docs`
|
||||
Slack channel or the
|
||||
[kubernetes-sig-docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
|
||||
|
||||
### View your changes locally
|
||||
|
||||
If you aren't ready to create a pull request but you want to see what your
|
||||
changes look like, you can use the `hugo` command to stage the changes locally.
|
||||
|
||||
1. Install Hugo version `0.40.3` or later.
|
||||
|
||||
2. In a terminal, go to the root directory of your clone of the Kubernetes
|
||||
docs, and enter this command:
|
||||
|
||||
```bash
|
||||
hugo server
|
||||
```
|
||||
|
||||
3. In your browser’s address bar, enter `localhost:1313`.
|
||||
|
||||
4. To stop the local Hugo instance, go back to the terminal and type `Ctrl+C`
|
||||
or just close the terminal window.
|
||||
|
||||
|
||||
## Triage and categorize issues
|
||||
|
||||
In any given week, a specific docs approver volunteers to do initial
|
||||
[triage and review of pull requests](#review-pull-requests) and issues. To get
|
||||
on this list, attend the weekly SIG Docs meeting and volunteer. Even if you are
|
||||
not on the schedule for the current week, you can still review PRs.
|
||||
|
||||
People in SIG Docs are only responsible for triaging and categorizing
|
||||
documentation issues. General website issues are also filed in the
|
||||
`kubernetes/website` repository.
|
||||
|
||||
When you triage an issue, you:
|
||||
|
||||
- Assess whether the issue has merit. Some issues can be closed quickly by
|
||||
answering a question or pointing the reporter to a resource.
|
||||
- Ask the reporter for more information if the issue doesn't have enough
|
||||
detail to be actionable or the template is not filled out adequately.
|
||||
- Add labels (sometimes called tags), projects, or milestones to the issue.
|
||||
Projects and milestones are not heavily used by the SIG Docs team.
|
||||
- At your discretion, taking ownership of an issue and submitting a PR for it
|
||||
(especially if it is quick or relates to work you were already doing).
|
||||
|
||||
If you have questions about triaging an issue, ask in `#sig-docs` on Slack or
|
||||
the
|
||||
[kubernetes-sig-docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs).
|
||||
|
||||
### More about labels
|
||||
|
||||
These guidelines are not set in stone and are subject to change.
|
||||
|
||||
- An issue can have multiple labels.
|
||||
- Some labels use slash notation for grouping, which can be thought of like
|
||||
"sub-labels". For instance, many `sig/` labels exist, such as `sig/cli` and
|
||||
`sig/api-machinery`.
|
||||
- Some labels are automatically added based on metadata in the files involved
|
||||
in the issue, slash commands used in the comments of the issue, or
|
||||
information in the issue text.
|
||||
- Some labels are manually added by the person triaging the issue (or the person
|
||||
reporting the issue, if they are a SIG Docs approvers).
|
||||
- `Actionable`: there seems to be enough information for the issue to be fixed
|
||||
or acted upon.
|
||||
- `good first issue`: Someone with limited Kubernetes or SIG Docs experience
|
||||
might be able to tackle this issue.
|
||||
- `kind/bug`, `kind/feature`, and `kind/documentation`: If the person who
|
||||
filed the issue did not fill out the template correctly, these labels may
|
||||
not be assigned automatically. A bug is a problem with existing content or
|
||||
functionality, and a feature is a request for new content or functionality.
|
||||
The `kind/documentation` label is not currently in use.
|
||||
- Priority labels: define the relative severity of the issue. These do not
|
||||
conform to those outlined in the
|
||||
[Kubernetes contributor guide](https://github.com/kubernetes/community/blob/master/contributors/guide/issue-triage.md#define-priority), and can be one of `P1`, `P2`, or `P3`, if set.
|
||||
- To add a label, you can use Github's **Labels** widget if you are a Sig Docs
|
||||
approver. Anyone who is a member of the Kubernetes organization can add a
|
||||
label by leaving a comment like `/label <label-to-add>`. The label must
|
||||
already exist. If you try to add a label that does not exist, the command is
|
||||
silently ignored.
|
||||
|
||||
### Priorities
|
||||
|
||||
An issue's priority influences how quickly it is addressed. For documentation,
|
||||
here are the guidelines for setting a priority on an issue:
|
||||
|
||||
#### P1
|
||||
|
||||
- Major content errors affecting more than 1 page
|
||||
- Broken code sample on a heavily trafficked page
|
||||
- Errors on a “getting started” page
|
||||
- Well known or highly publicized customer pain points
|
||||
- Automation issues
|
||||
|
||||
#### P2
|
||||
|
||||
This is the default for new issues and pull requests.
|
||||
|
||||
- Broken code for sample that is not heavily used
|
||||
- Minor content issues in a heavily trafficked page
|
||||
- Major content issues on a lower-trafficked page
|
||||
|
||||
#### P3
|
||||
|
||||
- Typos and broken anchor links
|
||||
- Documentation feature requests
|
||||
- "Nice to have" items
|
||||
|
||||
### Handling special issue types
|
||||
|
||||
We've encountered the following types of issues often enough to document how
|
||||
to handle them.
|
||||
|
||||
#### Duplicate issues
|
||||
|
||||
If a single problem has one or more issues open for it, the problem should be
|
||||
consolidated into a single issue. You should decide which issue to keep open (or
|
||||
open a new issue), port over all relevant information, link related issues, and
|
||||
close all the other issues that describe the same problem. Only having a single
|
||||
issue to work on will help reduce confusion and avoid duplicating work on the
|
||||
same problem.
|
||||
|
||||
#### Dead link issues
|
||||
|
||||
Depending on where the dead link is reported, different actions are required to
|
||||
resolve the issue. Dead links in the API and Kubectl docs are automation issues
|
||||
and should be assigned a P1 until the problem can be fully understood. All other
|
||||
dead links are issues that need to be manually fixed and can be assigned a P3.
|
||||
|
||||
#### Support requests or code bug reports
|
||||
|
||||
Some issues opened for docs are instead issues with the underlying code, or
|
||||
requests for assistance when something (like a tutorial) didn’t work. For issues
|
||||
unrelated to docs, close the issue with a comment directing the requester to
|
||||
support venues (Slack, Stack Overflow) and, if relevant, where to file an issue
|
||||
for bugs with features (kubernetes/kubernetes is a great place to start).
|
||||
|
||||
Sample response to a request for support:
|
||||
|
||||
```none
|
||||
This issue sounds more like a request for support and less
|
||||
like an issue specifically for docs. I encourage you to bring
|
||||
your question to the `#kubernetes-users` channel in
|
||||
[Kubernetes slack](http://slack.k8s.io/). You can also search
|
||||
resources like
|
||||
[Stack Overflow](http://stackoverflow.com/questions/tagged/kubernetes)
|
||||
for answers to similar questions.
|
||||
|
||||
You can also open issues for Kubernetes functionality in
|
||||
https://github.com/kubernetes/kubernetes.
|
||||
|
||||
If this is a documentation issue, please re-open this issue.
|
||||
```
|
||||
|
||||
Sample code bug report response:
|
||||
|
||||
```none
|
||||
This sounds more like an issue with the code than an issue with
|
||||
the documentation. Please open an issue at
|
||||
https://github.com/kubernetes/kubernetes/issues.
|
||||
|
||||
If this is a documentation issue, please re-open this issue.
|
||||
```
|
||||
|
||||
## Document new features
|
||||
|
||||
Each major Kubernetes release includes new features, and many of them need
|
||||
at least a small amount of documentation to show people how to use them.
|
||||
|
||||
Often, the SIG responsible for a feature submits draft documentation for the
|
||||
feature as a pull request to the appropriate release branch of
|
||||
`kubernetes/website` repository, and someone on the SIG Docs team provides
|
||||
editorial feedback or edits the draft directly.
|
||||
|
||||
### Find out about upcoming features
|
||||
|
||||
To find out about upcoming features, attend the weekly sig-release meeting (see
|
||||
the [community](https://kubernetes.io/community/) page for upcoming meetings)
|
||||
and monitor the release-specific documentation
|
||||
in the [kubernetes/sig-release](https://github.com/kubernetes/sig-release/)
|
||||
repository. Each release has a sub-directory under the [/sig-release/tree/master/releases/](https://github.com/kubernetes/sig-release/tree/master/releases)
|
||||
directory. Each sub-directory contains a release schedule, a draft of the release
|
||||
notes, and a document listing each person on the release team.
|
||||
|
||||
- The release schedule contains links to all other documents, meetings,
|
||||
meeting minutes, and milestones relating to the release. It also contains
|
||||
information about the goals and timeline of the release, and any special
|
||||
processes in place for this release. Near the bottom of the document, several
|
||||
release-related terms are defined.
|
||||
|
||||
This document also contains a link to the **Feature tracking sheet**, which is
|
||||
the official way to find out about all new features scheduled to go into the
|
||||
release.
|
||||
- The release team document lists who is responsible for each release role. If
|
||||
it's not clear who to talk to about a specific feature or question you have,
|
||||
either attend the release meeting to ask your question, or contact the release
|
||||
lead so that they can redirect you.
|
||||
- The release notes draft is a good place to find out a little more about
|
||||
specific features, changes, deprecations, and more about the release. The
|
||||
content is not finalized until late in the release cycle, so use caution.
|
||||
|
||||
#### The feature tracking sheet
|
||||
|
||||
The feature tracking sheet
|
||||
[for a given Kubernetes release](https://github.com/kubernetes/sig-release/tree/master/releases) lists each feature that is planned for a release.
|
||||
Each line item includes the name of the feature, a link to the feature's main
|
||||
Github issue, its stability level (Alpha, Beta, or Stable), the SIG and
|
||||
individual responsible for implementing it, whether it
|
||||
needs docs, a draft release note for the feature, and whether it has been
|
||||
merged. Keep the following in mind:
|
||||
|
||||
- Beta and Stable features are generally a higher documentation priority than
|
||||
Alpha features.
|
||||
- It's hard to test (and therefore, document) a feature that hasn't been merged,
|
||||
or is at least considered feature-complete in its PR.
|
||||
- Determining whether a feature needs documentation is a manual process and
|
||||
just because a feature is not marked as needing docs doesn't mean it doesn't
|
||||
need them.
|
||||
|
||||
### Document a feature
|
||||
|
||||
As stated above, draft content for new features is usually submitted by the SIG
|
||||
responsible for implementing the new feature. This means that your role may be
|
||||
more of a shepherding role for a given feature than developing the documentation
|
||||
from scratch.
|
||||
|
||||
After you've chosen a feature to document/shepherd, ask about it in the `#sig-docs`
|
||||
Slack channel, in a weekly sig-docs meeting, or directly on the PR filed by the
|
||||
feature SIG. If you're given the go-ahead, you can edit into the PR using one of
|
||||
the techniques described in
|
||||
[Commit into another person's PR](#commit-into-another-persons-pr).
|
||||
|
||||
If you need to write a new topic, the following links are useful:
|
||||
- [Writing a New Topic](/docs/contribute/style/write-new-topic/)
|
||||
- [Using Page Templates](/docs/contribute/style/page-templates/)
|
||||
- [Documentation Style Guide](/docs/contribute/style/style-guide/)
|
||||
|
||||
### SIG members documenting new features
|
||||
|
||||
If you are a member of a SIG developing a new feature for Kubernetes, you need
|
||||
to work with SIG Docs to be sure your feature is documented in time for the
|
||||
release. Check the
|
||||
[feature tracking spreadsheet](https://github.com/kubernetes/sig-release/tree/master/releases)
|
||||
or check in the #sig-release Slack channel to verify scheduling details and
|
||||
deadlines. Some deadlines related to documentation are:
|
||||
|
||||
- **Docs deadline - Open placeholder PRs**: Open a pull request against the
|
||||
`release-X.Y` branch in the `kubernetes/website` repository, with a small
|
||||
commit that you will amend later. Use the Prow command `/milestone X.Y` to
|
||||
assign the PR to the relevant milestone. This alerts the docs person managing
|
||||
this release that the feature docs are coming. If your feature does not need
|
||||
any documentation changes, make sure the sig-release team knows this, by
|
||||
mentioning it in the #sig-release Slack channel. If the feature does need
|
||||
documentation but the PR is not created, the feature may be removed from the
|
||||
milestone.
|
||||
- **Docs deadline - PRs ready for review**: Your PR now needs to contain a first
|
||||
draft of the documentation for your feature. Don't worry about formatting or
|
||||
polishing. Just describe what the feature does and how to use it. The docs
|
||||
person managing the release will work with you to get the content into shape
|
||||
to be published. If your feature needs documentation and the first draft
|
||||
content is not received, the feature may be removed from the milestone.
|
||||
- **Docs complete - All PRs reviewed and ready to merge**: If your PR has not
|
||||
yet been merged into the `release-X.Y` branch by this deadline, work with the
|
||||
docs person managing the release to get it in. If your feature needs
|
||||
documentation and the docs are not ready, the feature may be removed from the
|
||||
milestone.
|
||||
|
||||
## Contribute to other repos
|
||||
|
||||
The [Kubernetes project](https://github.com/kubernetes) contains more than 50
|
||||
individual repositories. Many of these repositories contain code or content that
|
||||
can be considered documentation, such as user-facing help text, error messages,
|
||||
user-facing text in API references, or even code comments.
|
||||
|
||||
If you see text and you aren't sure where it comes from, you can use Github's
|
||||
search tool at the level of the Kubernetes organization to search through all
|
||||
repositories for that text. This can help you figure out where to submit your
|
||||
issue or PR.
|
||||
|
||||
Each repository may have its own processes and procedures. Before you file an
|
||||
issue or submit a PR, read that repository's `README.md`, `CONTRIBUTING.md`, and
|
||||
`code-of-conduct.md`, if they exist.
|
||||
|
||||
Most repositories use issue and PR templates. Have a look through some open
|
||||
issues and PRs to get a feel for that team's processes. Make sure to fill out
|
||||
the templates with as much detail as possible when you file issues or PRs.
|
||||
|
||||
## Localize content
|
||||
|
||||
The Kubernetes documentation is written in English first, but we want people to
|
||||
be able to read it in their language of choice. If you are comfortable
|
||||
writing in another language, especially in the software domain, you can help
|
||||
localize the Kubernetes documentation or provide feedback on existing localized
|
||||
content. See [Localization](/docs/contribute/localization/) and ask on the
|
||||
[kubernetes-sig-docs mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs)
|
||||
or in `#sig-docs` on Slack if you are interested in helping out.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
When you are comfortable with all of the tasks discussed in this topic and you
|
||||
want to engage with the Kubernetes docs team in even deeper ways, read the
|
||||
[advanced docs contributor](/docs/contribute/advanced/) topic.
|
||||
|
||||
{{% /capture %}}
|
||||
|
|
@ -0,0 +1,219 @@
|
|||
---
|
||||
title: Participating in SIG Docs
|
||||
content_template: templates/concept
|
||||
---
|
||||
|
||||
{{% 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. See
|
||||
[SIG Docs from the community github repo](https://github.com/kubernetes/community/tree/master/sig-docs)
|
||||
for more information about the SIG.
|
||||
|
||||
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),
|
||||
[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)
|
||||
for more information on how membership works within the Kubernetes community.
|
||||
The rest of this document outlines some unique ways these roles function within
|
||||
SIG Docs, which is responsible for maintaining one of the most public-facing
|
||||
aspects of Kubernetes -- the Kubernetes website and documentation.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
## 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.
|
||||
|
||||
- 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).
|
||||
|
||||
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
|
||||
|
||||
Anyone can file an issue against any part of Kubernetes, including documentation.
|
||||
|
||||
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
|
||||
|
||||
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 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.
|
||||
|
||||
### 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).
|
||||
|
||||
Reviewers review documentation pull requests and provide feedback on proposed
|
||||
changes.
|
||||
|
||||
Automation assigns reviewers to pull requests, and contributors 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
|
||||
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`.
|
||||
|
||||
For a trivial change or one that needs no technical review, the SIG Docs
|
||||
[approver](#approvers) can provide the `/lgtm` as well.
|
||||
|
||||
A `/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).
|
||||
|
||||
### 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.
|
||||
|
||||
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).
|
||||
|
||||
#### PR Wrangler
|
||||
|
||||
SIG Docs approvers are added to the
|
||||
[PR Wrangler rotation scheduler](https://github.com/kubernetes/website/wiki/PR-Wranglers)
|
||||
for weekly rotations. All SIG Docs approvers are expected to take part 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
|
||||
|
||||
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
|
||||
the Kubernetes organization. They require extensive knowledge of the structure
|
||||
of the Kubernetes project as a whole and how SIG Docs works within it. See
|
||||
[Leadership](https://github.com/kubernetes/community/tree/master/sig-docs#leadership)
|
||||
for the current list of chairpersons.
|
||||
|
||||
|
||||
|
||||
## SIG Docs teams and automation
|
||||
|
||||
Automation in SIG Docs relies on two different mechanisms for automation:
|
||||
Github groups and OWNERS files.
|
||||
|
||||
### Github groups
|
||||
|
||||
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)
|
||||
|
||||
Each 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 OWNERS files.
|
||||
|
||||
### OWNERS files and front-matter
|
||||
|
||||
The Kubernetes project uses an automation tool called prow for automation
|
||||
related to Github issues and pull requests. The
|
||||
[Kubernetes website repository](https://github.com/kubernetes/website) uses
|
||||
two [prow plugins](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_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS_ALIASES)
|
||||
files in the top level of the `kubernetes/website` Github repository to control
|
||||
how prow works within the repository.
|
||||
|
||||
An OWNERS file contains a list of people who are SIG Docs reviewers and
|
||||
approvers. OWNERS files can also exist in subdirectories, and can override who
|
||||
can act as a reviewer or approver of files in that subdirectory and its
|
||||
descendents. For more information about OWNERS files in general, see
|
||||
[OWNERS](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md).
|
||||
|
||||
In addition, an individual Markdown file can list reviewers and approvers in its
|
||||
front-matter, either by listing individual Github usernames or Github groups.
|
||||
|
||||
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.
|
||||
|
||||
## Become a reviewer or approver
|
||||
|
||||
To volunteer as a reviewer or approver, make sure you
|
||||
[meet the general requirements](https://github.com/kubernetes/community/blob/master/community-membership.md#membership)
|
||||
and the [requirements for SIG Docs](#become-a-reviewer-or-approver). Your
|
||||
SIG Docs sponsor adds you to the appropriate Github groups and OWNERS files
|
||||
after your status as a reviewer or approver is approved by the SIG.
|
||||
|
||||
| Role | SIG Docs prerequisites | Responsibilities |
|
||||
|------------------------|---------------------------------------------------|-----------------------------------------------------------|
|
||||
| [Member](#members) | Sign the CLA | Follow the [Code of Conduct](/community/#code-of-conduct) |
|
||||
| [Reviewer](#reviewers) | Regularly participate in weekly SIG Docs meetings | Review PRs auto-assigned by blunderbuss within 1 week |
|
||||
| [Approver](#approvers) | <ul><li>Contribute regularly as a reviewer for at least 3 months</li><li>Understand SIG Docs workflows and tooling</li></ul> | <ul><li>Respond to PR comments/requests for review from other maintainers within 1 week</li><li>Serve periodically as the PR Wrangler for SIG Docs</li></ul> |
|
||||
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
For more information about contributing to the Kubernetes documentation, see:
|
||||
|
||||
- [Start contributing](/docs/contribute/start/)
|
||||
- [Documentation style](/docs/contribute/style/)
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,355 @@
|
|||
---
|
||||
title: Start contributing
|
||||
slug: start
|
||||
content_template: templates/concept
|
||||
weight: 10
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
If you want to get started contributing to the Kubernetes documentation, this
|
||||
page and its linked topics can help you get started. You don't need to be a
|
||||
developer or a technical writer to make a big impact on the Kubernetes
|
||||
documentation and user experience! All you need for the topics on this page is
|
||||
a [Github account](https://github.com/join) and a web browser.
|
||||
|
||||
If you're looking for information on how to start contributing to Kubernetes
|
||||
code repositories, refer to
|
||||
[the Kubernetes community guidelines](https://github.com/kubernetes/community/blob/master/governance.md).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
## The basics about our docs
|
||||
|
||||
The Kubernetes documentation is written in Markdown and processed and deployed
|
||||
using Hugo. The source is in Github at
|
||||
[https://github.com/kubernetes/website](https://github.com/kubernetes/website).
|
||||
Most of the documentation source is stored in `/content/en/docs/`. Some of the
|
||||
reference documentation is automatically generated from scripts, mostly in the
|
||||
`/content/en/docs/imported/` subdirectory.
|
||||
|
||||
You can file issues, edit content, and review changes from others, all from the
|
||||
Github website. You can also use Github's embedded history and search tools.
|
||||
|
||||
Not all tasks can be done in the Github UI, but these are discussed in the
|
||||
[intermediate](/docs/contribute/intermediate/) and
|
||||
[advanced](/docs/contribute/advanced/) docs contribution guides.
|
||||
|
||||
### Participating in SIG Docs
|
||||
|
||||
The Kubernetes documentation is maintained by a special interest group (SIG)
|
||||
called Sig Docs. We communicate using a Slack channel, a mailing list, and
|
||||
weekly video meetings. New participants are welcome. For more information, see
|
||||
[Participating in SIG Docs](/docs/contribute/participating/).
|
||||
|
||||
### Style guidelines
|
||||
|
||||
We maintain a [style guide](/docs/contribute/style/style-guide/) with information
|
||||
about choices the SIG Docs community has made about grammar, syntax, source
|
||||
formatting, and typographic conventions. Look over the style guide before you
|
||||
make your first contribution, and use it when you have questions.
|
||||
|
||||
Changes to the style guide are made by SIG Docs as a group. To propose a change
|
||||
or addition, [add it to the agenda](https://docs.google.com/document/d/1Ds87eRiNZeXwRBEbFr6Z7ukjbTow5RQcNZLaSvWWQsE/edit#) for an upcoming SIG Docs meeting, and attend the meeting to participate in the
|
||||
discussion. See the [advanced contribution](advanced.md) topic for more
|
||||
information.
|
||||
|
||||
### Page templates
|
||||
|
||||
We use page templates to control the presentation of our documentation pages.
|
||||
Be sure to understand how these templates work by reviewing
|
||||
[Using page templates](/docs/contribute/style/page-templates/).
|
||||
|
||||
### Hugo shortcodes
|
||||
|
||||
The Kubernetes documentation is transformed from Markdown to HTML using Hugo.
|
||||
We make use of the standard Hugo shortcodes, as well as a few that are custom to
|
||||
the Kubernetes documentation. See [Custom Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/) for
|
||||
information about how to use them.
|
||||
|
||||
## File actionable issues
|
||||
|
||||
Anyone with a Github account can file an issue (bug report) against the
|
||||
Kubernetes documentation. If you see something wrong, even if you have no idea
|
||||
how to fix it, [file an issue](#how-to-file-an-issue). The exception to this
|
||||
rule is a tiny bug like a typo that you intend to fix yourself. In that case,
|
||||
you can instead [fix it](#fix-it) without filing a bug first.
|
||||
|
||||
### How to file an issue
|
||||
|
||||
- **On an existing page**
|
||||
|
||||
If you see a problem in an existing page in the [Kubernetes docs](/docs/),
|
||||
go to the bottom of the page and click the **Create an Issue** button. If
|
||||
you are not currently logged in to Github, log in. A Github issue form
|
||||
appears with some pre-populated content.
|
||||
|
||||
Using Markdown, fill in as many details as you can. In places where you see
|
||||
empty square brackets (`[ ]`), put an `x` between the set of brackets that
|
||||
represents the appropriate choice. If you have a proposed solution to fix
|
||||
the issue, add it.
|
||||
|
||||
- **Request a new page**
|
||||
|
||||
If you think content should exist, but you aren't sure where it should go or
|
||||
you don't think it fits within the pages that currently exist, you can
|
||||
still file an issue. You can either choose an existing page near where you think the
|
||||
new content should go and file the issue from that page, or go straight to
|
||||
[https://github.com/kubernetes/website/issues/new/](https://github.com/kubernetes/website/issues/new/)
|
||||
and file the issue from there.
|
||||
|
||||
### How to file great issues
|
||||
|
||||
To ensure that we understand your issue and can act on it, keep these guidelines
|
||||
in mind:
|
||||
|
||||
- Use the issue template, and fill out as many details as you can.
|
||||
- Clearly explain the specific impact the issue has on users.
|
||||
- Limit the scope of a given issue to a reasonable unit of work. For problems
|
||||
with a large scope, break them down into smaller issues.
|
||||
|
||||
For instance, "Fix the security docs" is not an actionable issue, but "Add
|
||||
details to the 'Restricting network access' topic" might be.
|
||||
- If the issue relates to another issue or pull request, you can refer to it
|
||||
either by its full URL or by the the issue or pull request number prefixed
|
||||
with a `#` character. For instance, `Introduced by #987654`.
|
||||
- Be respectful and avoid venting. For instance, "The docs about X suck" is not
|
||||
helpful or actionable feedback. The
|
||||
[Code of Conduct](/community/code-of-conduct/) also applies to interactions on
|
||||
Kubernetes Github repositories.
|
||||
|
||||
## Participate in SIG Docs discussions
|
||||
|
||||
The SIG Docs team communicates using the following mechanisms:
|
||||
|
||||
- [Join the Kubernetes Slack instance](http://slack.k8s.io/), then join the
|
||||
`#sig-docs` channel, where we discuss docs issues in real-time. Be sure to
|
||||
introduce yourself!
|
||||
- [Join the `kubernetes-sig-docs` mailing list](https://groups.google.com/forum/#!forum/kubernetes-sig-docs),
|
||||
where broader discussions take place and official decisions are recorded.
|
||||
- Participate in the weekly SIG Docs video meeting, which is announced on the
|
||||
Slack channel and the mailing list. Currently, these meetings take place on
|
||||
Zoom, so you'll need to download the [Zoom client](https://zoom.us/download)
|
||||
or dial in using a phone.
|
||||
|
||||
## Improve existing content
|
||||
|
||||
To improve existing content, you file a _pull request (PR)_ after creating a
|
||||
_fork_. Those two terms are [specific to Github](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/).
|
||||
For the purposes of this topic, you don't need to know everything about them,
|
||||
because you can do everything using your web browser. When you continue to the
|
||||
[intermediate docs contributor guide](/docs/contribute/intermediate/), you will
|
||||
need more background in Git terminology.
|
||||
|
||||
{{< note >}}
|
||||
**Kubnetes code developers**: If you are documenting a new feature for an
|
||||
upcoming Kubernetes release, your process is a bit different. See
|
||||
[Document a feature](/docs/contribute/intermediate.md#sig-members-documenting-new-features) for
|
||||
process guidelines and information about deadlines.
|
||||
{{< /note >}}
|
||||
|
||||
### Sign the CLA
|
||||
|
||||
Before you can contribute code or documentation to Kubernetes, you **must** read
|
||||
the [Contributor guide](/docs/imported/community/guide/) and
|
||||
[sign the Contributor License Agreement (CLA)](/docs/imported/community/guide/#sign-the-cla).
|
||||
Don't worry -- this doesn't take long!
|
||||
|
||||
### Find something to work on
|
||||
|
||||
If you see something you want to fix right away, just follow the instructions
|
||||
below. You don't need to [file an issue](#file-actionable-issues) (although you
|
||||
certainly can).
|
||||
|
||||
If you want to start by finding an existing issue to work on, go to
|
||||
[https://github.com/kubernetes/website/issues](https://github.com/kubernetes/website/issues)
|
||||
and look for issues with the label `good first issue` (you can use
|
||||
[this](https://github.com/kubernetes/website/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) shortcut). Read through the comments and make sure there is not an open pull
|
||||
request against the issue and that nobody has left a comment saying they are
|
||||
working on the issue recently (3 days is a good rule). Leave a comment saying
|
||||
that you would like to work on the issue.
|
||||
|
||||
### Choose which Git branch to use
|
||||
|
||||
The most important aspect of submitting pull requests is choosing which branch
|
||||
to base your work on. Use these guidelines to make the decision:
|
||||
|
||||
- Use `master` for fixing problems in content that is already published, or
|
||||
making improvements to content that already exists.
|
||||
- Use a release branch (such as `release-1.12`) to document upcoming features
|
||||
or changes for an upcoming release that is not yet published.
|
||||
- Use a feature branch that has been agreed upon by SIG Docs to collaborate on
|
||||
big improvements or changes to the existing documentation, including content
|
||||
reorganization or changes to the look and feel of the website.
|
||||
|
||||
If you're still not sure which branch to choose, ask in `#sig-docs` on Slack or
|
||||
attend a weekly SIG Docs meeting to get clarity.
|
||||
|
||||
### Submit a pull request
|
||||
|
||||
Follow these steps to submit a pull request to improve the Kubernetes
|
||||
documentation.
|
||||
|
||||
1. On the page where you see the issue, click the pencil icon at the top left.
|
||||
A new page appears, with some help text.
|
||||
2. Click the first blue button, which has the text **Edit <page name>**.
|
||||
|
||||
If you have never created a fork of the Kubernetes documentation
|
||||
repository, you are prompted to do so. Create the fork under your Github
|
||||
username, rather than another organization you may be a member of. The
|
||||
fork usually has a URL such as `https://github.com/<username>/website`,
|
||||
unless you already have a repository with a conflicting name.
|
||||
|
||||
The reason you are prompted to create a fork is that you do not have
|
||||
access to push a branch directly to the definitive Kubernetes repository.
|
||||
|
||||
3. The Github Markdown editor appears with the source Markdown file loaded.
|
||||
Make your changes. Below the editor, fill in the **Propose file change**
|
||||
form. The first field is the summary of your commit message and should be
|
||||
no more than 50 characters long. The second field is optional, but can
|
||||
include more detail if appropriate.
|
||||
|
||||
{{< note >}}
|
||||
**Note**: Do not include references to other Github issues or pull
|
||||
requests in your commit message. You can add those to the pull request
|
||||
description later.
|
||||
{{< /note >}}
|
||||
|
||||
Click **Propose file change**. The change is saved as a commit in a
|
||||
new branch in your fork, which is automatically named something like
|
||||
`patch-1`.
|
||||
|
||||
4. The next screen summarizes the changes you made, by comparing your new
|
||||
branch (the **head fork** and **compare** selection boxes) to the current
|
||||
state of the **base fork** and **base** branch (`master` on the
|
||||
`kubernetes/website` repository by default). You can change any of the
|
||||
selection boxes, but don't do that now. Have a look at the difference
|
||||
viewer on the bottom of the screen, and if everything looks right, click
|
||||
**Create pull request**.
|
||||
|
||||
{{< note >}}
|
||||
**Note**: If you don't want to create the pull request now, you can do it
|
||||
later, by browsing to the main URL of the Kubernetes website repository or
|
||||
your fork's repository. The Github website will prompt you to create the
|
||||
pull request if it detects that you pushed a new branch to your fork.
|
||||
{{< /note >}}
|
||||
|
||||
5. The **Open a pull request** screen appears. The subject of the pull request
|
||||
is the same as the commit summary, but you can change it if needed. The
|
||||
body is populated by your extended commit message (if present) and some
|
||||
template text. Read the template text and fill out the details it asks for,
|
||||
then delete the extra template text. Leave the
|
||||
**Allow edits from maintainers** checkbox selected. Click
|
||||
**Create pull request**.
|
||||
|
||||
Congratulations! Your pull request is available in
|
||||
Pull requests](https://github.com/kubernetes/website/pulls).
|
||||
|
||||
After a few minutes, you can preview the website with your PR's changes
|
||||
applied. Go to the **Conversation** tab of your PR and click the **Details**
|
||||
link for the `deploy/netlify` test, near the bottom of the page. It opens in
|
||||
the same browser window by default.
|
||||
|
||||
6. Wait for review. Generally, reviewers are suggested by the `k8s-ci-robot`.
|
||||
If a reviewer asks you to make changes, you can go to the **Files changed**
|
||||
tab and click the pencil icon on any files that have been changed by the
|
||||
pull request. When you save the changed file, a new commit is created in
|
||||
the branch being monitored by the pull request.
|
||||
|
||||
7. If your change is accepted, a reviewer merges your pull request, and the
|
||||
change is live on the Kubernetes website a few minutes later.
|
||||
|
||||
This is only one way to submit a pull request. If you are already a Git and
|
||||
Github advanced user, you can use a local GUI or command-line Git client
|
||||
instead of using the Github UI. Some basics about using the command-line Git
|
||||
client are discussed in the [intermediate](/docs/contribute/intermediate/) docs
|
||||
contribution guide.
|
||||
|
||||
## Review docs pull requests
|
||||
|
||||
People who are not yet approvers or reviewers can still review pull requests.
|
||||
The reviews are not considered "binding", which means that your review alone
|
||||
won't cause a pull request to be merged. However, it can still be helpful. Even
|
||||
if you don't leave any review comments, you can get a sense of pull request
|
||||
conventions and etiquette and get used to the workflow.
|
||||
|
||||
1. Go to
|
||||
[https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls).
|
||||
You see a list of every open pull request against the Kubernetes website and
|
||||
docs.
|
||||
|
||||
2. By default, the only filter that is applied is `open`, so you don't see
|
||||
pull requests that have already been closed or merged. It's a good idea to
|
||||
apply the `cncf-cla: yes` filter, and for your first review, it's a good
|
||||
idea to add `size/S` or `size/XS`. The `size` label is applied automatically
|
||||
based on how many lines of code the PR modifies. You can apply filters using
|
||||
the selection boxes at the top of the page, or use
|
||||
[this shortcut](https://github.com/kubernetes/website/pulls?q=is%3Aopen+is%3Apr+label%3A%22cncf-cla%3A+yes%22+label%3Asize%2FS) for only small PRs. All filters are `AND`ed together, so
|
||||
you can't search for both `size/XS` and `size/S` in the same query.
|
||||
|
||||
3. Go to the **Files changed** tab. Look through the changes introduced in the
|
||||
PR, and if applicable, also look at any linked issues. If you see a problem
|
||||
or room for improvement, hover over the line and click the `+` symbol that
|
||||
appears.
|
||||
|
||||
You can type a comment, and either choose **Add single comment** or **Start
|
||||
a review**. Typically, starting a review is better because it allows you to
|
||||
leave multiple comments and notifies the PR owner only when you have
|
||||
completed the review, rather than a separate notification for each comment.
|
||||
|
||||
4. When finished, click **Review changes** at the top of the page. You can
|
||||
summarize your review, and you can choose to comment, approve, or request
|
||||
changes. New contributors should always choose **Comment**.
|
||||
|
||||
Thanks for reviewing a pull request! When you are new to the project, it's a
|
||||
good idea to ask for feedback on your pull request reviews. The `#sig-docs`
|
||||
Slack channel is a great place to do this.
|
||||
|
||||
## Write a blog post
|
||||
|
||||
Anyone can write a blog post and submit it for review. Blog posts should not be
|
||||
commercial in nature and should consist of content that will apply broadly to
|
||||
the Kubernetes community.
|
||||
|
||||
To submit a blog post, you can either submit it using the
|
||||
[Kubernetes blog submission form](https://docs.google.com/forms/d/e/1FAIpQLSch_phFYMTYlrTDuYziURP6nLMijoXx_f7sLABEU5gWBtxJHQ/viewform),
|
||||
or follow the steps below.
|
||||
|
||||
1. [Sign the CLA](#sign-the-cla) if you have not yet done so.
|
||||
2. Have a look at the Markdown format for existing blog posts in the
|
||||
[website repository](https://github.com/kubernetes/website/tree/master/content/en/blog/_posts).
|
||||
3. Write out your blog post in a text editor of your choice.
|
||||
4. On the same link from step 2, click the **Create new file** button. Paste
|
||||
your content into the editor. Name the file to match the proposed title of
|
||||
the blog post, but don't put the date in the file name. The blog reviewers
|
||||
will work with you on the final file name and the date the blog will be
|
||||
published.
|
||||
5. When you save the file, Github will walk you through the pull request
|
||||
process.
|
||||
6. A blog post reviewer will review your submission and work with you on
|
||||
feedback and final details. When the blog post is approved, the blog will be
|
||||
scheduled for publication.
|
||||
|
||||
## Submit a case study
|
||||
|
||||
Case studies highlight how organizations are using Kubernetes to solve
|
||||
real-world problems. They are written in collaboration with the Kubernetes
|
||||
marketing team, which is handled by the CNCF.
|
||||
|
||||
Have a look at the source for the
|
||||
[existing case studies](https://github.com/kubernetes/website/tree/master/content/en/case-studies).
|
||||
Use the [Kubernetes case study submission form](https://www.cncf.io/people/end-user-community/)
|
||||
to submit your proposal.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
When you are comfortable with all of the tasks discussed in this topic and you
|
||||
want to engage with the Kubernetes docs team in deeper ways, read the
|
||||
[intermediate docs contribution guide](/docs/contribute/intermediate/).
|
||||
|
||||
{{% /capture %}}
|
||||
|
|
@ -0,0 +1,9 @@
|
|||
---
|
||||
title: Documentation style overview
|
||||
main_menu: true
|
||||
weight: 80
|
||||
---
|
||||
|
||||
The topics in this section provide guidance on writing style, content formatting
|
||||
and organization, and using Hugo customizations specific to Kubernetes
|
||||
documentation.
|
||||
|
|
@ -1,8 +1,7 @@
|
|||
---
|
||||
title: Content Organization
|
||||
date: 2018-04-30
|
||||
title: Content organization
|
||||
content_template: templates/concept
|
||||
weight: 42
|
||||
weight: 40
|
||||
---
|
||||
|
||||
{{< toc >}}
|
||||
|
|
@ -135,8 +134,8 @@ The `SASS` source of the stylesheets for this site is stored below `src/sass` an
|
|||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
* [Custom Hugo Shortcodes](/docs/home/contribute/includes)
|
||||
* [Style Guide](/docs/home/contribute/style-guide)
|
||||
* [Custom Hugo shortcodes](/docs/contribute/style/hugo_shortcodes)
|
||||
* [Style guide](/docs/contribute/style/style-guide)
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
|
@ -0,0 +1,239 @@
|
|||
---
|
||||
title: Using Page Templates
|
||||
content_template: templates/concept
|
||||
weight: 30
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
When contributing new topics, apply one of the following templates to them.
|
||||
This standardizes the user experience of a given page.
|
||||
|
||||
The page templates are in the
|
||||
[`_includes/templates`](https://git.k8s.io/website/_includes/templates)
|
||||
directory of the [`kubernetes/website`](https://github.com/kubernetes/website)
|
||||
repository.
|
||||
|
||||
{{< note >}}
|
||||
**Note**: Every new topic needs to use a template. If you are unsure which
|
||||
template to use for a new topic, start with the
|
||||
[concept template](#concept-template).
|
||||
{{< /note >}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
## Concept template
|
||||
|
||||
A concept page explains some aspect of Kubernetes. For example, a concept
|
||||
page might describe the Kubernetes Deployment object and explain the role it
|
||||
plays as an application is deployed, scaled, and updated. Typically, concept
|
||||
pages don't include sequences of steps, but instead provide links to tasks or
|
||||
tutorials.
|
||||
|
||||
|
||||
To write a new concept page, create a Markdown file in a subdirectory of the
|
||||
`/content/en/docs/concepts` directory, with the following characteristics:
|
||||
|
||||
- In the page's YAML front-matter, set `content_template: templates/concept`.
|
||||
- In the page's body, set the required `capture` variables and any optional
|
||||
ones you want to include:
|
||||
|
||||
| Variable | Required? |
|
||||
|===============|===========|
|
||||
| overview | yes |
|
||||
| body | yes |
|
||||
| whatsnext | no |
|
||||
|
||||
The page's body will look like this (remove any optional captures you don't
|
||||
need):
|
||||
|
||||
```
|
||||
{% raw %}
|
||||
{{% capture overview %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
{{% /capture %}}
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
- Within each section, write your content. Use the following guidelines:
|
||||
- Use a minimum of H2 headings (with two leading `#` characters). The sections
|
||||
themselves are titled automatically by the template.
|
||||
- For `overview`, use a paragraph to set context for the entire topic.
|
||||
- Add the `{{< toc >}}` shortcode to show an in-page table of contents.
|
||||
- For `body`, explain the concept using free-form Markdown.
|
||||
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
|
||||
interested in reading next.
|
||||
|
||||
An example of a published topic that uses the concept template is
|
||||
[Annotations](/docs/concepts/overview/working-with-objects/annotations/). The
|
||||
page you are currently reading also uses the content template.
|
||||
|
||||
## Task template
|
||||
|
||||
A task page shows how to do a single thing, typically by giving a short
|
||||
sequence of steps. Task pages have minimal explanation, but often provide links
|
||||
to conceptual topics that provide related background and knowledge.
|
||||
|
||||
To write a new task page, create a Markdown file in a subdirectory of the
|
||||
`/content/en/docs/tasks` directory, with the following characteristics:
|
||||
|
||||
- In the page's YAML front-matter, set `content_template: templates/task`.
|
||||
- In the page's body, set the required `capture` variables and any optional
|
||||
ones you want to include:
|
||||
|
||||
| Variable | Required? |
|
||||
|===============|===========|
|
||||
| overview | yes |
|
||||
| prerequisites | yes |
|
||||
| steps | no |
|
||||
| discussion | no |
|
||||
| whatsnext | no |
|
||||
|
||||
The page's body will look like this (remove any optional captures you don't
|
||||
need):
|
||||
|
||||
```
|
||||
{% raw %}
|
||||
{{% capture overview %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
|
||||
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture discussion %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
{{% /capture %}}
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
- Within each section, write your content. Use the following guidelines:
|
||||
- Use a minimum of H2 headings (with two leading `#` characters). The sections
|
||||
themselves are titled automatically by the template.
|
||||
- For `overview`, use a paragraph to set context for the entire topic.
|
||||
- Add the `{{< toc >}}` shortcode to show an in-page table of contents.
|
||||
- For `prerequisites`, use bullet lists when possible. Add additional
|
||||
prerequisites below the ones included by the `include` in the example
|
||||
above. The default prerequisites include a running Kubernetes cluster.
|
||||
- For `steps`, use numbered lists.
|
||||
- For discussion, use normal content to expand upon the information covered
|
||||
in `steps`.
|
||||
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
|
||||
interested in reading next.
|
||||
|
||||
An example of a published topic that uses the task template is [Using an HTTP proxy to access the Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api).
|
||||
|
||||
## Tutorial template
|
||||
|
||||
A tutorial page shows how to accomplish a goal that is larger than a single
|
||||
task. Typically a tutorial page has several sections, each of which has a
|
||||
sequence of steps. For example, a tutorial might provide a walkthrough of a
|
||||
code sample that illustrates a certain feature of Kubernetes. Tutorials can
|
||||
include surface-level explanations, but should link to related concept topics
|
||||
for deep explanations.
|
||||
|
||||
To write a new tutorial page, create a Markdown file in a subdirectory of the
|
||||
`/content/en/docs/tutorials` directory, with the following characteristics:
|
||||
|
||||
- In the page's YAML front-matter, set `content_template: templates/tutorial`.
|
||||
- In the page's body, set the required `capture` variables and any optional
|
||||
ones you want to include:
|
||||
|
||||
| Variable | Required? |
|
||||
|===============|===========|
|
||||
| overview | yes |
|
||||
| prerequisites | yes |
|
||||
| objectives | yes |
|
||||
| lessoncontent | yes |
|
||||
| cleanup | no |
|
||||
| whatsnext | no |
|
||||
|
||||
The page's body will look like this (remove any optional captures you don't
|
||||
need):
|
||||
|
||||
```
|
||||
{% raw %}
|
||||
{{% capture overview %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{< toc >}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
|
||||
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture objectives %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture lessoncontent %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture cleanup %}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
{{% /capture %}}
|
||||
{% endraw %}
|
||||
```
|
||||
|
||||
- Within each section, write your content. Use the following guidelines:
|
||||
- Use a minimum of H2 headings (with two leading `#` characters). The sections
|
||||
themselves are titled automatically by the template.
|
||||
- For `overview`, use a paragraph to set context for the entire topic.
|
||||
- Add the `{{< toc >}}` shortcode to show an in-page table of contents.
|
||||
- For `prerequisites`, use bullet lists when possible. Add additional
|
||||
prerequisites below the ones included by default.
|
||||
- For `objectives`, use bullet lists.
|
||||
- For `lessoncontent`, use a mix of numbered lists and narrative content as
|
||||
appropriate.
|
||||
- For `cleanup`, use numbered lists to describe the steps to clean up the
|
||||
state of the cluster after finishing the task.
|
||||
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
|
||||
interested in reading next.
|
||||
|
||||
An example of a published topic that uses the tutorial template is
|
||||
[Running a Stateless Application Using a Deployment](/docs/tutorials/stateless-application/run-stateless-application-deployment/).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
- Learn about the [style guide](/docs/contribute/style/style-guide/)
|
||||
- Learn about [content organization](/docs/contribute/style/content-organization/)
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
|
@ -1,10 +1,10 @@
|
|||
---
|
||||
title: Documentation Style Guide
|
||||
linktitle: Style guide
|
||||
content_template: templates/concept
|
||||
weight: 10
|
||||
---
|
||||
|
||||
|
||||
|
||||
{{% capture overview %}}
|
||||
This page gives writing style guidelines for the Kubernetes documentation.
|
||||
These are guidelines, not rules. Use your best judgment, and feel free to
|
||||
|
|
@ -12,14 +12,15 @@ propose changes to this document in a pull request.
|
|||
|
||||
For additional information on creating new content for the Kubernetes
|
||||
docs, follow the instructions on
|
||||
[using page templates](/docs/home/contribute/page-templates/) and
|
||||
[creating a documentation pull request](/docs/home/contribute/create-pull-request/).
|
||||
[using page templates](/docs/contribute/style/page-templates/) and
|
||||
[creating a documentation pull request](/docs/contribute/start/#improve-existing-content).
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
{{< note >}}
|
||||
**Note:** Kubernetes documentation uses [Blackfriday Markdown Renderer](https://github.com/russross/blackfriday) along with a few [Hugo Shortcodes](/docs/home/contribute/includes/) to support glossary entries, tabs, and representing feature state.
|
||||
**Note:** Kubernetes documentation uses [Blackfriday Markdown Renderer](https://github.com/russross/blackfriday) along with a few [Hugo Shortcodes](/docs/home/contribute/includes/) to support glossary entries, tabs,
|
||||
and representing feature state.
|
||||
{{< /note >}}
|
||||
|
||||
## Language
|
||||
|
|
@ -83,7 +84,7 @@ represents.
|
|||
<tr><th>Do</th><th>Don't</th></tr>
|
||||
<tr><td>Open the <code>envars.yaml</code> file.</td><td>Open the envars.yaml file.</td></tr>
|
||||
<tr><td>Go to the <code>/docs/tutorials</code> directory.</td><td>Go to the /docs/tutorials directory.</td></tr>
|
||||
<tr><td>Open the <code>/_data/concepts.yaml</code> file.</td><td>Open the /_data/concepts.yaml file.</td></tr>
|
||||
<tr><td>Open the <code>/_data/concepts.yaml</code><!--to-unbreak-atom-highlighting_--> file.</td><td>Open the /_data/concepts.yaml<!--to-unbreak-atom-highlighting_--> file.</td></tr>
|
||||
</table>
|
||||
|
||||
### Use the international standard for punctuation inside quotes
|
||||
|
|
@ -1,6 +1,7 @@
|
|||
---
|
||||
title: Writing a New Topic
|
||||
title: Writing a new topic
|
||||
content_template: templates/task
|
||||
weight: 20
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
|
@ -9,7 +10,7 @@ This page shows how to create a new topic for the Kubernetes docs.
|
|||
|
||||
{{% capture prerequisites %}}
|
||||
Create a fork of the Kubernetes documentation repository as described in
|
||||
[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/).
|
||||
[Start contributing](/docs/contribute/start/).
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
|
|
@ -21,6 +22,11 @@ is the best fit for your content:
|
|||
|
||||
<table>
|
||||
|
||||
<tr>
|
||||
<td>Concept</td>
|
||||
<td>A concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials. For an example of a concept topic, see <a href="/docs/concepts/architecture/nodes/">Nodes</a>.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Task</td>
|
||||
<td>A task page shows how to do a single thing. The idea is to give readers a sequence of steps that they can actually do as they read the page. A task page can be short or long, provided it stays focused on one area. In a task page, it is OK to blend brief explanations with the steps to be performed, but if you need to provide a lengthy explanation, you should do that in a concept topic. Related task and concept topics should link to each other. For an example of a short task page, see <a href="/docs/tasks/configure-pod-container/configure-volume-storage/">Configure a Pod to Use a Volume for Storage</a>. For an example of a longer task page, see <a href="/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/">Configure Liveness and Readiness Probes</a></td>
|
||||
|
|
@ -31,17 +37,12 @@ is the best fit for your content:
|
|||
<td>A tutorial page shows how to accomplish a goal that ties together several Kubernetes features. A tutorial might provide several sequences of steps that readers can actually do as they read the page. Or it might provide explanations of related pieces of code. For example, a tutorial could provide a walkthrough of a code sample. A tutorial can include brief explanations of the Kubernetes features that are being tied together, but should link to related concept topics for deep explanations of individual features.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Concept</td>
|
||||
<td>A concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials. For an example of a concept topic, see <a href="/docs/concepts/architecture/nodes/">Nodes</a>.</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
Each page type has a
|
||||
[template](/docs/home/contribute/page-templates/)
|
||||
that you can use as you write your topic.
|
||||
Using templates helps ensure consistency among topics of a given type.
|
||||
Use a template for each new page. Each page type has a
|
||||
[template](/docs/contribute/style/page-templates/)
|
||||
that you can use as you write your topic. Using templates helps ensure
|
||||
consistency among topics of a given type.
|
||||
|
||||
## Choosing a title and filename
|
||||
|
||||
|
|
@ -70,24 +71,29 @@ triple-dashed lines at the top of the page. Here's an example:
|
|||
|
||||
Depending on your page type, put your new file in a subdirectory of one of these:
|
||||
|
||||
* /docs/tasks/
|
||||
* /docs/tutorials/
|
||||
* /docs/concepts/
|
||||
* /content/en/docs/tasks/
|
||||
* /content/en/docs/tutorials/
|
||||
* /content/en/docs/concepts/
|
||||
|
||||
You can put your file in an existing subdirectory, or you can create a new
|
||||
subdirectory.
|
||||
|
||||
## Creating an entry in the table of contents
|
||||
## Placing your topic in the table of contents
|
||||
|
||||
Depending page type, create an entry in one of these files:
|
||||
The table of contents is built dynamicaly using the directory structure of the
|
||||
documentation source. The top-level directories under `/content/en/docs/` create
|
||||
top-level navigation, and subdirectories each have entries in the table of
|
||||
contents.
|
||||
|
||||
* /_data/tasks.yaml
|
||||
* /_data/tutorials.yaml
|
||||
* /_data/concepts.yaml
|
||||
Each subdirectory has a file `_index.md`, which represents the "home" page for
|
||||
a given subdirectory's content. The `_index.md` does not need a template. It
|
||||
can contain overview content about the topics in the subdirectory.
|
||||
|
||||
Here's an example of an entry in /_data/tasks.yaml:
|
||||
|
||||
- docs/tasks/configure-pod-container/configure-volume-storage.md
|
||||
Other files in a directory are sorted alphabetically by default. This is almost
|
||||
never the best order. To control the relative sorting of topics in a
|
||||
subdirectory, set the `weight:` front-matter key to an integer. Typically, we
|
||||
use multiples of 10, to account for adding topics later. For instance, a topic
|
||||
with weight `10` will come before one with weight `20`.
|
||||
|
||||
## Embedding code in your topic
|
||||
|
||||
|
|
@ -95,43 +101,51 @@ If you want to include some code in your topic, you can embed the code in your
|
|||
file directly using the markdown code block syntax. This is recommended for the
|
||||
following cases (not an exhaustive list):
|
||||
|
||||
- The code is showing the output from a command such as
|
||||
- The code shows the output from a command such as
|
||||
`kubectl get deploy mydeployment -o json | jq '.status'`.
|
||||
- The code is not generic enough for users to try out. As an example, the YAML
|
||||
- The code is not generic enough for users to try out. As an example, you can
|
||||
embed the YAML
|
||||
file for creating a Pod which depends on a specific
|
||||
[FlexVolume](/docs/concepts/storage/volumes#flexvolume) implementation can be
|
||||
directly embedded into the topic when appropriate.
|
||||
[FlexVolume](/docs/concepts/storage/volumes#flexvolume) implementation.
|
||||
- The code is an incomplete example because its purpose is to highlight a
|
||||
portion of an otherwise large file. For example, when describing ways to
|
||||
portion of a larger file. For example, when describing ways to
|
||||
customize the [PodSecurityPolicy](/docs/tasks/administer-cluster/sysctl-cluster/#podsecuritypolicy)
|
||||
for some reasons, you may provide a short snippet directly in your topic file.
|
||||
for some reasons, you can provide a short snippet directly in your topic file.
|
||||
- The code is not meant for users to try out due to other reasons. For example,
|
||||
when describing how a new attribute should be added to a resource using the
|
||||
`kubectl edit` command, you may provide a short example that includes only
|
||||
`kubectl edit` command, you can provide a short example that includes only
|
||||
the attribute to add.
|
||||
|
||||
## Including code from another file
|
||||
|
||||
Another way to include code in your topic is to create a new, complete sample
|
||||
file (or a group of sample files) and then reference the sample(s) from your
|
||||
topic. This is the preferred way of including sample YAML files when the sample
|
||||
is generic, reusable, and you want the readers to try it out by themselves.
|
||||
file (or group of sample files) and then reference the sample from your topic.
|
||||
Use this method to include sample YAML files when the sample is generic and
|
||||
reusable, and you want the reader to try it out themselves.
|
||||
|
||||
When adding a new standalone sample file (e.g. a YAML file), place the code in
|
||||
When adding a new standalone sample file, such as a YAML file, place the code in
|
||||
one of the `<LANG>/examples/` subdirectories where `<LANG>` is the language for
|
||||
the topic. In your topic file, use the `codenew` shortcode:
|
||||
|
||||
<pre>{{< codenew file="<RELPATH>/my-example-yaml>" >}}</pre>
|
||||
|
||||
where `<RELPATH>` is the path to the file you're including, relative to the
|
||||
`examples` directory. For example, the following short code references a YAML
|
||||
file located at `content/en/examples/pods/storage/gce-volume.yaml`.
|
||||
where `<RELPATH>` is the path to the file to include, relative to the
|
||||
`examples` directory. The following Hugo shortcode references a YAML
|
||||
file located at `/content/en/examples/pods/storage/gce-volume.yaml`.
|
||||
|
||||
<pre>{{< codenew file="pods/storage/gce-volume.yaml" >}}</pre>
|
||||
```none
|
||||
{{</* codenew file="pods/storage/gce-volume.yaml" */>}}
|
||||
```
|
||||
|
||||
{{< note >}}
|
||||
**Note**: To show raw Hugo shortcodes as in the above example and prevent Hugo
|
||||
from interpreting them, use C-style comments directly after the `<` and before
|
||||
the `>` characters. View the code for this page for an example.
|
||||
{{< /note >}}
|
||||
|
||||
## Showing how to create an API object from a configuration file
|
||||
|
||||
If you need to show the reader how to create an API object based on a
|
||||
If you need to demonstrate how to create an API object based on a
|
||||
configuration file, place the configuration file in one of the subdirectories
|
||||
under `<LANG>/examples`.
|
||||
|
||||
|
|
@ -142,7 +156,7 @@ kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml
|
|||
```
|
||||
|
||||
{{< note >}}
|
||||
**NOTE**: When adding new YAML files to the `<LANG>/examples` directory, make
|
||||
**Note**: When adding new YAML files to the `<LANG>/examples` directory, make
|
||||
sure the file is also included into the `<LANG>/examples_test.go` file. The
|
||||
Travis CI for the Website automatically runs this test case when PRs are
|
||||
submitted to ensure all examples pass the tests.
|
||||
|
|
@ -47,5 +47,5 @@ Placeholder text is included.
|
|||
|
||||
1. Develop the snippet locally and verify that it works as expected.
|
||||
2. Copy the template's code into the `atom-snippets.cson` file on Github. Raise a
|
||||
pull request, and ask for review from another Atom user in #sig-docs on
|
||||
pull request, and ask for review from another Atom user in `#sig-docs` on
|
||||
Kubernetes Slack.
|
||||
|
|
@ -1,65 +0,0 @@
|
|||
---
|
||||
layout: docwithnav
|
||||
title: Contributing to the Kubernetes Documentation
|
||||
---
|
||||
|
||||
<!-- BEGIN: Gotta keep this section JS/HTML because it swaps out content dynamically -->
|
||||
<p> </p>
|
||||
<script language="JavaScript">
|
||||
var forwarding=window.location.hash.replace("#","");
|
||||
$( document ).ready(function() {
|
||||
if(forwarding) {
|
||||
$("#generalInstructions").hide();
|
||||
$("#continueEdit").show();
|
||||
$("#continueEditButton").text("Edit " + "content/en/" + forwarding);
|
||||
$("#continueEditButton").attr("href", "https://github.com/kubernetes/website/edit/{{< param "docsbranch" >}}/" + "content/en/" + forwarding)
|
||||
$("#viewOnGithubButton").text("View " + "content/en/" + forwarding + " on GitHub");
|
||||
$("#viewOnGithubButton").attr("href", "https://git.k8s.io/website/" + "content/en/" + forwarding)
|
||||
} else {
|
||||
$("#generalInstructions").show();
|
||||
$("#continueEdit").hide();
|
||||
}
|
||||
});
|
||||
</script>
|
||||
<div id="continueEdit">
|
||||
|
||||
<h2>Continue your edit</h2>
|
||||
|
||||
<p><b>To make changes to the document, do the following:</b></p>
|
||||
|
||||
<ol>
|
||||
<li>Click the button below to edit the page you were just on.</li>
|
||||
<li>Click <b>Commit Changes</b> at the bottom of the screen to create a copy of our site in your GitHub account called a <i>fork</i>.</li>
|
||||
<li>You can make other changes in your fork after it is created, if you want.</li>
|
||||
<li>On the index page, click <b>New Pull Request</b> to let us know about it.</li>
|
||||
</ol>
|
||||
|
||||
<p><a id="continueEditButton" class="button"></a></p>
|
||||
<p><a id="viewOnGithubButton" class="button"></a></p>
|
||||
|
||||
</div>
|
||||
<div id="generalInstructions">
|
||||
|
||||
<h2>Edit our site in the cloud</h2>
|
||||
|
||||
<p>Click the button below to visit the repo for our site. You can then click the <b>Fork</b> button in the upper-right area of the screen to create a copy of our site in your GitHub account called a <i>fork</i>. Make any changes you want in your fork, and when you are ready to send those changes to us, go to the index page for your fork and click <b>New Pull Request</b> to let us know about it.</p>
|
||||
|
||||
<p><a class="button" href="https://github.com/kubernetes/website/">Browse this site's source code</a></p>
|
||||
|
||||
</div>
|
||||
<!-- END: Dynamic section -->
|
||||
|
||||
<br/>
|
||||
|
||||
For more information about contributing to the Kubernetes documentation, see:
|
||||
|
||||
* [Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/)
|
||||
* [Writing a New Topic](/docs/home/contribute/write-new-topic/)
|
||||
* [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/)
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
---
|
||||
title: "Contributing to the Kubernetes Docs"
|
||||
weight: 40
|
||||
---
|
||||
|
||||
|
|
@ -1,134 +0,0 @@
|
|||
---
|
||||
title: Writing a Blog Post
|
||||
reviewers:
|
||||
- zacharysarah
|
||||
- kbarnard10
|
||||
- sarahkconway
|
||||
content_template: templates/task
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
This page shows you how to submit a post for the [Kubernetes Blog](https://kubernetes.io/blog).
|
||||
|
||||
You’ll receive a response within 5 business days on whether your submission is approved and information about next steps, if any.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
To create a new blog post, you can either:
|
||||
|
||||
- Fill out the [Kubernetes Blog Submission](https://docs.google.com/forms/d/e/1FAIpQLSch_phFYMTYlrTDuYziURP6nLMijoXx_f7sLABEU5gWBtxJHQ/viewform) form.
|
||||
|
||||
or:
|
||||
|
||||
- Open a pull request against this repository as described in
|
||||
[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/)
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
## Kubernetes Blog guidelines
|
||||
|
||||
All content must be original. The Kubernetes Blog does not post material previously published elsewhere.
|
||||
|
||||
Suitable Content (with examples):
|
||||
|
||||
- User case studies (Yahoo Japan, Bitmovin)
|
||||
- New Kubernetes capabilities (5-days-of-k8s)
|
||||
- Kubernetes projects updates (kompose)
|
||||
- Updates from Special Interest Groups (SIG-OpenStack)
|
||||
- Tutorials and walkthroughs (PostgreSQL w/ StatefulSets)
|
||||
- Thought leadership around Kubernetes (CaaS, the foundation for next generation PaaS)
|
||||
- Kubernetes Partner OSS integration (Fission)
|
||||
|
||||
Unsuitable Content:
|
||||
|
||||
- Vendor product pitches
|
||||
- Partner updates without an integration and customer story
|
||||
- Syndicated posts (language translations are permitted)
|
||||
|
||||
## Create a blog post with a form
|
||||
|
||||
Open the [Kubernetes Blog Submission](https://docs.google.com/forms/d/e/1FAIpQLSch_phFYMTYlrTDuYziURP6nLMijoXx_f7sLABEU5gWBtxJHQ/viewform) form, fill it out, and click Submit.
|
||||
|
||||
## Create a post by opening a pull request
|
||||
|
||||
### Add a new Markdown file
|
||||
|
||||
Add a new Markdown (`*.md`) to `/blog/_posts/`.
|
||||
|
||||
Name the file using the following format:
|
||||
```
|
||||
YYYY-MM-DD-Title.md
|
||||
```
|
||||
For example:
|
||||
```
|
||||
2015-03-20-Welcome-to-the-Kubernetes-Blog.md
|
||||
```
|
||||
|
||||
### Add front matter to the file
|
||||
|
||||
Add the following block to the top of the new file:
|
||||
```
|
||||
---
|
||||
layout: blog
|
||||
title: <title>
|
||||
date: <date>
|
||||
---
|
||||
```
|
||||
|
||||
For example:
|
||||
```
|
||||
---
|
||||
layout: blog
|
||||
title: Welcome to the Kubernetes Blog!
|
||||
date: Saturday, March 20, 2015
|
||||
---
|
||||
```
|
||||
|
||||
### Create a new pull request (PR)
|
||||
|
||||
When you [create a new pull request](/docs/home/contribute/create-pull-request/), include the following in the PR description:
|
||||
|
||||
{{< note >}}
|
||||
- Desired publishing date
|
||||
**Note:** PRs must include complete drafts no later than 15 days prior to the desired publication date.
|
||||
{{< /note >}}
|
||||
- Author information:
|
||||
- Name
|
||||
- Title
|
||||
- Company
|
||||
- Contact email
|
||||
|
||||
### Add content to the file
|
||||
|
||||
Write your post using the following guidelines.
|
||||
|
||||
### Add images
|
||||
|
||||
Add any image files the post contains to `/static/images/blog/`.
|
||||
|
||||
The preferred image format is SVG.
|
||||
|
||||
Add the proposed date of your blog post to the title of any image files the post contains:
|
||||
```
|
||||
YYYY-MM-DD-image.svg
|
||||
```
|
||||
For example:
|
||||
```
|
||||
2018-03-01-cncf-color.svg
|
||||
```
|
||||
|
||||
Please use [reference-style image links][ref-style] to keep posts readable.
|
||||
|
||||
Here's an example of how to include an image in a blog post:
|
||||
|
||||
```
|
||||
Check out the ![CNCF logo][cncf-logo].
|
||||
|
||||
[cncf-logo]: /images/blog/2018-03-01-cncf-color.svg
|
||||
```
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
|
||||
[ref-style]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#images
|
||||
|
|
@ -1,122 +0,0 @@
|
|||
---
|
||||
title: Creating a Documentation Pull Request
|
||||
content_template: templates/task
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
To contribute to the Kubernetes documentation, create a pull request against the
|
||||
<a href="https://github.com/kubernetes/website" target="_blank" class="_">kubernetes/website</a>
|
||||
repository. This page shows how to create a pull request.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
|
||||
1. Create a <a href="https://github.com/" target="_blank" class="_">Github account</a>.
|
||||
|
||||
1. Sign the
|
||||
<a href="https://identity.linuxfoundation.org/projects/cncf" target="_blank" class="_">Linux Foundation Contributor License Agreement (CLA)</a>.
|
||||
|
||||
Documentation will be published under the [CC BY SA 4.0](https://git.k8s.io/website/LICENSE) license.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture steps %}}
|
||||
|
||||
## Creating a fork of the Kubernetes documentation repository
|
||||
|
||||
1. Go to the
|
||||
<a href="https://github.com/kubernetes/website" target="_blank" class="_">kubernetes/website</a>
|
||||
repository.
|
||||
|
||||
1. In the upper-right corner, click **Fork**. This creates a copy of the
|
||||
Kubernetes documentation repository in your GitHub account. The copy
|
||||
is called a *fork*.
|
||||
|
||||
## Making your changes
|
||||
|
||||
1. In your GitHub account, in your fork of the Kubernetes docs, create
|
||||
a new branch to use for your contribution.
|
||||
|
||||
1. In your new branch, make your changes and commit them. If you want to
|
||||
[write a new topic](/docs/home/contribute/write-new-topic/),
|
||||
choose the
|
||||
[page type](/docs/home/contribute/page-templates/)
|
||||
that is the best fit for your content.
|
||||
|
||||
## Viewing your changes locally
|
||||
|
||||
You can use Hugo to see a preview of your changes locally.
|
||||
|
||||
1. [Install Hugo](https://gohugo.io/getting-started/installing/)
|
||||
version 0.40.3 or later.
|
||||
|
||||
1. Go to the root directory of your clone of the Kubernetes docs, and
|
||||
enter this command:
|
||||
|
||||
hugo server
|
||||
|
||||
1. In your browser's address bar, enter `localhost:1313`.
|
||||
|
||||
## Viewing your changes in the Netlify preview
|
||||
|
||||
When you submit a pull request, you can see a preview of your changes at
|
||||
[Netlify](https://www.netlify.com/). In your pull request, at the bottom,
|
||||
to the right of **deploy/netlify**, click **Details**. Also, there is often
|
||||
a link to the Netlify preview in the pull request comments.
|
||||
|
||||
## Submitting a pull request to the master branch (Current Release)
|
||||
|
||||
If you want your change to be published in the released version Kubernetes docs,
|
||||
create a pull request against the master branch of the Kubernetes
|
||||
documentation repository.
|
||||
|
||||
1. In your GitHub account, in your new branch, create a pull request
|
||||
against the master branch of the kubernetes/website
|
||||
repository. This opens a page that shows the status of your pull request.
|
||||
|
||||
1. Click **Show all checks**. Wait for the **deploy/netlify** check to complete.
|
||||
To the right of **deploy/netlify**, click **Details**. This opens a staging
|
||||
site where you can verify that your changes have rendered correctly.
|
||||
|
||||
1. During the next few days, check your pull request for reviewer comments.
|
||||
If needed, revise your pull request by committing changes to your
|
||||
new branch in your fork.
|
||||
|
||||
## Submitting a pull request to the <vnext> branch (Upcoming Release)
|
||||
|
||||
If your documentation change should not be released until the next release of
|
||||
the Kubernetes product, create a pull request against the <vnext> branch
|
||||
of the Kubernetes documentation repository. The <vnext> branch has the
|
||||
form `release-<version-number>`, for example release-1.5.
|
||||
|
||||
1. In your GitHub account, in your new branch, create a pull request
|
||||
against the <vnext> branch of the kubernetes/website
|
||||
repository. This opens a page that shows the status of your pull request.
|
||||
|
||||
1. Click **Show all checks**. Wait for the **deploy/netlify** check to complete.
|
||||
To the right of **deploy/netlify**, click **Details**. This opens a staging
|
||||
site where you can verify that your changes have rendered correctly.
|
||||
|
||||
1. During the next few days, check your pull request for reviewer comments.
|
||||
If needed, revise your pull request by committing changes to your
|
||||
new branch in your fork.
|
||||
|
||||
The staging site for the upcoming Kubernetes release is here:
|
||||
[http://kubernetes-io-vnext-staging.netlify.com/](http://kubernetes-io-vnext-staging.netlify.com/).
|
||||
The staging site reflects the current state of what's been merged in the
|
||||
release branch, or in other words, what the docs will look like for the
|
||||
next upcoming release. It's automatically updated as new PRs get merged.
|
||||
|
||||
## Pull request review process for both Current and Upcoming Releases
|
||||
Once your pull request is created, a Kubernetes reviewer will take responsibility for providing clear, actionable feedback. As the owner of the pull request, **it is your responsibility to modify your pull request to address the feedback that has been provided to you by the Kubernetes reviewer.** Also note that you may end up having more than one Kubernetes reviewer provide you feedback or you may end up getting feedback from a Kubernetes reviewer that is different than the one originally assigned to provide you feedback. Furthermore, in some cases, one of your reviewers might ask for a technical review from a [Kubernetes tech reviewer](https://github.com/kubernetes/website/wiki/Tech-reviewers) when needed. Reviewers will do their best to provide feedback in a timely fashion but response time can vary based on circumstances.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
* Learn about [writing a new topic](/docs/home/contribute/write-new-topic/).
|
||||
* Learn about [using page templates](/docs/home/contribute/page-templates/).
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
|
|
@ -1,231 +0,0 @@
|
|||
---
|
||||
title: Using Page Templates
|
||||
---
|
||||
|
||||
<!--<html>
|
||||
<body>-->
|
||||
|
||||
<p>These page templates are available for writers who would like to contribute new topics to the Kubernetes docs:</p>
|
||||
|
||||
<ul>
|
||||
<li><a href="#task_template">Task</a></li>
|
||||
<li><a href="#tutorial_template">Tutorial</a></li>
|
||||
<li><a href="#concept_template">Concept</a></li>
|
||||
</ul>
|
||||
|
||||
<p>The page templates are in the <a href="https://git.k8s.io/website/_includes/templates" target="_blank">_includes/templates</a> directory of the <a href="https://github.com/kubernetes/website">website</a> repository.
|
||||
|
||||
<h2 id="task_template">Task template</h2>
|
||||
|
||||
<p>A task page shows how to do a single thing, typically by giving a short
|
||||
sequence of steps. Task pages have minimal explanation, but often provide links
|
||||
to conceptual topics that provide related background and knowledge.</p>
|
||||
|
||||
<p>To write a new task page, create a Markdown file in a subdirectory of the
|
||||
/docs/tasks directory. In your Markdown file, provide values for these
|
||||
variables:</p>
|
||||
|
||||
<ul>
|
||||
<li>overview - required</li>
|
||||
<li>prerequisites - required</li>
|
||||
<li>steps - required</li>
|
||||
<li>discussion - optional</li>
|
||||
<li>whatsnext - optional</li>
|
||||
</ul>
|
||||
|
||||
<p>Then include templates/task.md like this:</p>
|
||||
|
||||
{% raw %}<pre>...
|
||||
{% include templates/task.md %}</pre>{% endraw %}
|
||||
|
||||
<p>In the <code>steps</code> section, use <code>##</code> to start with a level-two heading. For subheadings,
|
||||
use <code>###</code> and <code>####</code> as needed. Similarly, if you choose to have a <code>discussion</code> section,
|
||||
start the section with a level-two heading.</p>
|
||||
|
||||
<p>Here's an example of a Markdown file that uses the task template:</p>
|
||||
|
||||
{% raw %}
|
||||
<pre>---
|
||||
title: Configuring This Thing
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page shows how to ...
|
||||
{% endcapture %}
|
||||
|
||||
{% capture prerequisites %}
|
||||
* Do this.
|
||||
* Do this too.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture steps %}
|
||||
## Doing ...
|
||||
|
||||
1. Do this.
|
||||
1. Do this next. Possibly read this [related explanation](...).
|
||||
{% endcapture %}
|
||||
|
||||
{% capture discussion %}
|
||||
## Understanding ...
|
||||
|
||||
Here's an interesting thing to know about the steps you just did.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn more about [this](...).
|
||||
* See this [related task](...).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/task.md %}</pre>
|
||||
{% endraw %}
|
||||
|
||||
<p>Here's an example of a published topic that uses the task template:</p>
|
||||
|
||||
<p><a href="/docs/tasks/access-kubernetes-api/http-proxy-access-api">Using an HTTP Proxy to Access the Kubernetes API</a></p>
|
||||
|
||||
<h2 id="tutorial_template">Tutorial template</h2>
|
||||
|
||||
<p>A tutorial page shows how to accomplish a goal that is larger than a single
|
||||
task. Typically a tutorial page has several sections, each of which has a
|
||||
sequence of steps. For example, a tutorial might provide a walkthrough of a
|
||||
code sample that illustrates a certain feature of Kubernetes. Tutorials can
|
||||
include surface-level explanations, but should link to related concept topics
|
||||
for deep explanations.
|
||||
|
||||
<p>To write a new tutorial page, create a Markdown file in a subdirectory of the
|
||||
/docs/tutorials directory. In your Markdown file, provide values for these
|
||||
variables:</p>
|
||||
|
||||
<ul>
|
||||
<li>overview - required</li>
|
||||
<li>prerequisites - required</li>
|
||||
<li>objectives - required</li>
|
||||
<li>lessoncontent - required</li>
|
||||
<li>cleanup - optional</li>
|
||||
<li>whatsnext - optional</li>
|
||||
</ul>
|
||||
|
||||
<p>Then include templates/tutorial.md like this:</p>
|
||||
|
||||
{% raw %}<pre>...
|
||||
{% include templates/tutorial.md %}</pre>{% endraw %}
|
||||
|
||||
<p>In the <code>lessoncontent</code> section, use <code>##</code> to start with a level-two heading. For subheadings,
|
||||
use <code>###</code> and <code>####</code> as needed.
|
||||
|
||||
<p>Here's an example of a Markdown file that uses the tutorial template:</p>
|
||||
|
||||
{% raw %}
|
||||
<pre>---
|
||||
title: Running a Thing
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page shows how to ...
|
||||
{% endcapture %}
|
||||
|
||||
{% capture prerequisites %}
|
||||
* Do this.
|
||||
* Do this too.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture objectives %}
|
||||
* Learn this.
|
||||
* Build this.
|
||||
* Run this.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture lessoncontent %}
|
||||
## Building ...
|
||||
|
||||
1. Do this.
|
||||
1. Do this next. Possibly read this [related explanation](...).
|
||||
|
||||
## Running ...
|
||||
|
||||
1. Do this.
|
||||
1. Do this next.
|
||||
|
||||
## Understanding the code
|
||||
Here's something interesting about the code you ran in the preceding steps.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture cleanup %}
|
||||
* Delete this.
|
||||
* Stop this.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn more about [this](...).
|
||||
* See this [related tutorial](...).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/tutorial.md %}</pre>
|
||||
{% endraw %}
|
||||
|
||||
<p>Here's an example of a published topic that uses the tutorial template:</p>
|
||||
|
||||
<p><a href="/docs/tutorials/stateless-application/run-stateless-application-deployment/">Running a Stateless Application Using a Deployment</a></p>
|
||||
|
||||
<h2 id="concept_template">Concept template</h2>
|
||||
|
||||
<p>A concept page explains some aspect of Kubernetes. For example, a concept
|
||||
page might describe the Kubernetes Deployment object and explain the role it
|
||||
plays as an application is deployed, scaled, and updated. Typically, concept
|
||||
pages don't include sequences of steps, but instead provide links to tasks or
|
||||
tutorials.
|
||||
|
||||
<p>To write a new concept page, create a Markdown file in a subdirectory of the
|
||||
/docs/concepts directory. In your Markdown file, provide values for these
|
||||
variables:</p>
|
||||
|
||||
<ul>
|
||||
<li>overview - required</li>
|
||||
<li>body - required</li>
|
||||
<li>whatsnext - optional</li>
|
||||
</ul>
|
||||
|
||||
<p>Then include templates/concept.md like this:</p>
|
||||
|
||||
{% raw %}<pre>...
|
||||
{% include templates/concept.md %}</pre>{% endraw %}
|
||||
|
||||
<p>In the <code>body</code> section, use <code>##</code> to start with a level-two heading. For subheadings,
|
||||
use <code>###</code> and <code>####</code> as needed.
|
||||
|
||||
<p>Here's an example of a page that uses the concept template:</p>
|
||||
|
||||
{% raw %}
|
||||
<pre>---
|
||||
title: Understanding this Thing
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page explains ...
|
||||
{% endcapture %}
|
||||
|
||||
{% capture body %}
|
||||
## Understanding ...
|
||||
|
||||
Kubernetes provides ...
|
||||
|
||||
## Using ...
|
||||
|
||||
To use ...
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn more about [this](...).
|
||||
* See this [related task](...).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/concept.md %}</pre>
|
||||
{% endraw %}
|
||||
|
||||
<p>Here's an example of a published topic that uses the concept template:</p>
|
||||
|
||||
<p><a href="/docs/concepts/overview/working-with-objects/annotations/">Annotations</a></p>
|
||||
|
||||
<!--</body>
|
||||
</html>-->
|
||||
|
||||
|
|
@ -1,114 +0,0 @@
|
|||
---
|
||||
title: Participating in SIG-DOCS
|
||||
content_template: templates/concept
|
||||
---
|
||||
|
||||
{{% 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.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% 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 >}}**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/guide/owners.md).
|
||||
|
||||
{{< note >}}
|
||||
**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/guide/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_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS_ALIASES) files in our repo for configuration.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% 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/)
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
|
|
@ -1,104 +0,0 @@
|
|||
---
|
||||
title: Reviewing Documentation Issues
|
||||
content_template: templates/concept
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
|
||||
This page explains how documentation issues are reviewed and prioritized for the
|
||||
<a href="https://github.com/kubernetes/website" target="_blank" class="_">kubernetes/website</a> repository. The purpose is to provide a way to organize issues and make it easier to contribute to Kubernetes documentation. The following should be used as the standard way of prioritizing, labeling, and interacting with issues.
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture body %}}
|
||||
|
||||
## Categorizing issues
|
||||
Issues should be sorted into different buckets of work using the following labels and definitions. If an issue doesn't have enough information to identify a problem that can be researched, reviewed, or worked on (i.e. the issue doesn't fit into any of the categories below) you should close the issue with a comment explaining why it is being closed.
|
||||
|
||||
### Needs Clarification
|
||||
* Issues that need more information from the original submitter to make them actionable. Issues with this label that aren't followed up within a week may be closed.
|
||||
|
||||
### Actionable
|
||||
* Issues that can be worked on with current information (or may need a comment to explain what needs to be done to make it more clear)
|
||||
* Allows contributors to have easy to find issues to work on
|
||||
|
||||
|
||||
### Needs Tech Review
|
||||
* Issues that need more information in order to be worked on (the proposed solution needs to be proven, a subject matter expert needs to be involved, work needs to be done to understand the problem/resolution and if the issue is still relevant)
|
||||
* Promotes transparency about level of work needed for the issue and that issue is in progress
|
||||
|
||||
### Needs Docs Review
|
||||
* Issues that are suggestions for better processes or site improvements that require community agreement to be implemented
|
||||
* Topics can be brought to SIG meetings as agenda items
|
||||
|
||||
### Needs UX Review
|
||||
* Issues that are suggestions for improving the user interface of the site.
|
||||
* Fixing broken site elements.
|
||||
|
||||
## Prioritizing Issues
|
||||
The following labels and definitions should be used to prioritize issues. If you change the priority of an issues, please comment on the issue with your reasoning for the change.
|
||||
|
||||
### P1
|
||||
* Major content errors affecting more than 1 page
|
||||
* Broken code sample on a heavily trafficked page
|
||||
* Errors on a “getting started” page
|
||||
* Well known or highly publicized customer pain points
|
||||
* Automation issues
|
||||
|
||||
### P2
|
||||
* Default for all new issues
|
||||
* Broken code for sample that is not heavily used
|
||||
* Minor content issues in a heavily trafficked page
|
||||
* Major content issues on a lower-trafficked page
|
||||
|
||||
### P3
|
||||
* Typos and broken anchor links
|
||||
|
||||
## Handling special issue types
|
||||
|
||||
### Duplicate issues
|
||||
If a single problem has one or more issues open for it, the problem should be consolidated into a single issue. You should decide which issue to keep open (or open a new issue), port over all relevant information, link related issues, and close all the other issues that describe the same problem. Only having a single issue to work on will help reduce confusion and avoid duplicating work on the same problem.
|
||||
|
||||
### Dead link issues
|
||||
Depending on where the dead link is reported, different actions are required to resolve the issue. Dead links in the API and Kubectl docs are automation issues and should be assigned a P1 until the problem can be fully understood. All other dead links are issues that need to be manually fixed and can be assigned a P3.
|
||||
|
||||
### Support requests or code bug reports
|
||||
Some issues opened for docs are instead issues with the underlying code, or requests for assistance when something (like a tutorial) didn't work. For issues unrelated to docs, close the issue with a comment directing the requester to support venues (Slack, Stack Overflow) and, if relevant, where to file an issue for bugs with features (kubernetes/kubernetes is a great place to start).
|
||||
|
||||
Sample response to a request for support:
|
||||
|
||||
```
|
||||
This issue sounds more like a request for support and less
|
||||
like an issue specifically for docs. I encourage you to bring
|
||||
your question to the `#kubernetes-users` channel in
|
||||
[Kubernetes slack](http://slack.k8s.io/). You can also search
|
||||
resources like
|
||||
[Stack Overflow](http://stackoverflow.com/questions/tagged/kubernetes)
|
||||
for answers to similar questions.
|
||||
|
||||
You can also open issues for Kubernetes functionality in
|
||||
https://github.com/kubernetes/kubernetes.
|
||||
|
||||
If this is a documentation issue, please re-open this issue.
|
||||
```
|
||||
|
||||
Sample code bug report response:
|
||||
|
||||
```
|
||||
This sounds more like an issue with the code than an issue with
|
||||
the documentation. Please open an issue at
|
||||
https://github.com/kubernetes/kubernetes/issues.
|
||||
|
||||
If this is a documentation issue, please re-open this issue.
|
||||
```
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
* 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/).
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
|
|
@ -14,5 +14,5 @@ tags:
|
|||
|
||||
<!--more-->
|
||||
|
||||
While code review is focused on code quality and correctness, approval is focused on the holistic acceptance of a contribution. Holistic acceptance includes backwards/forwards compatibility, adhering to API and flag conventions, subtle performance and correctness issues, interactions with other parts of the system, and others. Approver status is scoped to a part of the codebase.
|
||||
While code review is focused on code quality and correctness, approval is focused on the holistic acceptance of a contribution. Holistic acceptance includes backwards/forwards compatibility, adhering to API and flag conventions, subtle performance and correctness issues, interactions with other parts of the system, and others. Approver status is scoped to a part of the codebase. Approvers were previously referred to as maintainers.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,18 +0,0 @@
|
|||
---
|
||||
title: Maintainer
|
||||
id: maintainer
|
||||
date: 2018-04-12
|
||||
full_link:
|
||||
short_description: >
|
||||
A highly experienced contributor, active in multiple areas of Kubernetes, who has cross-area ownership and write access to a project's GitHub repository.
|
||||
|
||||
aka:
|
||||
tags:
|
||||
- community
|
||||
---
|
||||
A highly experienced {{< glossary_tooltip text="contributor" term_id="contributor" >}}, active in multiple areas of Kubernetes, who has cross-area ownership and write access to a project's GitHub repository.
|
||||
|
||||
<!--more-->
|
||||
|
||||
Maintainers work holistically across the project to maintain its health and success and have made substantial contributions, both through code development and broader organizational efforts.
|
||||
|
||||
|
|
@ -214,6 +214,16 @@ Common languages used in Kubernetes documentation code blocks include:
|
|||
- `xml`
|
||||
- `none` (disables syntax highlighting for the block)
|
||||
|
||||
### Code blocks containing Hugo shortcodes
|
||||
|
||||
To show raw Hugo shortcodes as in the above example and prevent Hugo
|
||||
from interpreting them, use C-style comments directly after the `<` and before
|
||||
the `>` characters. The following example illustrates this (view the Markdown
|
||||
source for this page).
|
||||
|
||||
```none
|
||||
{{</* codenew file="pods/storage/gce-volume.yaml" */>}}
|
||||
```
|
||||
|
||||
## Links
|
||||
|
||||
|
|
|
|||
|
|
@ -30,14 +30,12 @@
|
|||
"title" : "{{ .Title }}",
|
||||
"permalink" : "{{ .Permalink }}"
|
||||
};
|
||||
(function(d,c,j){if(!document.getElementById(j)){var pd=d.createElement(c),s;pd.id=j;pd.src=('https:'==document.location.protocol)?'https://polldaddy.com/js/rating/rating.js':'http://i0.poll.fm/js/rating/rating.js';s=document.getElementsByTagName(c)[0];s.parentNode.insertBefore(pd,s);}}(document,'script','pd-rating-js'));
|
||||
</script>
|
||||
<a href="" onclick="window.open('https://github.com/kubernetes/website/issues/new?title=Issue%20with%20' +
|
||||
'k8s.io'+window.location.pathname)" class="button issue">Create an Issue</a>
|
||||
<a href="https://github.com/kubernetes/website/issues/new?title=Issue%20with%20k8s.io/{{ .URL }}%20%5BFile:%20/content/en/{{ .File.Path }}%5D" class="button issue" target="_blank">Report a problem</a>
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
{{ if not .Params.noedit }}
|
||||
<a href="{{ printf "%s#%s" ("docs/editdocs" | relURL) .Path | safeURL }}" class="button issue">Edit this Page</a>
|
||||
<a href="https://github.com/kubernetes/website/edit/master/content/en/{{ .File.Path }}" class="button issue" target="_blank">Edit on Github</a>
|
||||
{{ end }}
|
||||
</div>
|
||||
{{ if not .Params.showcommit }}
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
{{ define "content" }}
|
||||
{{ with .Content }}
|
||||
{{ partial "docs/content_page" (dict "ctx" $ "page" $) }}
|
||||
{{ partial "docs/content_page" (dict "ctx" $ "page" $ ) }}
|
||||
{{ else }}
|
||||
{{ if ge (len .Pages) 1 }}
|
||||
{{ $page := index .Pages 0 }}
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
<p><a href="{{ printf "%s#%s" ("docs/editdocs" | relURL) .page.Path | safeURL }}" id="editPageButton">Edit This Page</a></p>
|
||||
<p><a href="https://github.com/kubernetes/website/edit/master/content/en/{{ .page.File.Path }}" id="editPageButton" target="_blank">Edit This Page</a></p>
|
||||
{{ if not .page.Params.notitle }}
|
||||
<h1>{{ .page.Title }}</h1>
|
||||
{{ end }}
|
||||
|
|
|
|||
|
|
@ -192,6 +192,23 @@
|
|||
/docs/home/contribute/stage-documentation-changes/ /docs/home/contribute/create-pull-request/ 301
|
||||
/docs/home/coreos/ /docs/getting-started-guides/coreos/ 301
|
||||
/docs/home/deprecation-policy/ /docs/reference/using-api/deprecation-policy/ 301
|
||||
|
||||
/docs/home/contribute/ /docs/contribute/ 301
|
||||
/docs/home/contribute/content-organization/ /docs/contribute/style/content-organization/ 301
|
||||
/docs/home/contribute/create-pull-request/ /docs/contribute/foundational/ 301
|
||||
/docs/home/contribute/includes/ /docs/contribute/style/hugo_shortcodes/ 301
|
||||
/docs/home/contribute/style-guide/ /docs/contribute/style/style-guide/ 301
|
||||
/docs/home/contribute/generated-reference/federation-api/ /docs/contribute/generate-ref-docs/federation-api/ 301
|
||||
/docs/home/contribute/generated-reference/kubectl/ /docs/contribute/generate-ref-docs/kubectl/ 301
|
||||
/docs/home/contribute/generated-reference/kubernetes-api/ /docs/contribute/generate-ref-docs/kubernetes-api/ 301
|
||||
/docs/home/contribute/generated-reference/kubernetes-components/ /docs/contribute/generate-ref-docs/kubernetes-components/ 301
|
||||
/docs/home/contribute/localization/ /docs/contribute/localization/ 301
|
||||
/docs/home/contribute/page-templates/ /docs/contribute/style/page-templates/ 301
|
||||
/docs/home/contribute/participating/ /docs/contribute/participating/ 301
|
||||
/docs/home/contribute/review-issues/ /docs/contribute/intermediate/ 301
|
||||
/docs/home/contribute/blog-post/ /docs/contribute/foundational/ 301
|
||||
/docs/home/contribute/write-new-topic/ /docs/contribute/style/write-new-topic/ 301
|
||||
|
||||
/docs/reference/deprecation-policy/ /docs/reference/using-api/deprecation-policy/ 301
|
||||
/docs/reference/federation/v1beta1/definitions/ /docs/reference/federation/extensions/v1beta1/definitions/ 301
|
||||
/docs/reference/federation/v1beta1/operations/ /docs/reference/federation/extensions/v1beta1/operations/ 301
|
||||
|
|
@ -213,6 +230,9 @@
|
|||
/docs/reference/generated/kubefed_options/ /docs/reference/setup-tools/kubefed/kubefed-options/ 301
|
||||
/docs/reference/generated/kubefed_unjoin/ /docs/reference/setup-tools/kubefed/kubefed-unjoin/ 301
|
||||
/docs/reference/generated/kubefed_version/ /docs/reference/setup-tools/kubefed/kubefed-version/ 301
|
||||
|
||||
/docs/reference/glossary/maintainer/ /docs/reference/glossary/approver/ 301
|
||||
|
||||
/docs/reference/kubectl/kubectl/kubectl_*.md /docs/reference/generated/kubectl/kubectl-commands#:splat 301
|
||||
/docs/reference/workloads-18-19/ https://v1-9.docs.kubernetes.io/docs/reference/workloads-18-19/ 301
|
||||
|
||||
|
|
@ -503,7 +523,8 @@ https://kubernetes-io-v1-7.netlify.com/* https://v1-7.docs.kubernetes.io/:spl
|
|||
|
||||
/docs/reference/generated/kubeadm/ /docs/reference/setup-tools/kubeadm/kubeadm/ 301
|
||||
|
||||
/editdocs/ /docs/home/contribute/ 301
|
||||
/editdocs/ /docs/contribute/ 301
|
||||
/docs/home/editdocs/ /docs/contribute/ 301
|
||||
|
||||
/docs/admin/accessing-the-api/ /docs/reference/access-authn-authz/controlling-access/ 301
|
||||
/docs/admin/admission-controllers/ /docs/reference/access-authn-authz/admission-controllers/ 301
|
||||
|
|
|
|||
Loading…
Reference in New Issue