Merge pull request #2311 from guineveresaenger/release-docs
Remove and redirect of release process information
This commit is contained in:
k8s-ci-robot
GitHub
commit
d1db844e6c
|
|
@ -1,108 +1,3 @@
|
|||
# Table of Contents
|
||||
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [Overview](#overview)
|
||||
- [Adding a new docs collection for a release](#adding-a-new-docs-collection-for-a-release)
|
||||
- [Updating docs in an existing collection](#updating-docs-in-an-existing-collection)
|
||||
- [Updating docs on HEAD](#updating-docs-on-head)
|
||||
- [Updating docs in release branch](#updating-docs-in-release-branch)
|
||||
- [Updating docs in gh-pages branch](#updating-docs-in-gh-pages-branch)
|
||||
|
||||
|
||||
# Overview
|
||||
|
||||
This document explains how to update kubernetes release docs hosted at http://kubernetes.io/docs/.
|
||||
|
||||
http://kubernetes.io is served using the [gh-pages
|
||||
branch](https://github.com/kubernetes/kubernetes/tree/gh-pages) of kubernetes repo on github.
|
||||
Updating docs in that branch will update http://kubernetes.io
|
||||
|
||||
There are 2 scenarios which require updating docs:
|
||||
* Adding a new docs collection for a release.
|
||||
* Updating docs in an existing collection.
|
||||
|
||||
# Adding a new docs collection for a release
|
||||
|
||||
Whenever a new release series (`release-X.Y`) is cut from `master`, we push the
|
||||
corresponding set of docs to `http://kubernetes.io/vX.Y/docs`. The steps are as follows:
|
||||
|
||||
* Create a `_vX.Y` folder in `gh-pages` branch.
|
||||
* Add `vX.Y` as a valid collection in [_config.yml](https://github.com/kubernetes/kubernetes/blob/gh-pages/_config.yml)
|
||||
* Create a new `_includes/nav_vX.Y.html` file with the navigation menu. This can
|
||||
be a copy of `_includes/nav_vX.Y-1.html` with links to new docs added and links
|
||||
to deleted docs removed. Update [_layouts/docwithnav.html]
|
||||
(https://github.com/kubernetes/kubernetes/blob/gh-pages/_layouts/docwithnav.html)
|
||||
to include this new navigation html file. Example PR: [#16143](https://github.com/kubernetes/kubernetes/pull/16143).
|
||||
* [Pull docs from release branch](#updating-docs-in-gh-pages-branch) in `_vX.Y`
|
||||
folder.
|
||||
|
||||
Once these changes have been submitted, you should be able to reach the docs at
|
||||
`http://kubernetes.io/vX.Y/docs/` where you can test them.
|
||||
|
||||
To make `X.Y` the default version of docs:
|
||||
|
||||
* Update [_config.yml](https://github.com/kubernetes/kubernetes/blob/gh-pages/_config.yml)
|
||||
and [/kubernetes/kubernetes/blob/gh-pages/_docs/index.md](https://github.com/kubernetes/kubernetes/blob/gh-pages/_docs/index.md)
|
||||
to point to the new version. Example PR: [#16416](https://github.com/kubernetes/kubernetes/pull/16416).
|
||||
* Update [_includes/docversionselector.html](https://github.com/kubernetes/kubernetes/blob/gh-pages/_includes/docversionselector.html)
|
||||
to make `vX.Y` the default version.
|
||||
* Add "Disallow: /vX.Y-1/" to existing [robots.txt](https://github.com/kubernetes/kubernetes/blob/gh-pages/robots.txt)
|
||||
file to hide old content from web crawlers and focus SEO on new docs. Example PR:
|
||||
[#16388](https://github.com/kubernetes/kubernetes/pull/16388).
|
||||
* Regenerate [sitemaps.xml](https://github.com/kubernetes/kubernetes/blob/gh-pages/sitemap.xml)
|
||||
so that it now contains `vX.Y` links. Sitemap can be regenerated using
|
||||
https://www.xml-sitemaps.com. Example PR: [#17126](https://github.com/kubernetes/kubernetes/pull/17126).
|
||||
* Resubmit the updated sitemaps file to [Google
|
||||
webmasters](https://www.google.com/webmasters/tools/sitemap-list?siteUrl=http://kubernetes.io/) for google to index the new links.
|
||||
* Update [_layouts/docwithnav.html] (https://github.com/kubernetes/kubernetes/blob/gh-pages/_layouts/docwithnav.html)
|
||||
to include [_includes/archivedocnotice.html](https://github.com/kubernetes/kubernetes/blob/gh-pages/_includes/archivedocnotice.html)
|
||||
for `vX.Y-1` docs which need to be archived.
|
||||
* Ping @thockin to update docs.k8s.io to redirect to `http://kubernetes.io/vX.Y/`. [#18788](https://github.com/kubernetes/kubernetes/issues/18788).
|
||||
|
||||
http://kubernetes.io/docs/ should now be redirecting to `http://kubernetes.io/vX.Y/`.
|
||||
|
||||
# Updating docs in an existing collection
|
||||
|
||||
The high level steps to update docs in an existing collection are:
|
||||
|
||||
1. Update docs on `HEAD` (master branch)
|
||||
2. Cherryick the change in relevant release branch.
|
||||
3. Update docs on `gh-pages`.
|
||||
|
||||
## Updating docs on HEAD
|
||||
|
||||
[Development guide](development.md) provides general instructions on how to contribute to kubernetes github repo.
|
||||
[Docs how to guide](how-to-doc.md) provides conventions to follow while writing docs.
|
||||
|
||||
## Updating docs in release branch
|
||||
|
||||
Once docs have been updated in the master branch, the changes need to be
|
||||
cherrypicked in the latest release branch.
|
||||
[Cherrypick guide](cherry-picks.md) has more details on how to cherrypick your change.
|
||||
|
||||
## Updating docs in gh-pages branch
|
||||
|
||||
Once release branch has all the relevant changes, we can pull in the latest docs
|
||||
in `gh-pages` branch.
|
||||
Run the following 2 commands in `gh-pages` branch to update docs for release `X.Y`:
|
||||
|
||||
```
|
||||
_tools/import_docs vX.Y _vX.Y release-X.Y release-X.Y
|
||||
```
|
||||
|
||||
For ex: to pull in docs for release 1.1, run:
|
||||
|
||||
```
|
||||
_tools/import_docs v1.1 _v1.1 release-1.1 release-1.1
|
||||
```
|
||||
|
||||
Apart from copying over the docs, `_tools/release_docs` also does some post processing
|
||||
(like updating the links to docs to point to http://kubernetes.io/docs/ instead of pointing to github repo).
|
||||
Note that we always pull in the docs from release branch and not from master (pulling docs
|
||||
from master requires some extra processing like versionizing the links and removing unversioned warnings).
|
||||
|
||||
We delete all existing docs before pulling in new ones to ensure that deleted
|
||||
docs go away.
|
||||
|
||||
If the change added or deleted a doc, then update the corresponding `_includes/nav_vX.Y.html` file as well.
|
||||
This document relates to the release process and can be found [here](https://git.k8s.io/sig-release/release-process-documentation/documentation-guides/update-release-docs-new.md).
|
||||
|
||||
*This file is a redirect stub. It should be deleted within 3 months from the current date, or by the release date of k8s v1.12, whichever comes sooner.*
|
||||
|
|
@ -1,72 +1,3 @@
|
|||
# How to update docs for new kubernetes features
|
||||
|
||||
This document describes things to consider when updating Kubernetes docs for new features or changes to existing features (including removing features).
|
||||
|
||||
## Who should read this doc?
|
||||
|
||||
Anyone making user facing changes to kubernetes. This is especially important for Api changes or anything impacting the getting started experience.
|
||||
|
||||
## What docs changes are needed when adding or updating a feature in kubernetes?
|
||||
|
||||
### When making Api changes
|
||||
|
||||
*e.g. adding Deployments*
|
||||
* Always make sure docs for downstream effects are updated *(StatefulSet -> PVC, Deployment -> ReplicationController)*
|
||||
* Add or update the corresponding *[Glossary](http://kubernetes.io/docs/reference/)* item
|
||||
* Verify the guides / walkthroughs do not require any changes:
|
||||
* **If your change will be recommended over the approaches shown in these guides, then they must be updated to reflect your change**
|
||||
* [Hello Node](http://kubernetes.io/docs/hellonode/)
|
||||
* [K8s101](http://kubernetes.io/docs/user-guide/walkthrough/)
|
||||
* [K8S201](http://kubernetes.io/docs/user-guide/walkthrough/k8s201/)
|
||||
* [Guest-book](https://github.com/kubernetes/kubernetes/tree/release-1.2/examples/guestbook)
|
||||
* [Thorough-walkthrough](http://kubernetes.io/docs/user-guide/)
|
||||
* Verify the [landing page examples](http://kubernetes.io/docs/samples/) do not require any changes (those under "Recently updated samples")
|
||||
* **If your change will be recommended over the approaches shown in the "Updated" examples, then they must be updated to reflect your change**
|
||||
* If you are aware that your change will be recommended over the approaches shown in non-"Updated" examples, create an Issue
|
||||
* Verify the collection of docs under the "Guides" section do not require updates (may need to use grep for this until are docs are more organized)
|
||||
|
||||
### When making Tools changes
|
||||
|
||||
*e.g. updating kube-dash or kubectl*
|
||||
* If changing kubectl, verify the guides / walkthroughs do not require any changes:
|
||||
* **If your change will be recommended over the approaches shown in these guides, then they must be updated to reflect your change**
|
||||
* [Hello Node](http://kubernetes.io/docs/hellonode/)
|
||||
* [K8s101](http://kubernetes.io/docs/user-guide/walkthrough/)
|
||||
* [K8S201](http://kubernetes.io/docs/user-guide/walkthrough/k8s201/)
|
||||
* [Guest-book](https://github.com/kubernetes/kubernetes/tree/release-1.2/examples/guestbook)
|
||||
* [Thorough-walkthrough](http://kubernetes.io/docs/user-guide/)
|
||||
* If updating an existing tool
|
||||
* Search for any docs about the tool and update them
|
||||
* If adding a new tool for end users
|
||||
* Add a new page under [Guides](http://kubernetes.io/docs/)
|
||||
* **If removing a tool (kube-ui), make sure documentation that references it is updated appropriately!**
|
||||
|
||||
### When making cluster setup changes
|
||||
|
||||
*e.g. adding Multi-AZ support*
|
||||
* Update the relevant [Administering Clusters](http://kubernetes.io/docs/) pages
|
||||
|
||||
### When making Kubernetes binary changes
|
||||
|
||||
*e.g. adding a flag, changing Pod GC behavior, etc*
|
||||
* Add or update a page under [Configuring Kubernetes](http://kubernetes.io/docs/)
|
||||
|
||||
## Where do the docs live?
|
||||
|
||||
1. Most external user facing docs live in the [kubernetes/docs](https://github.com/kubernetes/kubernetes.github.io) repo
|
||||
* Also see the *[general instructions](http://kubernetes.io/editdocs/)* for making changes to the docs website
|
||||
2. Internal design and development docs live in the [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repo
|
||||
|
||||
## Who should help review docs changes?
|
||||
|
||||
* cc *@kubernetes/docs*
|
||||
* Changes to [kubernetes/docs](https://github.com/kubernetes/kubernetes.github.io) repo must have both a Technical Review and a Docs Review
|
||||
|
||||
## Tips for writing new docs
|
||||
|
||||
* Try to keep new docs small and focused
|
||||
* Document pre-requisites (if they exist)
|
||||
* Document what concepts will be covered in the document
|
||||
* Include screen shots or pictures in documents for GUIs
|
||||
* *TODO once we have a standard widget set we are happy with* - include diagrams to help describe complex ideas (not required yet)
|
||||
This document relates to the release process and can be found [here](https://git.k8s.io/sig-release/release-process-documentation/documentation-guides/updating-docs-for-feature-changes.md).
|
||||
|
||||
*This file is a redirect stub. It should be deleted within 3 months from the current date, or by the release date of k8s v1.12, whichever comes sooner.*
|
||||
Loading…
Reference in New Issue