diff --git a/doc/adr/0001-record-architecture-decisions.md b/doc/adr/0001-record-architecture-decisions.md new file mode 100644 index 000000000..d4625ab2c --- /dev/null +++ b/doc/adr/0001-record-architecture-decisions.md @@ -0,0 +1,20 @@ +# 1. Record architecture decisions + +Date: 09/11/2016 + +## Status + +Accepted + +## Context + +We need to record the architectural decisions made on this project. + +## Decision + +We will use Architecture Decision Records, as described by Michael Nygard in +[this article](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). + +## Consequences + +See Michael Nygard's article, linked above. diff --git a/doc/adr/0002-contain-and-manage-state.md b/doc/adr/0002-contain-and-manage-state.md new file mode 100644 index 000000000..5c7ad333a --- /dev/null +++ b/doc/adr/0002-contain-and-manage-state.md @@ -0,0 +1,33 @@ +# 2. Contain and manage state + +Date: 09/11/2016 + +## Status + +Accepted + +## Context + +The hardest part of debugging Link Previews issues (especially those related to +EventLogging) was understanding the state of the system (the "state") and how +it's mutated given some interaction(s). This was in no small part because the +state was defined, initialized, and mutated in various parts of the codebase. + +The state required for Link Previews to function isn't actually overly +complicated. To keep things easy to debug/easy to reason about we should +endeavour to isolate the state and its mutations from the various other parts of +the system. + +## Decision + +Use [Redux](http://redux.js.org). + +## Consequences + +* Newcomers will have to familiarise themselves with the library (especially + it's nomenclature). +* All changes will have to be broken down into: the additional state that they + require; actions that are dispatched; and how the state is mutated as a result + of those actions. This requires discipline. +* We benefit from using a tool that is part of an increasingly rich ecosystem, + e.g. see [Redux DevTools Extension](https://github.com/zalmoxisus/redux-devtools-extension).