Write new material about how to contribute to the Kubernetes docs.
This commit is contained in:
steveperry-53
@@ -0,0 +1,94 @@
|
||||
---
|
||||
redirect_from:
|
||||
- /editdocs/
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
|
||||
To contribute to the Kubernetes documentation, create a pull request against the
|
||||
[kubernetes/kubernetes.github.io](https://github.com/kubernetes/kubernetes.github.io){: target="_blank"}
|
||||
repository. This page shows how to create a pull request.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture prerequisites %}
|
||||
|
||||
1. Create a [GitHub account](https://github.com){: target="_blank"}.
|
||||
|
||||
1. Sign the
|
||||
[Google Contributor License Agreement](https://cla.developers.google.com/about/google-individual){: target="_blank"}.
|
||||
|
||||
1. Sign the
|
||||
[Linux Contributor License Agreement](https://identity.linuxfoundation.org/projects/cncf){: target="_blank"}.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture steps %}
|
||||
|
||||
### Creating a fork of the Kubernetes documentation repository
|
||||
|
||||
1. Go to the
|
||||
[kubernetes/kubernetes.github.io](https://github.com/kubernetes/kubernetes.github.io){: target="_blank"}
|
||||
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/contribute/write-new-topic/),
|
||||
choose the
|
||||
[page type](/docs/contribute/page-templates/)
|
||||
that is the best fit for your content.
|
||||
|
||||
### Submitting a pull request to the master branch
|
||||
|
||||
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/kubernetes.github.io
|
||||
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
|
||||
|
||||
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/kubernetes.github.io
|
||||
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.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn about [writing a new topic](/docs/contribute/write-new-topic).
|
||||
* Learn about [using page templates](/docs/contribute/page-templates/).
|
||||
* Learn about [staging your changes](/docs/contribute/stage-documentation-changes).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/task.md %}
|
||||
@@ -71,7 +71,7 @@ Here's an interesting thing to know about the steps you just did.
|
||||
|
||||
<p>Here's an example of a published topic that uses the task template:</p>
|
||||
|
||||
<p><a href="/docs/tasks/access-application-cluster/http-proxy-access-application-cluster">Using an HTTP Proxy to Access Applications in a Cluster</a></p>
|
||||
<p><a href="/docs/tasks/access-kubernetes-api/http-proxy-access-api">Using an HTTP Proxy to Access the Kubernetes API</a></p>
|
||||
|
||||
<h3 id="tutorial_template">Tutorial template</h3>
|
||||
|
||||
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page shows how to stage content that you want to contribute
|
||||
to the Kubernetes documentation.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture prerequisites %}
|
||||
Create a fork of the Kubernetes documentation repository as described in
|
||||
[Creating a Documentation Pull Request](/docs/contribute/create-pull-request/).
|
||||
{% endcapture %}
|
||||
|
||||
{% capture steps %}
|
||||
|
||||
### Staging from your GitHub account
|
||||
|
||||
GitHub provides staging of content in your master branch. Note that you
|
||||
might not want to merge your changes into your master branch. If that is
|
||||
the case, choose another option for staging your content.
|
||||
|
||||
1. In your GitHub account, in your fork, merge your changes into
|
||||
the master branch.
|
||||
|
||||
1. Change the name of your repository to `<your-username>.github.io`, where
|
||||
`<your-username>` is the username of your GitHub account.
|
||||
|
||||
1. Delete the `CNAME` file.
|
||||
|
||||
1. View your staged content at this URL:
|
||||
|
||||
https://<your-username>.github.io
|
||||
|
||||
### Staging a pull request
|
||||
|
||||
When you create pull request against the Kubernetes documentation
|
||||
repository, you can see your changes on a staging server.
|
||||
|
||||
1. In your GitHub account, in your new branch, submit a pull request to the
|
||||
kubernetes/kubernetes.github.io 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 see your changes.
|
||||
|
||||
### Staging locally using Docker
|
||||
|
||||
You can use the k8sdocs Docker image to run a local staging server. If you're
|
||||
interested, you can view the
|
||||
[Dockerfile](https://github.com/kubernetes/kubernetes.github.io/blob/master/staging-container/Dockerfile){: target="_blank"}
|
||||
for this image.
|
||||
|
||||
1. Install Docker if you don't already have it.
|
||||
|
||||
1. Clone your fork to your local development machine.
|
||||
|
||||
1. In the root of your cloned repository, enter this command to start a local
|
||||
web server:
|
||||
|
||||
docker run -ti --rm -v "$PWD":/k8sdocs -p 4000:4000 gcr.io/google-samples/k8sdocs:1.0
|
||||
|
||||
1. View your staged content at
|
||||
[http://localhost:4000](http://localhost:4000){: target="_blank"}.
|
||||
|
||||
### Staging locally without Docker
|
||||
|
||||
1. [Install Ruby 2.2 or later](https://www.ruby-lang.org){: target="_blank"}.
|
||||
|
||||
1. [Install RubyGems](https://rubygems.org){: target="_blank"}.
|
||||
|
||||
1. Verify that Ruby and RubyGems are installed:
|
||||
|
||||
gem --version
|
||||
|
||||
1. Install the GitHub Pages package, which includes Jekyll:
|
||||
|
||||
gem install github-pages
|
||||
|
||||
1. Clone your fork to your local development machine.
|
||||
|
||||
1. In the root of your cloned repository, enter this command to start a local
|
||||
web server:
|
||||
|
||||
jekyll serve
|
||||
|
||||
1. View your staged content at
|
||||
[http://localhost:4000](http://localhost:4000){: target="_blank"}.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn about [writing a new topic](/docs/contribute/write-new-topic/).
|
||||
* Learn about [using page templates](/docs/contribute/page-templates/).
|
||||
* Learn about [creating a pull request](/docs/contribute/create-pull-request/).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/task.md %}
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
---
|
||||
|
||||
{% capture overview %}
|
||||
This page shows how to create a new topic for the Kubernetes docs.
|
||||
{% endcapture %}
|
||||
|
||||
{% capture prerequisites %}
|
||||
Create a fork of the Kubernetes documentation repository as described in
|
||||
[Creating a Documentation Pull Request](/docs/contribute/create-pull-request/).
|
||||
{% endcapture %}
|
||||
|
||||
{% capture steps %}
|
||||
|
||||
### Choosing a page type
|
||||
|
||||
As you prepare to write a new topic, think about which of these page types
|
||||
is the best fit for your content:
|
||||
|
||||
<table>
|
||||
|
||||
<tr>
|
||||
<td>Task</td>
|
||||
<td>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.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>Tutorial</td>
|
||||
<td>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.</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.</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
Each page type has a
|
||||
[template](/docs/contribute/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
|
||||
|
||||
Choose a title that has the keywords you want search engines to find.
|
||||
Create a filename that uses the words in your title separated by hyphens.
|
||||
For example, the topic with title
|
||||
[Using an HTTP Proxy to Access the Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api/)
|
||||
has filename `http-proxy-access-api.md`. You don't need to put
|
||||
"kubernetes" in the filename, because "kubernetes" is already in the
|
||||
URL for the topic, for example:
|
||||
|
||||
http://kubernetes.io/docs/tasks/access-kubernetes-api/http-proxy-access-api/
|
||||
|
||||
### Choosing a directory
|
||||
|
||||
Depending on your page type, put your new file in a subdirectory of one of these:
|
||||
|
||||
* /docs/tasks/
|
||||
* /docs/tutorials/
|
||||
* /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
|
||||
|
||||
Depending page type, create an entry in one of these files:
|
||||
|
||||
* /_data/tasks.yaml
|
||||
* /_data/tutorials.yaml
|
||||
* /_data/concepts.yaml
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
* Learn about [using page templates](/docs/contribute/page-templates/).
|
||||
* Learn about [staging your changes](/docs/contribute/stage-documentation-changes).
|
||||
* Learn about [creating a pull request](/docs/contribute/write-new-topic).
|
||||
{% endcapture %}
|
||||
|
||||
{% include templates/task.md %}
|
||||
Reference in New Issue
Block a user