Thanks everyone for contributing your time on translating Kubernetes documentation into Chinese.

If you're not familiar with processes working with git, please follow the steps below:

1. Have git installed in your machine.

2. OPTIONAL: Clone already translated file to your local machine.

   git clone https://git.gitbook.com/linfan1/kubernetes-chinese-docs
   

3. Use the Fork button in the upper-right side of the screen to fork this repo to your own github account.

4. Clone your repo to your local machine.

5. git clone https://github.com/YOURACCOUNT/kubernetes-docs-cn.git

6. Enter the cloned folder and set your emailaddress and username of your github account, so when you commit a change, git will know who you are.

   git config set user.email YOUREMAILADDRESS
   git config set user.name YOURGITHUBACCOUNT
   

7. Set this repo as an upstream.

   git remote add upstream https://github.com/kubernetes/kubernetes-docs-cn.git
   

8. Check out to branch release-1.1-cn.

   git checkout release-1.1-cn
   

9. Snychronize your repo with upstream.

   git fetch upstream
   git merge upstream/release-1.1-cn
   

10. Create a new working branch.

    git checkout -b NEWWORKINGBRANCH

11. Do you translation work, the documents are located in /docs folder. If you have done step 2, find your translated file and overwrite the coresponding file. If you're working on an untranslated file, just edit it.

12. Commit your changes. Input your commit title and message as the prompt says. Then press Ctrl+X and then Shift+Y.

    git add . git commit

13. Push your commit to your own repo and create a branch coresponding to your working branch.

    git push origin NEWWORKINGBRANCH:NEWWORKINGBRANCH

14. Now go to your repo page https://github.com/YOURACCOUNT/kubernetes-docs-cn, use the New Pull Request button to create a new PR. DO choose release-1.1-cn branch in the left and NEWWORKINGBRANCH in the right.

15. Want to send another PR? Repeat step 8 to 14.

• The steps above are just very basic practices of using git. There're more problems you may meet. So if you're new to git, learn it ASAP.
• Start an issue before you create a PR, so other people would know which file you're working on. Issue can be named as Translating docs/admin/accessing-the-api.md.
• Bound the issue and PR together using #ISSUEID in your PR.
• Comment under your PR use @SOMEONE to notify someone to review your PR.
• Send only one translated file in one single PR. So reviewers can make a quick review and merge the PR early.
• The PR I created to modify the README file can be considered as a example.
• For more information, continue reading this file.

Welcome! We are very pleased you want to contribute to the documentation and/or website for Kubernetes.

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.

If you want to see your changes staged without having to install anything locally, remove the CNAME file in this directory and change the name of the fork to be:

YOUR_GITHUB_USERNAME.github.io

Then, visit: http://YOUR_GITHUB_USERNAME.github.io

You should see a special-to-you version of the site.

If you have files to upload, or just want to work offline, run the below commands to setup your environment for running GitHub pages locally. Then, any edits you make will be viewable on a lightweight webserver that runs on your local machine.

First install rvm

curl -sSL https://get.rvm.io | bash -s stable

Then load it into your environment

source ${HOME}/.rvm/scripts/rvm (or whatever is prompted by the installer)

Then install Ruby 2.2 or higher

rvm install ruby-2.2.4
rvm use ruby-2.2.4 --default

Verify that this new version is running (optional)

which ruby
ruby -v

Install the GitHub Pages package, which includes Jekyll

gem install github-pages

Clone our site

git clone https://github.com/kubernetes/kubernetes.github.io.git

Make any changes you want. Then, to see your changes locally:

cd kubernetes.github.io
jekyll serve

Your copy of the site will then be viewable at: http://localhost:4000 (or wherever Ruby tells you).

If you're a bit rusty with git/GitHub, you might wanna read this for a refresher.

The above instructions work on Mac and Linux. These instructions might help for Windows users.

Edit the yaml files in /_data/ for the Guides, Reference, Samples, or Support areas.

You may have to exit and jekyll clean before restarting the jekyll serve to get changes to files in /_data/ to show up.

Put the new image in /images/docs/ if it's for the documentation, and just /images/ if it's for the website.

For diagrams, we greatly prefer SVG files!

To include a file that is hosted on this GitHub repo, insert this code:

{% include code.html language="<LEXERVALUE>" file="<RELATIVEPATH>" ghlink="<PATHFROMROOT>" %}

• LEXERVALUE: The language in which the file was written; must be a value supported by Rouge.
• RELATIVEPATH: The path to the file you're including, relative to the current file.
• PATHFROMROOT: The path to the file relative to root, e.g. /docs/admin/foo.yaml

To include a file that is hosted in the external, main Kubernetes repo, make sure it's added to /update-imported-docs.sh, and run it so that the file gets downloaded, then enter:

{% include code.html language="<LEXERVALUE>" file="<RELATIVEPATH>" k8slink="<PATHFROMK8SROOT>" %}

• PATHFROMK8SROOT: The path to the file relative to the root of the Kubernetes repo, e.g. /examples/rbd/foo.yaml

By specifying some inline CSV in a varable called tabspec, you can include a file called tabs.html that generates tabs showing code examples in multiple langauges.

{% capture tabspec %}servicesample
JSON,json,service-sample.json,/docs/user-guide/services/service-sample.json
YAML,yaml,service-sample.yaml,/docs/user-guide/services/service-sample.yaml{% endcapture %}
{% include tabs.html %}

In English, this would read: "Create a set of tabs with the alias servicesample, and have tabs visually labeled "JSON" and "YAML" that use json and yaml Rouge syntax highlighting, which display the contents of service-sample.{extension} on the page, and link to the file in GitHub at (full path)."

Example file: Pods: Multi-Container.

The /_config.yml file defines some useful variables you can use when editing docs.

• page.githubbranch: The name of the GitHub branch on the Kubernetes repo that is associated with this branch of the docs. e.g. release-1.2
• page.version The version of Kubernetes associated with this branch of the docs. e.g. v1.2
• page.docsbranch The name of the GitHub branch on the Docs/Website repo that you are currently using. e.g. release-1.1 or master

This keeps the docs you're editing aligned with the Kubernetes version you're talking about. For example, if you define a link like so, you'll never have to worry about it going stale in future doc branches:

View the README [here](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/README.md).

That, of course, will send users to:

http://releases.k8s.io/release-1.2/cluster/addons/README.md

(Or whatever Kubernetes release that docs branch is associated with.)

The current version of the website is served out of the master branch.

All versions of the site that relate to past and future versions will be named after their Kubernetes release number. For example, the old branch for the 1.1 docs is called release-1.1.

Kubernetes thrives on community participation and we really appreciate your contributions to our site and our documentation!