Generics goals

docs/design/generics/README.md

@@ -0,0 +1,17 @@
+# Carbon: Generics
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+This directory contains the collection of documents describing the generics
+feature of Carbon:
+
+-   ~~Overview~~ - not implemented yet
+-   [Goals](goals.md) - The motivation and principles guiding the design
+    direction.
+-   ~~Terminology~~ - not implemented yet
+-   ~~Detailed design~~ - not implemented yet
+-   ~~Rejected alternatives~~ - not implemented yet

proposals/README.md

@@ -23,6 +23,7 @@ request:
 <!-- proposals -->
 <!-- Generated by ./scripts/update_proposal_list.py -->
 
+-   [0024 - Generics goals](p0024.md)
 -   [0029 - Linear, rebase, and pull-request GitHub workflow](p0029.md)
     -   [0029 - Decision](p0029_decision.md)
 -   [0042 - Create code review guidelines](p0042.md)

proposals/p0024.md

@@ -0,0 +1,38 @@
+# Generics goals
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+[Pull request](https://github.com/carbon-language/carbon-lang/pull/24)
+
+## Problem
+
+The "generics" feature of Carbon is a large design effort that needs to be
+broken up into manageable steps. The first thing we need is a high-level goals
+document:
+
+-   to make sure we agree on the approach we are taking,
+-   to clearly communicate expectations to contributors for future steps,
+-   to encourage us to solve problems in the design in a consistent way,
+-   to provide a yardstick for measuring different alternatives under
+    consideration.
+
+## Background
+
+The question of what a generics feature would look like in Carbon has been an
+ongoing discussion, with many alternative proposals. Of course there have been a
+number of use cases that we want to address with this feature, but over the
+course of this process we have discovered a number of desirable properties we
+would like to achieve with any solution.
+
+## Proposal
+
+See the [generics goals document](/docs/design/generics/goals.md).
+
+## Rationale
+
+The goals here well reflect Carbon's goals as applied to the specifics of the
+generics feature.

proposals/scripts/proposals_test.py

@@ -17,12 +17,19 @@ def test_get_path(self):
         p = proposals.get_list(proposals_path)
         self.assertEqual(
             p[0],
+            (
+                "0024 - Generics goals",
+                "p0024.md",
+            ),
+        )
+        self.assertEqual(
+            p[1],
             (
                 "0029 - Linear, rebase, and pull-request GitHub workflow",
                 "p0029.md",
             ),
         )
-        self.assertEqual(p[1], ("0029 - Decision", "p0029_decision.md"))
+        self.assertEqual(p[2], ("0029 - Decision", "p0029_decision.md"))
 
 
 if __name__ == "__main__":

website/jekyll/gen_sidebar.py

@@ -178,7 +178,7 @@ def crawl(top):
         rel_dir = os.path.relpath(parent_dir, top)
         readme, files = list(_filter_files(parent_dir, rel_dir, raw_files))
         if readme is None:
-            assert not files
+            assert not files, "Every directory under docs/ needs a README.md."
             continue
 
         # Sort and put the README first when setting up the dir.

website/jekyll/gen_sidebar_test.py

@@ -64,13 +64,20 @@ def test_crawl(self):
         )
         self.assertEqual(
             proposals.files[1],
+            (
+                "0024 - Generics goals",
+                "/proposals/p0024.md",
+            ),
+        )
+        self.assertEqual(
+            proposals.files[2],
             (
                 "0029 - Linear, rebase, and pull-request GitHub workflow",
                 "/proposals/p0029.md",
             ),
         )
         self.assertEqual(
-            proposals.files[2],
+            proposals.files[3],
             ("0029 - Decision", "/proposals/p0029_decision.md"),
         )