bug 1726652: add ADR scaffolding and symbolication microservice ADR

This adds the scaffolding for creating and maintaining ADRs. It adds an
ADR log to readthedocs.

It adds an ADR for breaking out the symbolication API as a microservice.

.log4brains.yml

@@ -0,0 +1,5 @@
+project:
+  name: Tecken
+  tz: Etc/UTC
+  adrFolder: ./docs/adr
+  packages: []

docs/_static/css/custom.css

@@ -0,0 +1,4 @@
+div.wy-nav-content {
+    /* This forces the content part to not get truncated */
+    max-width: 100% !important;
+}

docs/adr/20210819-use-log4brains-to-manage-the-adrs.md

@@ -0,0 +1,23 @@
+# Use Log4brains to manage the ADRs
+
+- Status: accepted
+- Deciders: Will Kahn-Greene
+- Date: 2021-08-18
+- Tags: dev-tools, doc
+
+## Context and Problem Statement
+
+We want to record architectural decisions made in this project.
+Which tool(s) should we use to manage these records?
+
+## Considered Options
+
+- [Log4brains](https://github.com/thomvaill/log4brains): architecture knowledge base (command-line + static site generator)
+- [ADR Tools](https://github.com/npryce/adr-tools): command-line to create ADRs
+- [ADR Tools Python](https://bitbucket.org/tinkerer_/adr-tools-python/src/master/): command-line to create ADRs
+- [adr-viewer](https://github.com/mrwilson/adr-viewer): static site generator
+- [adr-log](https://adr.github.io/adr-log/): command-line to create a TOC of ADRs
+
+## Decision Outcome
+
+Chosen option: "Log4brains", because it includes the features of all the other tools, and even more.

docs/adr/20210819-use-markdown-architectural-decision-records.md

@@ -0,0 +1,43 @@
+# Use Markdown Architectural Decision Records
+
+- Status: accepted
+- Deciders: Will Kahn-Greene
+- Date: 2021-08-18
+- Tags: doc
+
+## Context and Problem Statement
+
+We want to record architectural decisions made in this project.
+Which format and structure should these records follow?
+
+## Considered Options
+
+- [MADR](https://adr.github.io/madr/) 2.1.2 with Log4brains patch
+- [MADR](https://adr.github.io/madr/) 2.1.2 – The original Markdown Architectural Decision Records
+- [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR"
+- [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements
+- Other templates listed at <https://github.com/joelparkerhenderson/architecture_decision_record>
+- Formless – No conventions for file format and structure
+
+## Decision Outcome
+
+Chosen option: "MADR 2.1.2 with Log4brains patch", because
+
+- Implicit assumptions should be made explicit.
+  Design documentation is important to enable people understanding the decisions later on.
+  See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
+- The MADR format is lean and fits our development style.
+- The MADR structure is comprehensible and facilitates usage & maintenance.
+- The MADR project is vivid.
+- Version 2.1.2 is the latest one available when starting to document ADRs.
+- The Log4brains patch adds more features, like tags.
+
+The "Log4brains patch" performs the following modifications to the original template:
+
+- Change the ADR filenames format (`NNN-adr-name` becomes `YYYYMMDD-adr-name`), to avoid conflicts during Git merges.
+- Add a `draft` status, to enable collaborative writing.
+- Add a `Tags` field.
+
+## Links
+
+- Relates to [Use Log4brains to manage the ADRs](20210819-use-log4brains-to-manage-the-adrs.md)

docs/adr/20210820-symbolication-microservice.md

@@ -0,0 +1,66 @@
+# Symbolication API as a separate microservice
+
+- Status: accepted
+- Deciders: Will Kahn-Greene
+- Date: 2020-05-07
+- Tags: symbolication
+
+Proposal: https://docs.google.com/document/d/1U6FBFh9FsEWvUXf7DFzCBV4eCEjaBoxJbs9vtm6Lz6c/edit#
+
+Tracker bug: https://bugzilla.mozilla.org/show_bug.cgi?id=1636210
+
+## Context and Problem Statement
+
+Tecken is the Mozilla Symbols Server and includes upload, download, and
+symbolication API endpoints. In order to implement new features, we need to
+rewrite the code for the symbolication API. What form should that take?
+
+## Decision Drivers
+
+- support different performance and uptime requirements for the service
+
+## Considered Options
+
+- Option 1: keep symbolication API code in Tecken monolith service
+- Option 2: break symbolication API into a new microservice
+
+## Decision Outcome
+
+Chose "Option 2: break symbolication API into a new microservice" because
+the benefits of having it separate outweigh the additional maintenance costs of
+having it as a microservice.
+
+## Pros and Cons of the Options
+
+### Option 1: keep symbolication API code in Tecken monolith service
+
+The symbolication API is currently part of the Tecken monolithic service. We
+could keep it that way.
+
+Goods:
+
+- no additional maintenance costs
+
+Bads:
+
+- bursts of symbolication API usage continue to be a risk for upload API outage
+- when implementing this, we'll be switching to the Symbolic library and
+  keeping it in one big system makes that a little harder and more complex
+
+### Option 2: break symbolication API into a new microservice
+
+Tecken is a monolithic service that has upload, download, and symbolication
+APIs. We could break the symbolication API into a separate microservice that
+can run on its own.
+
+Goods:
+
+- we can scale the symbolication API microservice indepdently of the rest of Tecken
+- bursts of symbolication API usage won't affect the upload API uptime
+- potentially allows us to hand off just the symbolication API microservice to
+  another group to maintain
+
+Bads:
+
+- each separate service requires additional maintenance to keep going: separate
+  infrastructure, monitoring, deploy pipeline, project scaffolding, etc

docs/adr/README.md

@@ -0,0 +1,35 @@
+# Architecture Decision Records
+
+ADRs are automatically published to our Log4brains architecture knowledge base:
+
+🔗 **<http://INSERT-YOUR-LOG4BRAINS-URL>**
+
+Please use this link to browse them.
+
+## Development
+
+If not already done, install Log4brains:
+
+```bash
+npm install -g log4brains
+```
+
+To preview the knowledge base locally, run:
+
+```bash
+log4brains preview
+```
+
+In preview mode, the Hot Reload feature is enabled: any change you make to a markdown file is applied live in the UI.
+
+To create a new ADR interactively, run:
+
+```bash
+log4brains adr new
+```
+
+## More information
+
+- [Log4brains documentation](https://github.com/thomvaill/log4brains/tree/master#readme)
+- [What is an ADR and why should you use them](https://github.com/thomvaill/log4brains/tree/master#-what-is-an-adr-and-why-should-you-use-them)
+- [ADR GitHub organization](https://adr.github.io/)

docs/adr/index.md

@@ -0,0 +1,36 @@
+<!-- This file is the homepage of your Log4brains knowledge base. You are free to edit it as you want -->
+
+# Architecture knowledge base
+
+Welcome 👋 to the architecture knowledge base of Tecken.
+You will find here all the Architecture Decision Records (ADR) of the project.
+
+## Definition and purpose
+
+> An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant.
+> An Architectural Decision Record (ADR) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitutes its decision log.
+
+An ADR is immutable: only its status can change (i.e., become deprecated or superseded). That way, you can become familiar with the whole project history just by reading its decision log in chronological order.
+Moreover, maintaining this documentation aims at:
+
+- 🚀 Improving and speeding up the onboarding of a new team member
+- 🔭 Avoiding blind acceptance/reversal of a past decision (cf [Michael Nygard's famous article on ADRs](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html))
+- 🤝 Formalizing the decision process of the team
+
+## Usage
+
+This website is automatically updated after a change on the `master` branch of the project's Git repository.
+In fact, the developers manage this documentation directly with markdown files located next to their code, so it is more convenient for them to keep it up-to-date.
+You can browse the ADRs by using the left menu or the search bar.
+
+The typical workflow of an ADR is the following:
+
+![ADR workflow](/l4b-static/adr-workflow.png)
+
+The decision process is entirely collaborative and backed by pull requests.
+
+## More information
+
+- [Log4brains documentation](https://github.com/thomvaill/log4brains/tree/master#readme)
+- [What is an ADR and why should you use them](https://github.com/thomvaill/log4brains/tree/master#-what-is-an-adr-and-why-should-you-use-them)
+- [ADR GitHub organization](https://adr.github.io/)

docs/adr/template.md

@@ -0,0 +1,73 @@
+# [short title of solved problem and solution]
+
+- Status: [draft | proposed | rejected | accepted | deprecated | … | superseded by [xxx](yyyymmdd-xxx.md)] <!-- optional -->
+- Deciders: [list everyone involved in the decision] <!-- optional -->
+- Date: [YYYY-MM-DD when the decision was last updated] <!-- optional. To customize the ordering without relying on Git creation dates and filenames -->
+- Tags: [space and/or comma separated list of tags] <!-- optional -->
+
+Technical Story: [description | ticket/issue URL] <!-- optional -->
+
+## Context and Problem Statement
+
+[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.]
+
+## Decision Drivers <!-- optional -->
+
+- [driver 1, e.g., a force, facing concern, …]
+- [driver 2, e.g., a force, facing concern, …]
+- … <!-- numbers of drivers can vary -->
+
+## Considered Options
+
+- [option 1]
+- [option 2]
+- [option 3]
+- … <!-- numbers of options can vary -->
+
+## Decision Outcome
+
+Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)].
+
+### Positive Consequences <!-- optional -->
+
+- [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]
+- …
+
+### Negative Consequences <!-- optional -->
+
+- [e.g., compromising quality attribute, follow-up decisions required, …]
+- …
+
+## Pros and Cons of the Options <!-- optional -->
+
+### [option 1]
+
+[example | description | pointer to more information | …] <!-- optional -->
+
+- Good, because [argument a]
+- Good, because [argument b]
+- Bad, because [argument c]
+- … <!-- numbers of pros and cons can vary -->
+
+### [option 2]
+
+[example | description | pointer to more information | …] <!-- optional -->
+
+- Good, because [argument a]
+- Good, because [argument b]
+- Bad, because [argument c]
+- … <!-- numbers of pros and cons can vary -->
+
+### [option 3]
+
+[example | description | pointer to more information | …] <!-- optional -->
+
+- Good, because [argument a]
+- Good, because [argument b]
+- Bad, because [argument c]
+- … <!-- numbers of pros and cons can vary -->
+
+## Links <!-- optional -->
+
+- [Link type](link to adr) <!-- example: Refined by [xxx](yyyymmdd-xxx.md) -->
+- … <!-- numbers of links can vary -->

docs/adr_log.rst

@@ -0,0 +1,12 @@
+=======
+ADR Log
+=======
+
+This is a log of Architecture Decision Records for critical architecture
+decisions in Tecken.
+
+See `<https://github.com/mozilla-services/tecken/tree/main/docs/adr>`_ for
+details on how we create and maintain these records.
+
+.. adrlog:: adr/
+   :urlroot: https://github.com/mozilla-services/tecken/tree/main/docs/adr

docs/conf.py

@@ -51,6 +51,7 @@
     "sphinxcontrib.httpdomain",
     "everett.sphinxext",
     "exts.eliot_metrics",
+    "exts.adr_log",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -162,7 +163,9 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 # html_static_path = ['_static']
-html_static_path = []
+html_static_path = ["_static"]
+
+html_css_files = ["css/custom.css"]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied