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
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
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
