chore(adrs): initial setup of docs/adr using MADR format

2019-05-07 11:02:40 -04:00 · 2019-05-07 11:02:40 -04:00 · ebf0ca77a4
--- a/docs/adr/0000-use-markdown-architectural-decision-records.md
+++ b/docs/adr/0000-use-markdown-architectural-decision-records.md
@ -0,0 +1,26 @@
+# Use Markdown Architectural Decision Records
+
+## 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 – The 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", 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.
--- a/docs/adr/index.md
+++ b/docs/adr/index.md
@ -0,0 +1,13 @@
+# Architectural Decision Log
+
+This log lists the architectural decisions for [project name].
+
+<!-- adrlog -- Regenerate the content by using "adr-log -i". You can install it via "npm install -g adr-log" -->
+
+- [ADR-0000](0000-use-markdown-architectural-decision-records.md) - Use Markdown Architectural Decision Records
+
+<!-- adrlogstop -->
+
+For new ADRs, please use [template.md](template.md) as basis.
+More information on MADR is available at <https://adr.github.io/madr/>.
+General information about architectural decision records is available at <https://adr.github.io/>.
--- a/docs/adr/template.md
+++ b/docs/adr/template.md
@ -0,0 +1,72 @@
+# [short title of solved problem and solution]
+
+* Status: [proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)] <!-- optional -->
+* Deciders: [list everyone involved in the decision] <!-- optional -->
+* Date: [YYYY-MM-DD when the decision was last updated] <!-- 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 [ADR-0005](0005-example.md) -->
+* … <!-- numbers of links can vary -->
--- a/package-lock.json
+++ b/package-lock.json
@ -1180,6 +1180,20 @@
      "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-1.1.1.tgz",
      "integrity": "sha512-nne9/IiQ/hzIhY6pdDnbBtz7DjPTKrY00P/zvPSm5pOFkl6xuGrGnXn/VtTNNfNtAfZ9/1RtehkszU9qcTii0Q=="
    },
+    "adr-log": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/adr-log/-/adr-log-2.1.1.tgz",
+      "integrity": "sha512-TvxITz0Uv0PBEdwfMdMxudgkiZnyAEprphdvx+ZUYGur42pliST5JCKGwb+xDSw0jxRRfZjXAMsA/tJ3DJO+AA==",
+      "requires": {
+        "console-stamp": "^0.2.6",
+        "glob": "^7.1.2",
+        "gray-matter": "^2.1.0",
+        "lazy-cache": "^2.0.2",
+        "minimist": "^1.2.0",
+        "path": "^0.12.7",
+        "remarkable": "^1.7.1"
+      }
+    },
    "agent-base": {
      "version": "4.2.1",
      "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-4.2.1.tgz",
@ -1225,6 +1239,14 @@
      "resolved": "https://registry.npmjs.org/ansi-escapes/-/ansi-escapes-3.2.0.tgz",
      "integrity": "sha512-cBhpre4ma+U0T1oM5fXg7Dy1Jw7zzwv7lt/GoCpr+hDQJoYnKVPLL4dCvSEFMmQurOQvSrwT7SL/DAlhBI97RQ=="
    },
+    "ansi-red": {
+      "version": "0.1.1",
+      "resolved": "https://registry.npmjs.org/ansi-red/-/ansi-red-0.1.1.tgz",
+      "integrity": "sha1-jGOPnRCAgAo1PJwoyKgcpHBdlGw=",
+      "requires": {
+        "ansi-wrap": "0.1.0"
+      }
+    },
    "ansi-regex": {
      "version": "2.1.1",
      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-2.1.1.tgz",
@ -1235,6 +1257,11 @@
      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-2.2.1.tgz",
      "integrity": "sha1-tDLdM1i2NM914eRmQ2gkBTPB3b4="
    },
+    "ansi-wrap": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/ansi-wrap/-/ansi-wrap-0.1.0.tgz",
+      "integrity": "sha1-qCJQ3bABXponyoLoLqYDu/pF768="
+    },
    "anymatch": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/anymatch/-/anymatch-2.0.0.tgz",
@ -1430,6 +1457,11 @@
      "resolved": "https://registry.npmjs.org/atob/-/atob-2.1.2.tgz",
      "integrity": "sha512-Wm6ukoaOGJi/73p/cl2GvLjTI5JM1k/O14isD73YML8StrH/7/lRFgmg8nICZgD3bZZvjwCGxtMOD3wWNAu8cg=="
    },
+    "autolinker": {
+      "version": "0.15.3",
+      "resolved": "https://registry.npmjs.org/autolinker/-/autolinker-0.15.3.tgz",
+      "integrity": "sha1-NCQX2PLzRhsUzwkIjV7fh5HcmDI="
+    },
    "aws-sign2": {
      "version": "0.7.0",
      "resolved": "https://registry.npmjs.org/aws-sign2/-/aws-sign2-0.7.0.tgz",
@ -1878,6 +1910,11 @@
      "resolved": "https://registry.npmjs.org/code-point-at/-/code-point-at-1.1.0.tgz",
      "integrity": "sha1-DQcLTQQ6W+ozovGkDi7bPZpMz3c="
    },
+    "coffee-script": {
+      "version": "1.12.7",
+      "resolved": "https://registry.npmjs.org/coffee-script/-/coffee-script-1.12.7.tgz",
+      "integrity": "sha512-fLeEhqwymYat/MpTPUjSKHVYYl0ec2mOyALEMLmzr5i1isuG+6jfI2j2d5oBO3VIzgUXgBVIcOT9uH1TFxBckw=="
+    },
    "collection-visit": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/collection-visit/-/collection-visit-1.0.0.tgz",
@ -2005,6 +2042,16 @@
      "resolved": "https://registry.npmjs.org/console-control-strings/-/console-control-strings-1.1.0.tgz",
      "integrity": "sha1-PXz0Rk22RG6mRL9LOVB/mFEAjo4="
    },
+    "console-stamp": {
+      "version": "0.2.7",
+      "resolved": "https://registry.npmjs.org/console-stamp/-/console-stamp-0.2.7.tgz",
+      "integrity": "sha512-4QGcEgXSDnErHxX8NLtywyjSRaS9IUV7gPAqYKtIvDM0DYuZErcVQgcKrtJGIK9W821HwqYqaA3FXU1OlgMiIQ==",
+      "requires": {
+        "chalk": "^1.1.1",
+        "dateformat": "^1.0.11",
+        "merge": "^1.2.0"
+      }
+    },
    "continuation-local-storage": {
      "version": "3.2.1",
      "resolved": "https://registry.npmjs.org/continuation-local-storage/-/continuation-local-storage-3.2.1.tgz",
@ -4552,6 +4599,28 @@
      "resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.1.15.tgz",
      "integrity": "sha512-6uHUhOPEBgQ24HM+r6b/QwWfZq+yiFcipKFrOFiBEnWdy5sdzYoi+pJeQaPI5qOLRFqWmAXUPQNsielzdLoecA=="
    },
+    "gray-matter": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/gray-matter/-/gray-matter-2.1.1.tgz",
+      "integrity": "sha1-MELZrewqHe1qdwep7SOA+KF6Qw4=",
+      "requires": {
+        "ansi-red": "^0.1.1",
+        "coffee-script": "^1.12.4",
+        "extend-shallow": "^2.0.1",
+        "js-yaml": "^3.8.1",
+        "toml": "^2.3.2"
+      },
+      "dependencies": {
+        "extend-shallow": {
+          "version": "2.0.1",
+          "resolved": "https://registry.npmjs.org/extend-shallow/-/extend-shallow-2.0.1.tgz",
+          "integrity": "sha1-Ua99YUrZqfYQ6huvu5idaxxWiQ8=",
+          "requires": {
+            "is-extendable": "^0.1.0"
+          }
+        }
+      }
+    },
    "handlebars": {
      "version": "4.1.1",
      "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.1.1.tgz",
@ -5242,6 +5311,14 @@
      "resolved": "https://registry.npmjs.org/lazy/-/lazy-1.0.11.tgz",
      "integrity": "sha1-2qBoIGKCVCwIgojpdcKXwa53tpA="
    },
+    "lazy-cache": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/lazy-cache/-/lazy-cache-2.0.2.tgz",
+      "integrity": "sha1-uRkKT5EzVGlIQIWfio9whNiCImQ=",
+      "requires": {
+        "set-getter": "^0.1.0"
+      }
+    },
    "lcid": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/lcid/-/lcid-2.0.0.tgz",
@ -5447,6 +5524,11 @@
      "resolved": "https://registry.npmjs.org/macos-release/-/macos-release-2.2.0.tgz",
      "integrity": "sha512-iV2IDxZaX8dIcM7fG6cI46uNmHUxHE4yN+Z8tKHAW1TBPMZDIKHf/3L+YnOuj/FK9il14UaVdHmiQ1tsi90ltA=="
    },
+    "madr": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/madr/-/madr-2.1.2.tgz",
+      "integrity": "sha512-n+dkvy8NMMIHEMp2qaOQfxiy1Zqs5UfygEw1hqmBYqQdMgnVZSrS2BWN9NThzoHKWuFnhyWwmy0ls6k5XZ03Gg=="
+    },
    "make-dir": {
      "version": "1.3.0",
      "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-1.3.0.tgz",
@ -5547,6 +5629,11 @@
        }
      }
    },
+    "merge": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/merge/-/merge-1.2.1.tgz",
+      "integrity": "sha512-VjFo4P5Whtj4vsLzsYBu5ayHhoHJ0UqNm7ibvShmbmoz7tGi0vXaoJbGdB+GmDMLUdg8DpQXEIeVDAe8MaABvQ=="
+    },
    "merge2": {
      "version": "1.2.3",
      "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.2.3.tgz",
@ -6367,6 +6454,15 @@
      "resolved": "https://registry.npmjs.org/pascalcase/-/pascalcase-0.1.1.tgz",
      "integrity": "sha1-s2PlXoAGym/iF4TS2yK9FdeRfxQ="
    },
+    "path": {
+      "version": "0.12.7",
+      "resolved": "https://registry.npmjs.org/path/-/path-0.12.7.tgz",
+      "integrity": "sha1-1NwqUGxM4hl+tIHr/NWzbAFAsQ8=",
+      "requires": {
+        "process": "^0.11.1",
+        "util": "^0.10.3"
+      }
+    },
    "path-dirname": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/path-dirname/-/path-dirname-1.0.2.tgz",
@ -6610,6 +6706,11 @@
      "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.1.2.tgz",
      "integrity": "sha1-IZMqVJ9eUv/ZqCf1cOBL5iqX2lQ="
    },
+    "process": {
+      "version": "0.11.10",
+      "resolved": "https://registry.npmjs.org/process/-/process-0.11.10.tgz",
+      "integrity": "sha1-czIwDoQBYb2j5podHZGn1LwW8YI="
+    },
    "process-nextick-args": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.0.tgz",
@ -6924,6 +7025,26 @@
        "safe-regex": "^1.1.0"
      }
    },
+    "remarkable": {
+      "version": "1.7.1",
+      "resolved": "https://registry.npmjs.org/remarkable/-/remarkable-1.7.1.tgz",
+      "integrity": "sha1-qspJchALZqZCpjoQIcpLrBvjv/Y=",
+      "requires": {
+        "argparse": "~0.1.15",
+        "autolinker": "~0.15.0"
+      },
+      "dependencies": {
+        "argparse": {
+          "version": "0.1.16",
+          "resolved": "https://registry.npmjs.org/argparse/-/argparse-0.1.16.tgz",
+          "integrity": "sha1-z9AeD7uj1srtBJ+9dY1A9lGW9Xw=",
+          "requires": {
+            "underscore": "~1.7.0",
+            "underscore.string": "~2.4.0"
+          }
+        }
+      }
+    },
    "remove-trailing-separator": {
      "version": "1.1.0",
      "resolved": "https://registry.npmjs.org/remove-trailing-separator/-/remove-trailing-separator-1.1.0.tgz",
@ -7115,6 +7236,14 @@
      "resolved": "https://registry.npmjs.org/set-blocking/-/set-blocking-2.0.0.tgz",
      "integrity": "sha1-BF+XgtARrppoA93TgrJDkrPYkPc="
    },
+    "set-getter": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/set-getter/-/set-getter-0.1.0.tgz",
+      "integrity": "sha1-12nBgsnVpR9AkUXy+6guXoboA3Y=",
+      "requires": {
+        "to-object-path": "^0.3.0"
+      }
+    },
    "set-value": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/set-value/-/set-value-2.0.0.tgz",
@ -7660,6 +7789,11 @@
        "repeat-string": "^1.6.1"
      }
    },
+    "toml": {
+      "version": "2.3.6",
+      "resolved": "https://registry.npmjs.org/toml/-/toml-2.3.6.tgz",
+      "integrity": "sha512-gVweAectJU3ebq//Ferr2JUY4WKSDe5N+z0FvjDncLGyHmIDoxgY/2Ie4qfEIDm4IS7OA6Rmdm7pdEEdMcV/xQ=="
+    },
    "tough-cookie": {
      "version": "2.4.3",
      "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-2.4.3.tgz",
@ -7763,6 +7897,16 @@
      "resolved": "https://registry.npmjs.org/umask/-/umask-1.1.0.tgz",
      "integrity": "sha1-8pzr8B31F5ErtY/5xOUP3o4zMg0="
    },
+    "underscore": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/underscore/-/underscore-1.7.0.tgz",
+      "integrity": "sha1-a7rwh3UA02vjTsqlhODbn+8DUgk="
+    },
+    "underscore.string": {
+      "version": "2.4.0",
+      "resolved": "https://registry.npmjs.org/underscore.string/-/underscore.string-2.4.0.tgz",
+      "integrity": "sha1-jN2PusTi0uoefi6Al8QvRCKA+Fs="
+    },
    "union-value": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/union-value/-/union-value-1.0.0.tgz",
@ -7898,6 +8042,14 @@
      "resolved": "https://registry.npmjs.org/use/-/use-3.1.1.tgz",
      "integrity": "sha512-cwESVXlO3url9YWlFW/TA9cshCEhtu7IKJ/p5soJ/gGpj7vbvFrAY/eIioQ6Dw23KjZhYgiIo8HOs1nQ2vr/oQ=="
    },
+    "util": {
+      "version": "0.10.4",
+      "resolved": "https://registry.npmjs.org/util/-/util-0.10.4.tgz",
+      "integrity": "sha512-0Pm9hTQ3se5ll1XihRic3FDIku70C+iHUdT/W926rSgHV5QgXsYbKZN8MSC3tJtSkhuROzvsQjAaFENRXr+19A==",
+      "requires": {
+        "inherits": "2.0.3"
+      }
+    },
    "util-deprecate": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
--- a/package.json
+++ b/package.json
@ -22,11 +22,13 @@
  "author": "Mozilla (https://mozilla.org/)",
  "license": "MPL-2.0",
  "dependencies": {
+    "adr-log": "^2.1.1",
    "chalk": "1.1.1",
    "diffparser": "^2.0.1",
    "fxa-dev-launcher": "vladikoff/fxa-dev-launcher",
    "internal-ip": "1.2.0",
    "lerna": "^3.13.1",
+    "madr": "^2.1.2",
    "node-fetch": "^2.3.0",
    "pm2": "^3.4.1",
    "replace-in-file": "0.2.1"