Add known-bug header. (#1311)

src/tests/headers.md

@@ -87,6 +87,8 @@ found in [`header.rs`] from the compiletest source.
     * [`revisions`](compiletest.md#revisions) — compile multiple times
     * [`forbid-output`](compiletest.md#incremental-tests) — incremental cfail rejects output pattern
     * [`should-ice`](compiletest.md#incremental-tests) — incremental cfail should ICE
+    * [`known-bug`](ui.md#known-bugs) — indicates that the test is
+      for a known bug that has not yet been fixed
 * [Assembly](compiletest.md#assembly-tests) headers
     * `assembly-output` — the type of assembly output to check
 

src/tests/ui.md

@@ -394,6 +394,21 @@ The `ignore-pass` header can be used to ignore the `--pass` CLI flag if the
 test won't work properly with that override.
 
 
+## Known bugs
+
+The `known-bug` header may be used for tests that demonstrate a known bug that
+has not yet been fixed.
+Adding tests for known bugs is helpful for several reasons, including:
+
+1. Maintaining a functional test that can be conveniently reused when the bug is fixed.
+2. Providing a sentinel that will fail if the bug is incidentally fixed.
+   This can alert the developer so they know that the associated issue has
+   been fixed and can possibly be closed.
+
+Do not include [error annotations](#error-annotations) in a test with `known-bug`.
+The test should still include other normal headers and stdout/stderr files.
+
+
 ## Test organization
 
 When deciding where to place a test file, please try to find a subdirectory