It must to be clear to readers that design documents in the 'Contribute!' section do not describe current functionality of Bazel. If a reader comes to one of these pages from an online search, it must be clear that this is not documentation.

PiperOrigin-RevId: 152052655

17 files changed, 152 insertions, 44 deletions

diff --git a/site/designs/_posts/2015-03-06-bazel-init.md b/site/designs/_posts/2015-03-06-bazel-init.md
index a00df7aa05..1cd6f258ac 100644
--- a/site/designs/_posts/2015-03-06-bazel-init.md
+++ b/site/designs/_posts/2015-03-06-bazel-init.md
@@ -7,12 +7,18 @@ __This design document has been replaced by
 [Skylark Remote Repositories](/designs/2015/07/02/skylark-remote-repositories.html)
 and is maintained here just for reference__
 
-# bazel init a.k.a ./configure for Bazel
+# Design Document: bazel init a.k.a ./configure for Bazel
 _A configuration mechanism for Bazel_
 
-__Status:__ deprecated, replaced by [Skylark Remote Repositories](/designs/2015/07/02/skylark-remote-repositories.html)
+**Design documents are not descriptions of the current functionality of Bazel.
+Always go to the documentation for current information.**
 
-__Author:__ dmarting@google.com
+
+**Status:** deprecated, replaced by [Skylark Remote Repositories](/designs/2015/07/02/skylark-remote-repositories.html)
+
+**Author:** dmarting@google.com
+
+**Design document published**: 06 March 2015
 
 ## I. Rationale
 
diff --git a/site/designs/_posts/2015-07-02-skylark-remote-repositories.md b/site/designs/_posts/2015-07-02-skylark-remote-repositories.md
index 96e5fe0693..9038df85a5 100644
--- a/site/designs/_posts/2015-07-02-skylark-remote-repositories.md
+++ b/site/designs/_posts/2015-07-02-skylark-remote-repositories.md
@@ -3,13 +3,19 @@ layout: contribute
 title: Skylark Remote Repositories
 ---
 
-# Skylark Remote Repositories
+# Design Document: Skylark Remote Repositories
 
-__Status:__ implemented
+**Design documents are not descriptions of the current functionality of Bazel.
+Always go to the documentation for current information.**
 
-__Author:__ dmarting@google.com
 
-__Reviewers:__ lberki@google.com, laurentlb@google.com, kchodorow@google.com
+**Status:** implemented
+
+**Author:** dmarting@google.com
+
+**Reviewers:** lberki@google.com, laurentlb@google.com, kchodorow@google.com
+
+**Design document published**: 02 July 2015
 
 ## Context
 
diff --git a/site/designs/_posts/2016-02-16-cpp-autoconf.md b/site/designs/_posts/2016-02-16-cpp-autoconf.md
index 650efd9ec8..de42e17406 100644
--- a/site/designs/_posts/2016-02-16-cpp-autoconf.md
+++ b/site/designs/_posts/2016-02-16-cpp-autoconf.md
@@ -3,13 +3,19 @@ layout: contribute
 title: Generating C++ crosstool with a Skylark Remote Repository
 ---
 
-# Generating C++ crosstool with a Skylark Remote Repository
+# Design Document: Generating C++ crosstool with a Skylark Remote Repository
 
-__Status:__ implemented
+**Design documents are not descriptions of the current functionality of Bazel.
+Always go to the documentation for current information.**
 
-__Author:__ dmarting@google.com
 
-__Reviewers:__ lberki@google.com
+**Status:** implemented
+
+**Author:** dmarting@google.com
+
+**Reviewers:** lberki@google.com
+
+**Design document published**: 16 February 2016
 
 ## Context
 
diff --git a/site/designs/_posts/2016-05-23-beautiful-error-messages.md b/site/designs/_posts/2016-05-23-beautiful-error-messages.md
index 6f1852d8af..e8370e1a5a 100644
--- a/site/designs/_posts/2016-05-23-beautiful-error-messages.md
+++ b/site/designs/_posts/2016-05-23-beautiful-error-messages.md
@@ -3,15 +3,21 @@ layout: documentation
 title: Beautiful error messages
 ---
 
-# Beautiful error messages
+# Design Document: Beautiful error messages
 
-__Status__: Reviewed, not yet implemented
+**Design documents are not descriptions of the current functionality of Bazel.
+Always go to the documentation for current information.**
 
-__Author__: laurentlb@google.com
 
-__Reviewers__: ulfjack@google.com
+**Status**: Reviewed, not yet implemented
 
-__Related__: [Implementing beautiful error
+**Author**: laurentlb@google.com
+
+**Reviewers**: ulfjack@google.com
+
+**Design document published**: 23 May 2016
+
+**Related**: [Implementing beautiful error
 messages](/designs/2016/05/26/implementing-beautiful-error-messages.html)
 
 ## Background
diff --git a/site/designs/_posts/2016-05-26-implementing-beautiful-error-messages.md b/site/designs/_posts/2016-05-26-implementing-beautiful-error-messages.md
index 145fac5e9b..c07c665805 100644
--- a/site/designs/_posts/2016-05-26-implementing-beautiful-error-messages.md
+++ b/site/designs/_posts/2016-05-26-implementing-beautiful-error-messages.md
@@ -3,13 +3,19 @@ layout: contribute
 title: Implementing Beautiful Error Messages (Loading Phase)
 ---
 
-# Implementing Beautiful Error Messages (Loading Phase)
+# Design Document: Implementing Beautiful Error Messages (Loading Phase)
 
-__Author__: [laurentlb@google.com](mailto:laurentlb@google.com)
+**Design documents are not descriptions of the current functionality of Bazel.
+Always go to the documentation for current information.**
 
-__Status__: unimplemented
 
-__Related__: ["Beautiful error messages"](/designs/2016/05/23/beautiful-error-messages.html)
+**Status**: unimplemented
+
+**Author**: [laurentlb@google.com](mailto:laurentlb@google.com)
+
+**Design document published**: 26 May 2016
+
+**Related**: ["Beautiful error messages"](/designs/2016/05/23/beautiful-error-messages.html)
 
 ## Introduction
 
diff --git a/site/designs/_posts/2016-06-02-sandboxing.md b/site/designs/_posts/2016-06-02-sandboxing.md
index a063cc9ab1..579b115fff 100644
--- a/site/designs/_posts/2016-06-02-sandboxing.md
+++ b/site/designs/_posts/2016-06-02-sandboxing.md
@@ -3,11 +3,17 @@ layout: contribute
 title: Sandboxing
 ---
 
-# Bazel Sandboxing 2.0
+# Design Document: Bazel Sandboxing 2.0
 
-This doc was written by [philwo@google.com](mailto:philwo@google.com).
+**Design documents are not descriptions of the current functionality of Bazel.
+Always go to the documentation for current information.**
 
-Status: launched
+
+**Status:** launched
+
+**Author:** [philwo@google.com](mailto:philwo@google.com)
+
+**Design document published**: 02 June 2016
 
 The section "Handling of environment variables" inspired and was then
 superseded by the more detailed
diff --git a/site/designs/_posts/2016-06-21-environment.md b/site/designs/_posts/2016-06-21-environment.md
index 9a45f2a4ae..bf1e445b9c 100644
--- a/site/designs/_posts/2016-06-21-environment.md
+++ b/site/designs/_posts/2016-06-21-environment.md
@@ -3,12 +3,18 @@ layout: contribute
 title: Specifying environment variables
 ---
 
-# Specifying environment variables for actions
+# Design Document: Specifying environment variables for actions
+
+**Design documents are not descriptions of the current functionality of Bazel.
+Always go to the documentation for current information.**
+
 
 **Status**: Implemented. See [documentation](/docs/skylark/lib/ctx.html#action)
 
 **Author**: [Klaus Aehlig](mailto:aehlig@google.com)
 
+**Design document published**: 21 June 2016
+
 ## Current shortcomings
 
 Currently, Bazel provides a cleaned set of environment variables to the
diff --git a/site/designs/_posts/2016-08-04-extensibility-for-native-rules.md b/site/designs/_posts/2016-08-04-extensibility-for-native-rules.md
index 2b1c258587..1c05d4a5bb 100644
--- a/site/designs/_posts/2016-08-04-extensibility-for-native-rules.md
+++ b/site/designs/_posts/2016-08-04-extensibility-for-native-rules.md
@@ -2,12 +2,19 @@
 layout: contribute
 title: Extensibility For Native Rules
 ---
-# Extensibility For Native Rules
+
+# Design Document: Extensibility For Native Rules
+
+**Design documents are not descriptions of the current functionality of Bazel.
+Always go to the documentation for current information.**
+
 
 **Status**: Reviewed, not yet implemeted
 
 **Author**: [Dmitry Lomov](mailto:dslomov@google.com)
 
+**Design document published**: 04 August 2016
+
 ## Motivation
 
 There is a number of requests that require Skylark API to access functionality
diff --git a/site/designs/_posts/2016-09-05-build-python-on-windows.md b/site/designs/_posts/2016-09-05-build-python-on-windows.md
index 9018da50d6..312575c89e 100644
--- a/site/designs/_posts/2016-09-05-build-python-on-windows.md
+++ b/site/designs/_posts/2016-09-05-build-python-on-windows.md
@@ -2,12 +2,19 @@
 layout: contribute
 title: Building Python on Windows
 ---
-# Building Python on Windows
+
+# Design Document: Building Python on Windows
+
+**Design documents are not descriptions of the current functionality of Bazel.
+Always go to the documentation for current information.**
+
 
 **Status**: Implemented
 
 **Author**: [Yun Peng](mailto:pcloudy@google.com)
 
+**Design document published**: 05 September 2016
+
 **Relevant changes**:
 
 1. [zipper now can specify actual path a file is added to](https://bazel-review.googlesource.com/4243)
@@ -103,4 +110,4 @@ tree, it can be copied to anywhere as a self-contained executable binary.
 
 This flag can be used to tell Bazel whether or not it should build a zip file
 as the final binary. By default, it’s enabled on Windows,
-disabled on other platform.
\ No newline at end of file
+disabled on other platform.
diff --git a/site/designs/_posts/2016-09-19-recursive-ws-parsing.md b/site/designs/_posts/2016-09-19-recursive-ws-parsing.md
index f0fcd758c9..9261d3b3f5 100644
--- a/site/designs/_posts/2016-09-19-recursive-ws-parsing.md
+++ b/site/designs/_posts/2016-09-19-recursive-ws-parsing.md
@@ -2,12 +2,19 @@
 layout: contribute
 title: Recursive WORKSPACE file parsing
 ---
-# Recursive WORKSPACE file parsing
+
+# Design Document: Recursive WORKSPACE file parsing
+
+**Design documents are not descriptions of the current functionality of Bazel.
+Always go to the documentation for current information.**
+
 
 **Status**: Unimplemented
 
 **Author**: [kchodorow@](mailto:kchodorow@google.com)
 
+**Design document published**: 19 September 2016
+
 ## Objective
 
 Users are annoyed by having to specify all deps in their WORKSPACE file.  To
diff --git a/site/designs/_posts/2016-10-11-distribution-artifact.md b/site/designs/_posts/2016-10-11-distribution-artifact.md
index c0a20e848b..a1bbd9acca 100644
--- a/site/designs/_posts/2016-10-11-distribution-artifact.md
+++ b/site/designs/_posts/2016-10-11-distribution-artifact.md
@@ -3,12 +3,18 @@ layout: contribute
 title: Distribution Artifact for Bazel
 ---
 
-# Distribution Artifact for Bazel
+# Design Document: Distribution Artifact for Bazel
+
+**Design documents are not descriptions of the current functionality of Bazel.
+Always go to the documentation for current information.**
+
 
 **Status**: Implemented
 
 **Author**: [Klaus Aehlig](mailto:aehlig@google.com)
 
+**Design document published**: 11 October 2016
+
 ## Current State and Shortcomings
 
 
diff --git a/site/designs/_posts/2016-10-18-repository-invalidation.md b/site/designs/_posts/2016-10-18-repository-invalidation.md
index 0d851e5d34..fc0f8fec14 100644
--- a/site/designs/_posts/2016-10-18-repository-invalidation.md
+++ b/site/designs/_posts/2016-10-18-repository-invalidation.md
@@ -3,12 +3,18 @@ layout: contribute
 title: Invalidation of remote repositories
 ---
 
-# Invalidation of remote repositories
+# Design Document: Invalidation of remote repositories
+
+**Design documents are not descriptions of the current functionality of Bazel.
+Always go to the documentation for current information.**
+
 
 **Status**: Implemented
 
 **Author**: [Damien Martin-Guillerez](dmarting@google.com)
 
+**Design document published**: 18 October 2016
+
 ## State at commit [808a651](https://github.com/bazelbuild/bazel/commit/808a6518519501cfd32755a229d5dddf70e33557)
 
 [Remote repositories](/docs/external.html) are fetched the first
diff --git a/site/designs/_posts/2017-03-03-label-keyed-string-dict-type.md b/site/designs/_posts/2017-03-03-label-keyed-string-dict-type.md
index 76f6b00a67..4e0adbdc89 100644
--- a/site/designs/_posts/2017-03-03-label-keyed-string-dict-type.md
+++ b/site/designs/_posts/2017-03-03-label-keyed-string-dict-type.md
@@ -3,13 +3,19 @@ layout: contribute
 title: Label-keyed String Dictionary Type for Build Attributes
 ---
 
-# Label-keyed String Dictionary Type for Build Attributes
+# Design Document: Label-keyed String Dictionary Type for Build Attributes
+
+**Design documents are not descriptions of the current functionality of Bazel.
+Always go to the documentation for current information.**
+
 
 **Status**: Implemented in
 [5e9e194](https://github.com/bazelbuild/bazel/commit/5e9e1949f4c08ce09665b92aadf7ec7e518aab6a)
 
 **Author**: [Michael Staib](mstaib@google.com)
 
+**Design document published**: 03 March 2017
+
 ## Background/Motivation
 
 For future work in the realm of allowing Bazel users to define configuration
diff --git a/site/designs/index.md b/site/designs/index.md
index 70956d0f8c..efcf16aa42 100644
--- a/site/designs/index.md
+++ b/site/designs/index.md
@@ -3,7 +3,22 @@ layout: contribute
 title: Design Documents
 ---
 
-# Bazel Design Documents
+# Design Documents
+
+The design documents published here are part of a design process:
+
+1. Design is reviewed
+2. Design document is published here
+3. Design is implemented
+
+It's possible that designs change as they are implemented in practice. The
+design documents published here capture the initial design, and _not_ the
+ongoing changes as designs are implemented.
+
+Always go to the [documentation](/versions/master/docs/bazel-overview.md) for
+descriptions of current Bazel functionality.
+
+## Bazel Design Documents
 
 <ul>
 {% for doc in site.categories.designs %}
diff --git a/site/designs/skylark/declared-providers.md b/site/designs/skylark/declared-providers.md
index e64ffb7d41..9332970234 100644
--- a/site/designs/skylark/declared-providers.md
+++ b/site/designs/skylark/declared-providers.md
@@ -3,14 +3,18 @@ layout: documentation
 title: Declared Providers
 ---
 
-# Declared Providers
+# Design Document: Declared Providers
 
-Authors: [Dmitry Lomov](mailto:dslomov@google.com),
+**Design documents are not descriptions of the current functionality of Skylark.
+Always go to the documentation for current information.**
+
+
+**Authors:** [Dmitry Lomov](mailto:dslomov@google.com),
 [Laurent Le Brun](mailto:laurentlb@google.com)
 
-Status: Approved
+**Status:** Approved
 
-Date: 2016-06-06
+**Date:** 2016-06-06
 
 ## Motivation
 
diff --git a/site/designs/skylark/parameterized-aspects.md b/site/designs/skylark/parameterized-aspects.md
index b99af3f94d..24088e3cb7 100644
--- a/site/designs/skylark/parameterized-aspects.md
+++ b/site/designs/skylark/parameterized-aspects.md
@@ -3,14 +3,18 @@ layout: documentation
 title: Parameterized Skylark Aspects
 ---
 
-# Parameterized Skylark Aspects
+#  Design Document: Parameterized Skylark Aspects
 
-Author: [Dmitry Lomov](mailto:dslomov@google.com),
+**Design documents are not descriptions of the current functionality of Skylark.
+Always go to the documentation for current information.**
+
+
+**Author:** [Dmitry Lomov](mailto:dslomov@google.com),
 [Lindley French](mailto:lindleyf@google.com)
 
-Date: 2016-04-18
+**Date:** 2016-04-18
 
-Status: Approved (Proposal #2), Stage 1 implemented.
+**Status:** Approved (Proposal #2), Stage 1 implemented.
 
 
 **Proposal #2 is  approved **
diff --git a/site/designs/skylark/saner-skylark-sets.md b/site/designs/skylark/saner-skylark-sets.md
index bbc50148ad..98f158ecc6 100644
--- a/site/designs/skylark/saner-skylark-sets.md
+++ b/site/designs/skylark/saner-skylark-sets.md
@@ -3,15 +3,19 @@ layout: documentation
 title: Saner Skylark Sets
 ---
 
-# Saner Skylark Sets
+#  Design Document: Saner Skylark Sets
 
 ### (Sacrificing Superfluous Safety)
 
-Author: [Dmitry Lomov](mailto:dslomov@google.com)
+**Design documents are not descriptions of the current functionality of Skylark.
+Always go to the documentation for current information.**
 
-Date: 2016-07-25
 
-Status: Draft
+**Author:** [Dmitry Lomov](mailto:dslomov@google.com)
+
+**Date:** 2016-07-25
+
+**Status:** Draft
 
 ## Motivation