Merge pull request #1478 from steveperry-53/contribution-guide-2

Write new material about how to contribute to the Kubernetes docs.
reviewable/pr1503/r1
devin-donnelly 2016-10-18 17:09:19 -07:00 committed by GitHub
commit 499bd7828f
10 changed files with 301 additions and 151 deletions

View File

@ -4,6 +4,13 @@ Welcome! We are very pleased you want to contribute to the documentation and/or
You can click the "Fork" button in the upper-right area of the screen to create a copy of our site on your GitHub account called a "fork." 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 "New Pull Request" to let us know about it.
For more information about contributing to the Kubernetes documentation, see:
* [Creating a Documentation Pull Request](http://kubernetes.io/docs/contribute/create-pull-request/)
* [Writing a New Topic](http://kubernetes.io/docs/contribute/write-new-topic/)
* [Staging Your Documentation Changes](http://kubernetes.io/docs/contribute/stage-documentation-changes/)
* [Using Page Templates](http://kubernetes.io/docs/contribute/page-templates/)
## Automatic Staging for Pull Requests
When you create a pull request (either against master or the upcoming release), your changes are staged in a custom subdomain on Netlify so that you can see your changes in rendered form before the PR is merged. You can use this to verify that everything is correct before the PR gets merged. To view your changes:
@ -13,17 +20,17 @@ When you create a pull request (either against master or the upcoming release),
- Look for "deploy/netlify"; you'll see "Deploy Preview Ready!" if staging was successful
- Click "Details" to bring up the staged site and navigate to your changes
## Release Branch Staging
## Branch structure and staging
The Kubernetes site maintains staged versions at a subdomain provided by Netlify. Every PR for the Kubernetes site, either against the master branch or the upcoming release branch, is staged automatically.
The current version of the website is served out of the `master` branch. To make changes to the live docs, such as bug fixes, broken links, typos, etc, **target your pull request to the master branch**
The staging site for the next upcoming Kubernetes release is here: [http://kubernetes-io-vnext-staging.netlify.com/](http://kubernetes-io-vnext-staging.netlify.com/)
The `release-1.x` branch stores changes for **upcoming releases of Kubernetes**. For example, the `release-1.5` branch has changes for the 1.5 release. These changes target branches (and *not* master) to avoid publishing documentation updates prior to the release for which they're relevant. If you have a change for an upcoming release of Kubernetes, **target your pull request to the appropriate release branch**.
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.
The staging site for the next 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.
## Staging the site locally (using Docker)
Don't like installing stuff? Download and run a local staging server with a single `docker run` command.
Don't like installing stuff? Download and run a local staging server with a single `docker run` command.
git clone https://github.com/kubernetes/kubernetes.github.io.git
cd kubernetes.github.io
@ -47,7 +54,7 @@ Install Ruby 2.2 or higher. If you're on Linux, run these commands:
apt-get install ruby2.2
apt-get install ruby2.2-dev
* If you're on a Mac, follow [these instructions](https://gorails.com/setup/osx/).
* If you're on a Mac, follow [these instructions](https://gorails.com/setup/osx/).
* If you're on a Windows machine you can use the [Ruby Installer](http://rubyinstaller.org/downloads/). During the installation make sure to check the option for *Add Ruby executables to your PATH*.
The remainder of the steps should work the same across operating systems.
@ -70,6 +77,11 @@ Make any changes you want. Then, to see your changes locally:
Your copy of the site will then be viewable at: [http://localhost:4000](http://localhost:4000)
(or wherever Jekyll tells you).
=======
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.
>>>>>>> contribution-guide-2
## GitHub help
If you're a bit rusty with git/GitHub, you might want to read
@ -140,16 +152,6 @@ That, of course, will send users to:
(Or whatever Kubernetes release that docs branch is associated with.)
## Branch structure
The current version of the website is served out of the `master` branch. To make changes to the live docs, such as bug fixes, broken links, typos, etc, **target your pull request to the master branch**.
The `release-1.x` branches store changes for **upcoming releases of Kubernetes**. For example, the `release-1.5` branch has changes for the upcoming 1.5 release. These changes target branches (and *not* master) to avoid publishing documentation updates prior to the release for which they're relevant. If you have a change for an upcoming release of Kubernetes, **target your pull request to the appropriate release branch**.
Changes in the "docsv2" branch (where we are testing a revamp of the docs) are automatically staged here:
http://k8sdocs.github.io/docs/tutorials/
## Config yaml guidelines
Guidelines for config yamls that are included in the site docs. These

View File

@ -30,4 +30,3 @@ permalink: pretty
gems:
- jekyll-redirect-from

View File

@ -6,6 +6,12 @@ toc:
- title: Contributing to the Kubernetes Docs
section:
- title: Creating a Documentation Pull Request
path: /docs/contribute/create-pull-request/
- title: Writing a New Topic
path: /docs/contribute/write-new-topic/
- title: Staging Your Documentation Changes
path: /docs/contribute/stage-documentation-changes/
- title: Using Page Templates
path: /docs/contribute/page-templates/

View File

@ -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 &lt;vnext&gt; 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 %}

View File

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

View File

@ -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 %}

View File

@ -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 %}

View File

@ -117,7 +117,7 @@ h2, h3, h4 {
<div class="col2nd">
<h3>Contribute to Our Docs</h3>
<p>The docs for Kubernetes are open-source, just like the code for Kubernetes itself. The docs are on GitHub Pages, so you can fork it and it will auto-stage on username.github.io, previewing your changes!</p>
<a href="/editdocs/" class="button">Write Docs for K8s</a>
<a href="/docs/contribute/create-pull-request/" class="button">Write Docs for K8s</a>
</div>
<div class="col2nd">
<h3>Need Help?</h3>

View File

@ -1,90 +0,0 @@
---
---
{% capture overview %}
This page shows how to use an HTTP proxy to access the Kubernetes API.
{% endcapture %}
{% capture prerequisites %}
* Install [kubectl](http://kubernetes.io/docs/user-guide/prereqs).
* Create a Kubernetes cluster, including a running Kubernetes
API server. One way to create a new cluster is to use
[Minikube](/docs/getting-started-guides/minikube).
* Configure `kubectl` to communicate with your Kubernetes API server. This
configuration is done automatically if you use Minikube.
* If you do not already have an application running in your cluster, start
a Hello world application by entering this command:
kubectl run --image=gcr.io/google-samples/node-hello:1.0 --port=8080
{% endcapture %}
{% capture steps %}
### Using kubectl to start a proxy server
This command starts a proxy to the Kubernetes API server:
kubectl proxy --port=8080
### Exploring the Kubernetes API
When the proxy server is running, you can explore the API using `curl`, `wget`,
or a browser.
Get the API versions:
curl http://localhost:8080/api/
{
"kind": "APIVersions",
"versions": [
"v1"
],
"serverAddressByClientCIDRs": [
{
"clientCIDR": "0.0.0.0/0",
"serverAddress": "10.0.2.15:8443"
}
]
}
Get a list of pods:
curl http://localhost:8080/api/v1/namespaces/default/pods
{
"kind": "PodList",
"apiVersion": "v1",
"metadata": {
"selfLink": "/api/v1/namespaces/default/pods",
"resourceVersion": "33074"
},
"items": [
{
"metadata": {
"name": "kubernetes-bootcamp-2321272333-ix8pt",
"generateName": "kubernetes-bootcamp-2321272333-",
"namespace": "default",
"selfLink": "/api/v1/namespaces/default/pods/kubernetes-bootcamp-2321272333-ix8pt",
"uid": "ba21457c-6b1d-11e6-85f7-1ef9f1dab92b",
"resourceVersion": "33003",
"creationTimestamp": "2016-08-25T23:43:30Z",
"labels": {
"pod-template-hash": "2321272333",
"run": "kubernetes-bootcamp"
},
...
}
{% endcapture %}
{% capture whatsnext %}
Learn more about [kubectl proxy](/docs/user-guide/kubectl/kubectl_proxy).
{% endcapture %}
{% include templates/task.md %}

View File

@ -1,42 +0,0 @@
---
layout: docwithnav
---
<!-- BEGIN: Gotta keep this section JS/HTML because it swaps out content dynamically -->
<p>&nbsp;</p>
<script language="JavaScript">
var forwarding=window.location.hash.replace("#","");
$( document ).ready(function() {
if(forwarding) {
$("#generalInstructions").hide();
$("#continueEdit").show();
$("#continueEditButton").text("Edit " + forwarding);
$("#continueEditButton").attr("href", "https://github.com/kubernetes/kubernetes.github.io/edit/master/" + forwarding)
} else {
$("#generalInstructions").show();
$("#continueEdit").hide();
}
});
</script>
<div id="continueEdit">
<h2>Continue your edit</h2>
<p>Click the below link to edit the page you were just on. When you are done, press "Commit Changes" at the bottom of the screen. This will create a copy of our site on your GitHub account called a "fork." You can make other changes in your fork after it is created, if you want. When you are ready to send us all your changes, go to the index page for your fork and click "New Pull Request" to let us know about it.</p>
<p><a id="continueEditButton" class="button"></a></p>
</div>
<div id="generalInstructions">
<h2>Edit our site in the cloud</h2>
<p>Click the below button to visit the repo for our site. You can then click the "Fork" button in the upper-right area of the screen to create a copy of our site on your GitHub account called a "fork." 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 "New Pull Request" to let us know about it.</p>
<p><a class="button" href="https://github.com/kubernetes/kubernetes.github.io/">Browse this site's source code</a></p>
</div>
<!-- END: Dynamic section -->
{% include_relative README.md %}