docs: Move version history to top level out of intro (#10730)

Signed-off-by: Greg Greenway <ggreenway@apple.com>

.gitattributes

@@ -1,4 +1,4 @@
-/docs/root/intro/version_history.rst merge=union
+/docs/root/version_history/current.rst merge=union
 *.generated.pb_text linguist-generated=true
 *.generated.pb_text -diff -merge
 /generated_api_shadow/envoy/** linguist-generated=true

CONTRIBUTING.md

@@ -88,7 +88,7 @@ versioning guidelines:
   build. If your PR cannot have 100% coverage for some reason please clearly explain why when you
   open it.
 * Any PR that changes user-facing behavior **must** have associated documentation in [docs](docs) as
-  well as [release notes](docs/root/intro/version_history.rst). API changes should be documented
+  well as [release notes](docs/root/version_history/current.rst). API changes should be documented
   inline with protos as per the [API contribution guidelines](api/CONTRIBUTING.md).
 * All code comments and documentation are expected to have proper English grammar and punctuation.
   If you are not a fluent English speaker (or a bad writer ;-)) please let us know and we will try

GOVERNANCE.md

@@ -79,12 +79,12 @@ or you can subscribe to the iCal feed [here](https://app.opsgenie.com/webcal/get
 * Begin marshalling the ongoing PR flow in this repo. Ask maintainers to hold off merging any
   particularly risky PRs until after the release is tagged. This is because we aim for master to be
   at release candidate quality at all times.
-* Do a final check of the [release notes](docs/root/intro/version_history.rst):
+* Do a final check of the [release notes](docs/root/version_history/current.rst):
   * Make any needed corrections (grammar, punctuation, formatting, etc.).
   * Check to see if any security/stable version release notes are duplicated in
     the major version release notes. These should not be duplicated.
-  * Remove the "Pending" tags and add dates to the top of the [release notes](docs/root/intro/version_history.rst)
-    and [deprecated log](docs/root/intro/deprecated.rst).
+  * If the "Deprecated" section is empty, delete it.
+  * Remove the "Pending" tags and add dates to the top of the [release notes for this version](docs/root/version_history/current.rst).
   * Switch the [VERSION](VERSION) from a "dev" variant to a final variant. E.g., "1.6.0-dev" to
     "1.6.0".
   * Get a review and merge.
@@ -100,10 +100,24 @@ or you can subscribe to the iCal feed [here](https://app.opsgenie.com/webcal/get
 * Craft a witty/uplifting email and send it to all the email aliases including envoy-announce@.
 * If possible post on Twitter (either have Matt do it or contact caniszczyk@ on Slack and have the
   Envoy account post).
-* Do a new PR to update [VERSION](VERSION) to the next development release. E.g., "1.7.0-dev". At
-  the same time, also add a new empty "pending" section to the [release
-  notes](docs/root/intro/version_history.rst) and to [deprecated log](docs/root/intro/deprecated.rst) for the
-  following version. E.g., "1.7.0 (pending)".
+* Do a new PR to setup the next version
+  * Update [VERSION](VERSION) to the next development release. E.g., "1.7.0-dev". 
+  * `git mv docs/root/version_history/current.rst docs/root/version_history/v1.6.0.rst`, filling in the previous
+    release version number in the filename, and add an entry for the new file in the `toctree` in 
+    [version_history.rst](docs/root/version_history/version_history.rst).
+  * Create a new "current" version history file at the [release
+  notes](docs/root/version_history/current.rst) for the following version. E.g., "1.7.0 (pending)". Use
+  this text as the template for the new file:
+```
+1.7.0 (Pending)
+===============
+
+Changes
+-------
+
+Deprecated
+----------
+```
 * Run the deprecate_versions.py script (e.g. `sh tools/deprecate_version/deprecate_version.sh`)
   to file tracking issues for code which can be removed.
 * Run the deprecate_features.py script (e.g. `sh tools/deprecate_features/deprecate_features.sh`)

PULL_REQUESTS.md

@@ -54,10 +54,10 @@ N/A if there were no documentation changes.
 ### <a name="relnotes"></a>Release notes
 
 If this change is user impacting OR extension developer impacting (filter API, etc.) you **must**
-add a release note to [version_history.rst](docs/root/intro/version_history.rst). Please include
-any relevant links. Each release note should be prefixed with the relevant subsystem in
-**alphabetical order** (see existing examples as a guide) and include links to relevant parts of the
-documentation. Thank you! Please write in N/A if there are no release notes.
+add a release note to the [version history](docs/root/version_history/current.rst) for the 
+current version. Please include any relevant links. Each release note should be prefixed with the
+relevant subsystem in **alphabetical order** (see existing examples as a guide) and include links
+to relevant parts of the documentation. Thank you! Please write in N/A if there are no release notes.
 
 ### <a name="issues"></a>Issues
 

docs/build.sh

@@ -16,10 +16,10 @@ then
     exit 1
   fi
   # Check the version_history.rst contains current release version.
-  grep --fixed-strings "$VERSION_NUMBER" docs/root/intro/version_history.rst \
-    || (echo "Git tag not found in version_history.rst" && exit 1)
+  grep --fixed-strings "$VERSION_NUMBER" docs/root/version_history/current.rst \
+    || (echo "Git tag not found in version_history/current.rst" && exit 1)
 
-  # Now that we now there is a match, we can use the tag.
+  # Now that we know there is a match, we can use the tag.
   export ENVOY_DOCS_VERSION_STRING="tag-$CIRCLE_TAG"
   export ENVOY_DOCS_RELEASE_LEVEL=tagged
   export ENVOY_BLOB_SHA="$CIRCLE_TAG"

docs/root/index.rst

@@ -15,6 +15,7 @@ Envoy documentation
   intro/intro
   start/start
   install/install
+  version_history/version_history
   configuration/configuration
   operations/operations
   extending/extending