kubernetes · thockin · Jul 13, 2015 · Jul 10, 2015 · Jul 10, 2015 · Jul 10, 2015
diff --git a/build/mark-new-version.sh b/build/mark-new-version.sh
@@ -92,12 +92,20 @@ fi
 echo "+++ Versioning documentation and examples"
 
 # Update the docs to match this version.
-DOCS_TO_EDIT=(docs/README.md examples/README.md)
-for DOC in "${DOCS_TO_EDIT[@]}"; do
+md_dirs=(docs examples)
+md_files=()
+for dir in "${md_dirs[@]}"; do
+  mdfiles+=($( find "${dir}" -name "*.md" -type f ))
+done
+for doc in "${mdfiles[@]}"; do
   $SED -ri \
       -e '/<!-- BEGIN STRIP_FOR_RELEASE -->/,/<!-- END STRIP_FOR_RELEASE -->/d' \
       -e "s|(releases.k8s.io)/[^/]+|\1/${NEW_VERSION}|" \
-      "${DOC}"
+      "${doc}"
+  is_versioned_tag='<!-- TAG IS_VERSIONED -->'
+  if ! grep -q "${is_versioned_tag}" "${doc}"; then
+    echo "${is_versioned_tag}" >> "${doc}"
+  fi
 done
 
 # Update API descriptions to match this version.

diff --git a/cmd/mungedocs/mungedocs.go b/cmd/mungedocs/mungedocs.go
@@ -40,6 +40,7 @@ var (
 	allMunges = []munge{
 		{"table-of-contents", updateTOC},
 		{"check-links", checkLinks},
+		{"unversioned-warning", updateUnversionedWarning},
 	}
 )
 

diff --git a/cmd/mungedocs/toc.go b/cmd/mungedocs/toc.go
@@ -23,10 +23,12 @@ import (
 	"strings"
 )
 
+const tocMungeTag = "GENERATED_TOC"
+
 // inserts/updates a table of contents in markdown file.
 //
 // First, builds a ToC.
-// Then, finds <!-- BEGIN GENERATED TOC --> and <!-- END GENERATED TOC -->, and replaces anything between those with
+// Then, finds the magic macro block tags and replaces anything between those with
 // the ToC, thereby updating any previously inserted ToC.
 //
 // TODO(erictune): put this in own package with tests
@@ -36,7 +38,7 @@ func updateTOC(filePath string, markdown []byte) ([]byte, error) {
 		return nil, err
 	}
 	lines := splitLines(markdown)
-	updatedMarkdown, err := updateMacroBlock(lines, "<!-- BEGIN GENERATED TOC -->", "<!-- END GENERATED TOC -->", string(toc))
+	updatedMarkdown, err := updateMacroBlock(lines, beginMungeTag(tocMungeTag), endMungeTag(tocMungeTag), string(toc))
 	if err != nil {
 		return nil, err
 	}

diff --git a/cmd/mungedocs/toc_test.go b/cmd/mungedocs/toc_test.go
@@ -29,8 +29,10 @@ func Test_buildTOC(t *testing.T) {
 	}{
 		{"", ""},
 		{"Lorem ipsum\ndolor sit amet\n", ""},
-		{"# Title\nLorem ipsum \n## Section Heading\ndolor sit amet\n",
-			"- [Title](#title)\n  - [Section Heading](#section-heading)\n"},
+		{
+			"# Title\nLorem ipsum \n## Section Heading\ndolor sit amet\n",
+			"- [Title](#title)\n  - [Section Heading](#section-heading)\n",
+		},
 	}
 	for _, c := range cases {
 		actual, err := buildTOC([]byte(c.in))
@@ -47,10 +49,14 @@ func Test_updateTOC(t *testing.T) {
 		out string
 	}{
 		{"", ""},
-		{"Lorem ipsum\ndolor sit amet\n",
-			"Lorem ipsum\ndolor sit amet\n"},
-		{"# Title\nLorem ipsum \n**table of contents**\n<!-- BEGIN GENERATED TOC -->\nold cruft\n<!-- END GENERATED TOC -->\n## Section Heading\ndolor sit amet\n",
-			"# Title\nLorem ipsum \n**table of contents**\n<!-- BEGIN GENERATED TOC -->\n- [Title](#title)\n  - [Section Heading](#section-heading)\n\n<!-- END GENERATED TOC -->\n## Section Heading\ndolor sit amet\n"},
+		{
+			"Lorem ipsum\ndolor sit amet\n",
+			"Lorem ipsum\ndolor sit amet\n",
+		},
+		{
+			"# Title\nLorem ipsum \n**table of contents**\n<!-- BEGIN MUNGE: GENERATED_TOC -->\nold cruft\n<!-- END MUNGE: GENERATED_TOC -->\n## Section Heading\ndolor sit amet\n",
+			"# Title\nLorem ipsum \n**table of contents**\n<!-- BEGIN MUNGE: GENERATED_TOC -->\n- [Title](#title)\n  - [Section Heading](#section-heading)\n\n<!-- END MUNGE: GENERATED_TOC -->\n## Section Heading\ndolor sit amet\n",
+		},
 	}
 	for _, c := range cases {
 		actual, err := updateTOC("filename.md", []byte(c.in))

diff --git a/cmd/mungedocs/unversioned_warning.go b/cmd/mungedocs/unversioned_warning.go
@@ -0,0 +1,48 @@
+/*
+Copyright 2015 The Kubernetes Authors All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package main
+
+const unversionedWarningTag = "UNVERSIONED_WARNING"
+
+var beginUnversionedWarning = beginMungeTag(unversionedWarningTag)
+var endUnversionedWarning = endMungeTag(unversionedWarningTag)
+
+const unversionedWarning = `
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<h1>*** PLEASE NOTE: This document applies to the HEAD of the source
+tree only. If you are using a released version of Kubernetes, you almost
+certainly want the docs that go with that version.</h1>
+
+<strong>Documentation for specific releases can be found at
+[releases.k8s.io](http://releases.k8s.io).</strong>
+
+<!-- END STRIP_FOR_RELEASE -->
+`
+
+// inserts/updates a warning for unversioned docs
+func updateUnversionedWarning(file string, markdown []byte) ([]byte, error) {
+	lines := splitLines(markdown)
+	if hasLine(lines, "<!-- TAG IS_VERSIONED -->") {
+		// No warnings on release branches
+		return markdown, nil
+	}
+	if !hasMacroBlock(lines, beginUnversionedWarning, endUnversionedWarning) {
+		lines = append([]string{beginUnversionedWarning, endUnversionedWarning}, lines...)
+	}
+	return updateMacroBlock(lines, beginUnversionedWarning, endUnversionedWarning, unversionedWarning)
+}
diff --git a/cmd/mungedocs/unversioned_warning_test.go b/cmd/mungedocs/unversioned_warning_test.go
@@ -0,0 +1,64 @@
+/*
+Copyright 2015 The Kubernetes Authors All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package main
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestUnversionedWarning(t *testing.T) {
+	warningBlock := beginUnversionedWarning + "\n" + unversionedWarning + "\n" + endUnversionedWarning + "\n"
+	var cases = []struct {
+		in  string
+		out string
+	}{
+		{"", warningBlock},
+		{
+			"Foo\nBar\n",
+			warningBlock + "Foo\nBar\n",
+		},
+		{
+			"Foo\n<!-- TAG IS_VERSIONED -->\nBar",
+			"Foo\n<!-- TAG IS_VERSIONED -->\nBar",
+		},
+		{
+			beginUnversionedWarning + "\n" + endUnversionedWarning + "\n",
+			warningBlock,
+		},
+		{
+			beginUnversionedWarning + "\n" + "something\n" + endUnversionedWarning + "\n",
+			warningBlock,
+		},
+		{
+			"Foo\n" + beginUnversionedWarning + "\n" + endUnversionedWarning + "\nBar\n",
+			"Foo\n" + warningBlock + "Bar\n",
+		},
+		{
+			"Foo\n" + warningBlock + "Bar\n",
+			"Foo\n" + warningBlock + "Bar\n",
+		},
+	}
+	for i, c := range cases {
+		actual, err := updateUnversionedWarning("filename.md", []byte(c.in))
+		assert.NoError(t, err)
+		if string(actual) != c.out {
+			t.Errorf("case[%d]: expected %q got %q", i, c.out, string(actual))
+		}
+	}
+}
diff --git a/cmd/mungedocs/util.go b/cmd/mungedocs/util.go
@@ -98,3 +98,15 @@ func hasMacroBlock(lines []string, begin string, end string) bool {
 	}
 	return false
 }
+
+// Returns the canonical begin-tag for a given description.  This does not
+// include the trailing newline.
+func beginMungeTag(desc string) string {
+	return fmt.Sprintf("<!-- BEGIN MUNGE: %s -->", desc)
+}
+
+// Returns the canonical end-tag for a given description.  This does not
+// include the trailing newline.
+func endMungeTag(desc string) string {
+	return fmt.Sprintf("<!-- END MUNGE: %s -->", desc)
+}
diff --git a/docs/README.md b/docs/README.md
@@ -1,8 +1,8 @@
-# Kubernetes Documentation: releases.k8s.io/HEAD
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
 
 <!-- BEGIN STRIP_FOR_RELEASE -->
 
-<h1>*** PLEASE NOTE: This documentation applies to the HEAD of the source
+<h1>*** PLEASE NOTE: This document applies to the HEAD of the source
 tree only. If you are using a released version of Kubernetes, you almost
 certainly want the docs that go with that version.</h1>
 
@@ -11,7 +11,8 @@ certainly want the docs that go with that version.</h1>
 
 <!-- END STRIP_FOR_RELEASE -->
 
-## Where to start
+<!-- END MUNGE: UNVERSIONED_WARNING -->
+# Kubernetes Documentation: releases.k8s.io/HEAD
 
 * The [User's guide](user-guide.md) is for anyone who wants to run programs and
   services on an existing Kubernetes cluster.

diff --git a/docs/accessing-the-cluster.md b/docs/accessing-the-cluster.md
@@ -1,3 +1,17 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<h1>*** PLEASE NOTE: This document applies to the HEAD of the source
+tree only. If you are using a released version of Kubernetes, you almost
+certainly want the docs that go with that version.</h1>
+
+<strong>Documentation for specific releases can be found at
+[releases.k8s.io](http://releases.k8s.io).</strong>
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
 # User Guide to Accessing the Cluster
  * [Accessing the cluster API](#api)
  * [Accessing services running on the cluster](#otherservices)

diff --git a/docs/accessing_the_api.md b/docs/accessing_the_api.md
@@ -1,3 +1,17 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<h1>*** PLEASE NOTE: This document applies to the HEAD of the source
+tree only. If you are using a released version of Kubernetes, you almost
+certainly want the docs that go with that version.</h1>
+
+<strong>Documentation for specific releases can be found at
+[releases.k8s.io](http://releases.k8s.io).</strong>
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
 # Configuring APIserver ports
 
 This document describes what ports the kubernetes apiserver

diff --git a/docs/admission_controllers.md b/docs/admission_controllers.md
@@ -1,3 +1,17 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<h1>*** PLEASE NOTE: This document applies to the HEAD of the source
+tree only. If you are using a released version of Kubernetes, you almost
+certainly want the docs that go with that version.</h1>
+
+<strong>Documentation for specific releases can be found at
+[releases.k8s.io](http://releases.k8s.io).</strong>
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
 # Admission Controllers
 
 ## What are they?

diff --git a/docs/annotations.md b/docs/annotations.md
@@ -1,3 +1,17 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<h1>*** PLEASE NOTE: This document applies to the HEAD of the source
+tree only. If you are using a released version of Kubernetes, you almost
+certainly want the docs that go with that version.</h1>
+
+<strong>Documentation for specific releases can be found at
+[releases.k8s.io](http://releases.k8s.io).</strong>
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
 # Annotations
 
 We have [labels](labels.md) for identifying metadata.

diff --git a/docs/api-conventions.md b/docs/api-conventions.md
@@ -1,3 +1,17 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<h1>*** PLEASE NOTE: This document applies to the HEAD of the source
+tree only. If you are using a released version of Kubernetes, you almost
+certainly want the docs that go with that version.</h1>
+
+<strong>Documentation for specific releases can be found at
+[releases.k8s.io](http://releases.k8s.io).</strong>
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
 API Conventions
 ===============
 

diff --git a/docs/api.md b/docs/api.md
@@ -1,3 +1,17 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<h1>*** PLEASE NOTE: This document applies to the HEAD of the source
+tree only. If you are using a released version of Kubernetes, you almost
+certainly want the docs that go with that version.</h1>
+
+<strong>Documentation for specific releases can be found at
+[releases.k8s.io](http://releases.k8s.io).</strong>
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
 # The Kubernetes API
 
 Primary system and API concepts are documented in the [User guide](user-guide.md).

diff --git a/docs/application-troubleshooting.md b/docs/application-troubleshooting.md
@@ -1,3 +1,17 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<h1>*** PLEASE NOTE: This document applies to the HEAD of the source
+tree only. If you are using a released version of Kubernetes, you almost
+certainly want the docs that go with that version.</h1>
+
+<strong>Documentation for specific releases can be found at
+[releases.k8s.io](http://releases.k8s.io).</strong>
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
 # Application Troubleshooting.
 
 This guide is to help users debug applications that are deployed into Kubernetes and not behaving correctly.

diff --git a/docs/authentication.md b/docs/authentication.md
@@ -1,3 +1,17 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<h1>*** PLEASE NOTE: This document applies to the HEAD of the source
+tree only. If you are using a released version of Kubernetes, you almost
+certainly want the docs that go with that version.</h1>
+
+<strong>Documentation for specific releases can be found at
+[releases.k8s.io](http://releases.k8s.io).</strong>
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
 # Authentication Plugins
 
 Kubernetes uses client certificates, tokens, or http basic auth to authenticate users for API calls.

diff --git a/docs/authorization.md b/docs/authorization.md
@@ -1,3 +1,17 @@
+<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
+
+<!-- BEGIN STRIP_FOR_RELEASE -->
+
+<h1>*** PLEASE NOTE: This document applies to the HEAD of the source
+tree only. If you are using a released version of Kubernetes, you almost
+certainly want the docs that go with that version.</h1>
+
+<strong>Documentation for specific releases can be found at
+[releases.k8s.io](http://releases.k8s.io).</strong>
+
+<!-- END STRIP_FOR_RELEASE -->
+
+<!-- END MUNGE: UNVERSIONED_WARNING -->
 # Authorization Plugins