From 418614c1c509a3c9700f75aa6e40b55e4a882dd4 Mon Sep 17 00:00:00 2001
From: Jean-Paul Calderone <exarkun@twistedmatrix.com>
Date: Mon, 8 Nov 2021 09:23:20 -0500
Subject: [PATCH] add a rst version of our design template

This is based on the version in google docs.
It has some changes informed by our experience using the template so far.
---
 docs/dev/designs/index.rst    |  7 +++
 docs/dev/designs/template.rst | 95 +++++++++++++++++++++++++++++++++++
 docs/index.rst                |  5 +-
 3 files changed, 106 insertions(+), 1 deletion(-)
 create mode 100644 docs/dev/designs/index.rst
 create mode 100644 docs/dev/designs/template.rst

diff --git a/docs/dev/designs/index.rst b/docs/dev/designs/index.rst
new file mode 100644
index 00000000..84993e1b
--- /dev/null
+++ b/docs/dev/designs/index.rst
@@ -0,0 +1,7 @@
+System Designs
+--------------
+
+.. toctree::
+   :maxdepth: 2
+
+   System Design Template <template>
diff --git a/docs/dev/designs/template.rst b/docs/dev/designs/template.rst
new file mode 100644
index 00000000..8fbc2a58
--- /dev/null
+++ b/docs/dev/designs/template.rst
@@ -0,0 +1,95 @@
+$HEADLINE
+=========
+
+*The goal is to do the least design we can get away with while still making a quality product.*
+*Think of this as a tool to help define the problem, analyze solutions, and share results.*
+*Feel free to skip sections that you don't think are relevant*
+*(but say that you are doing so).*
+*Delete the bits in italics*
+
+**Contacts:** *The primary contacts for this design.*
+**Date:** *The last time this design was modified.  YYYY-MM-DD*
+
+*Short description of the feature.*
+*Consider clarifying by also describing what it is not.*
+
+Rationale
+---------
+
+*Why are we doing this now?*
+*What value does this give to our users?*
+*Which users?*
+
+User Stories
+------------
+
+**$STORY NAME**
+
+**Category:** *must / nice to have / must not*
+
+As a **$PERSON** I want **$FEATURE** so that **$BENEFIT**.
+
+**Acceptance Criteria:**
+
+  * *What concrete conditions must be met for the implementation to be acceptable?*
+  * *Surface assumptions about the user story that may not be shared across the team.*
+  * *Describe failure modes and negative scenarios when preconditions for using the feature are not met.*
+  * *Place the story in a performance/scaling context with real numbers.*
+
+*Have as many as you like.*
+*Group user stories together into meaningfully deliverable units.*
+
+*Gather Feedback*
+-----------------
+
+*It might be a good idea to stop at this point & get feedback to make sure you're solving the right problem.*
+
+Alternatives Considered
+-----------------------
+
+*What we've considered.*
+*What trade-offs are involved with each choice.*
+*Why we've chosen the one we did.*
+
+Detailed Implementation Design
+------------------------------
+
+*Focus on:*
+
+* external and internal interfaces
+* how externally-triggered system events (e.g. sudden reboot; network congestion) will affect the system
+* scalability and performance
+
+Data Integrity
+~~~~~~~~~~~~~~
+
+*If we get this wrong once, we lose forever.*
+*What data does the system need to operate on?*
+*How will old data be upgraded to meet the requirements of the design?*
+*How will data be upgraded to future versions of the implementation?*
+
+Security
+~~~~~~~~
+
+*What threat model does this design take into account?*
+*What new attack surfaces are added by this design?*
+*What defenses are deployed with the implementation to keep those surfaces safe?*
+
+Backwards Compatibility
+~~~~~~~~~~~~~~~~~~~~~~~
+
+*What existing systems are impacted by these changes?*
+*How does the design ensure they will continue to work?*
+
+Performance and Scalability
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+*How will performance of the implementation be measured?*
+
+*After measuring it, record the results here.*
+
+Further Reading
+---------------
+
+*Links to related things.*
+*Other designs, tickets, epics, mailing list threads, etc.*
diff --git a/docs/index.rst b/docs/index.rst
index eb6b59ec..c95dc579 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,13 +6,16 @@
 Welcome to PrivateStorageio's documentation!
 ============================================
 
-Howdy!  We separated the documentation into parts addressing different audiences.  Please enjoy our docs for:
+Howdy!
+We separated the documentation into parts addressing different audiences.
+Please enjoy our docs for:
 
 .. toctree::
    :maxdepth: 2
 
    Administrators <ops/README>
    Developers <dev/README>
+   System Designs <dev/designs/index>
 
 
 Naming
-- 
GitLab