diff --git a/contributors/devel/update-release-docs.md b/contributors/devel/update-release-docs.md index 68c6707cd..abe3f19e1 100644 --- a/contributors/devel/update-release-docs.md +++ b/contributors/devel/update-release-docs.md @@ -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.* \ No newline at end of file diff --git a/contributors/devel/updating-docs-for-feature-changes.md b/contributors/devel/updating-docs-for-feature-changes.md index 1171d3978..94d3f5111 100644 --- a/contributors/devel/updating-docs-for-feature-changes.md +++ b/contributors/devel/updating-docs-for-feature-changes.md @@ -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.* \ No newline at end of file