Merge pull request #13 from rust-lang/vision-doc

nikomatsakis · web-flow · commit 4ab35397428c · 2021-05-25T11:32:45.000-04:00
Vision doc template
diff --git a/CHARTER.md b/CHARTER.md
@@ -1,4 +1,4 @@
-# Const Generics Charter
+# 📜  Const Generics Charter
 
 The goal of this group is to both improve and extend the support for const generics.
 
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# Const Generics Project Group
+# 👋🏽 Const Generics Project Group
 
 <!--
  Status badge advertising the project as being actively worked on. When the
@@ -33,19 +33,12 @@ fn main() {
 }
 ```
 
-<!--
-FIXME(website): do we want a website for this?
-
 Welcome to the repository for the Const Generics Project Group! This is the
 repository we use to organise our work. Please refer to our [charter] as well
 as our [github pages website][gh-pages] for more information on our goals and
 current scope.
 [gh-pages]: https://rust-lang.github.io/{{GROUP_SLUG}}
 
-
-**/FIX ME**
--->
-
 [charter]: ./CHARTER.md
 
 
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -1,6 +1,11 @@
 # Summary
 
-- [Welcome](./README.md)
-- [Charter](./CHARTER.md)
-- [Meetings](./meetings/README.md)
-- [Draft RFCs](./draft-rfcs/README.md)
+- [👋🏽 Welcome](./README.md)
+- [📜 Charter](./CHARTER.md)
+- [🔮 The vision](./vision.md)
+   - [🙋‍♀️ Cast of characters](./vision/characters.md)
+   - [😱 Status quo](./vision/status_quo.md)
+   - [✨ Shiny future](./vision/shiny_future.md)
+   - [📅 Roadmap for 2021](./vision/roadmap.md)
+   - [❓How to vision doc](./vision/how_to_vision_doc.md)- [Meetings](./meetings/README.md)
+- [✏️ Draft RFCs](./draft-rfcs/README.md)
diff --git a/book.toml b/book.toml
@@ -1,10 +1,10 @@
 [book]
-authors = ["{{GROUP_NAME}} Members"]
+authors = ["Const Generics Project Group Members"]
 language = "en"
 multilingual = false
 src = "."
-title = "{{GROUP_NAME}} {{GROUP_TYPE}} Group"
+title = "Const Generics Project Group"
 
 [output.html]
 no-section-label=true
-git-repository-url="https://github.com/rust-lang/{{GROUP_SLUG}}"
+git-repository-url="https://github.com/rust-lang/project-const-generics"
diff --git a/draft-rfcs/README.md b/draft-rfcs/README.md
@@ -1,4 +1,4 @@
-# RFC drafts
+# ✏️ RFC drafts
 
 This folder contains drafts of RFCs that the group is preparing to submit.
 
diff --git a/vision.md b/vision.md
@@ -0,0 +1,15 @@
+# 🔮 The vision
+
+## What is this
+
+This section lays out a general vision and set of goals for Const Generics in Rust. 
+
+## Status and schedule
+
+**This document is currently being formed.** 
+
+## This is a group effort
+
+As the leads of the Async Foundation group, Niko and Tyler are driving and organizing this document. But writing it and shaping it is a group effort. If you think there is a part of the async experience that is not reflected here, we want to hear from you! Check out the [How to vision doc] for more details on how to contribute.
+
+[How to vision doc]: ./vision/how_to_vision_doc.md
diff --git a/vision/characters.md b/vision/characters.md
@@ -0,0 +1 @@
+# 🙋‍♀️ Cast of characters
diff --git a/vision/how_to_vision_doc.md b/vision/how_to_vision_doc.md
@@ -0,0 +1,19 @@
+# ❓ How to vision doc
+
+This page describes the process for contributing to the vision doc.
+
+[sq]: status_quo.md
+[sf]: shiny_future.md
+[r]: roadmap.md
+[dd]: ../design_docs.md
+
+## Who owns this document?
+
+This document is owned and maintained by the leads of the Const Generics Working Group.
+They decide what content to accept or reject. 
+This decision is made in consultation with the Rust teams that will be making the ultimate decisions. 
+For example, if a design doc or part of the shiny future is describing a new language feature, the leads ought to  discuss that with the language design team, since that team will ultimately have to approve the RFCs for its design.
+
+## How to participate
+
+For now, you have to join our weekly meetings.
diff --git a/vision/roadmap.md b/vision/roadmap.md
@@ -0,0 +1,22 @@
+# 📅 The roadmap: what we're doing in 2021
+
+This page describes the current plans for 2021.
+It is updated on a monthly basis.
+
+## Key
+
+| Emoji | Meaning |
+| --- | --- |
+| 🥬 | "Healthy" -- on track with the plan as described in the doc |
+| ✏️ |  "Planning" -- Still figuring out the plan |
+| 🤒 | "Worried" -- things are looking a bit tricky, plans aren't working out |
+| 🏖️ | "On vacation" -- taking a break right now |
+| ⚰️ | We gave up on this idea =) |
+
+## Roadmap items
+
+| Plan | Owner | Status | Last updated
+| --- | --- | --- | --- |
+| [Async functions in traits] | nikomatsakis | 🥬 | 2021-02 |
+
+[Async functions in traits]: ../design_docs/async_fns_in_traits.md
diff --git a/vision/shiny_future.md b/vision/shiny_future.md
@@ -0,0 +1,7 @@
+# ✨ Shiny future: Where we want to get to
+
+The "shiny future" is here to tell you what we are trying to build over the next 2-3 years. That is, it presents our "best guess" as to what will look like a few years from now. When describing specific features, it also embeds links to [design notes] that describe the constraints and general plans around that feature.
+
+[design notes]: ../design_notes.md
+
+Predicting the future is a tricky business! Many of the things described in the "shiny future" doc have a lot of uncertainty. We fully expect that the designs and narratives described in this document will change as we work towards realizing them. When there are areas of particular uncertainty, we use the Frequently Asked Questions and the design docs to call them out.
diff --git a/vision/status_quo.md b/vision/status_quo.md
@@ -0,0 +1,29 @@
+# 😱 Status quo stories
+
+## What is this
+
+The "status quo" stores are here to state our "theory of the case". That is, they present (and prove) our hypotheses as to what the various challenges are for users of Async I/O in Rust. These hypotheses are presented in narrative form, by telling the story of a specific [character] as they try (and typically fail in dramatic fashion) to achieve their goals.
+
+[character]: ./characters.md
+
+### Based on a true story
+
+These stories are not made up. They are always based on real-life experiences of actual people. Each story contains a "Frequently Asked Questions" section, and that will include notes the sources used to create the story. In some cases, it may link to notes or summaries in the [conversations] section, though that is not required. The "Frequently Asked Questions" section also contains a summary of what the "morals" of the story are (i.e., what are the key takeaways), along with answers to questions that people have raised along the way.
+
+[conversations]: ../conversations.md
+
+### The stories provide data we use to prioritize, not a prioritization itself
+
+**Just because a user story is represented here doesn't mean we're going to be able to fix it right now.** Some of these user stories will indicate more severe problems than others. As we consider the stories, we'll select some subset to try and address; that choice is reflected in the [roadmap].
+
+[roadmap]: ./roadmap.md
+
+### Help wanted!
+
+This is not a static document! There are lots of ways you can help to expand it! Take a look at the [How to Vision Doc](./how_to_vision_doc.md) for more details.
+
+[Alan]: ./characters.md#alan-the-startup-guy-trying-to-stand-up-a-web-stack-quickly
+[Grace]: ./characters.md#grace-the-principal-engineer-hacking-on-t4-a-new-storage-service
+[Niklaus]: ./characters.md#niklaus-the-developer-building-generic-rust-libraries-and-frameworks
+[Barbara]: ./characters.md#barbara-embedded-developer-doing-networking
+[Volunteer wanted]: ./how_to_vision_doc.md#how-can-i-finish-or-add-a-section-to-the-document

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Const Generics Charter`
	`1`	`+# 📜 Const Generics Charter`
`2`	`2`
`3`	`3`	`The goal of this group is to both improve and extend the support for const generics.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# RFC drafts`
	`1`	`+# ✏️ RFC drafts`
`2`	`2`
`3`	`3`	`This folder contains drafts of RFCs that the group is preparing to submit.`
`4`	`4`