Initial ADRs (#2)

* Initial ADRs

architecture/adr-001-use-adrs.md

@@ -0,0 +1,67 @@
+# Architecture Decision Record: Use ADRs
+
+## Context
+
+ComposeUI has several very explicit goals that make the practice and
+discipline of architecture very important:
+
+- We want to think deeply about all our architectural decisions,
+  exploring all alternatives and making a careful, considered,
+  well-researched choice.
+- We want to be as transparent as possible in our decision-making
+  process.
+- We don't want decisions to be made unilaterally in a
+  vacuum. Specifically, we want to give our steering group the
+  opportunity to review every major decision.
+- Despite being a geographically and temporally distributed team, we
+  want our contributors to have a strong shared understanding of the
+  technical rationale behind decisions.
+- We want to be able to revisit prior decisions to determine fairly if
+  they still make sense, and if the motivating circumstances or
+  conditions have changed.
+
+## Decision
+
+We will document every architecture-level decision for ComposeUI and its
+core modules with an
+[Architecture Decision Record](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). These
+are a well structured, relatively lightweight way to capture
+architectural proposals. They can serve as an artifact for discussion,
+and remain as an enduring record of the context and motivation of past
+decisions.
+
+The workflow will be:
+
+1. A developer creates an ADR document outlining an approach for a
+   particular question or problem. The ADR has an initial status of "proposed."
+2. The developers and steering group discuss the ADR. During this
+   period, the ADR should be updated to reflect additional context,
+   concerns raised, and proposed changes.
+3. Once consensus is reached, ADR can be transitioned to either an
+   "accepted" or "rejected" state.
+4. Only after an ADR is accepted should implementing code be committed
+   to the main branch of the relevant project/module.
+5. If a decision is revisited and a different conclusion is reached, a
+   new ADR should be created documenting the context and rationale for
+   the change. The new ADR should reference the old one, and once the
+   new one is accepted, the old one should (in its "status" section)
+   be updated to point to the new one. The old ADR should not be
+   removed or otherwise modified except for the annotation pointing to
+   the new ADR.
+
+## Status
+
+Proposed
+
+## Consequences
+
+1. Developers must write an ADR and submit it for review before
+   selecting an approach to any architectural decision -- that is, any
+   decision that affects the way ComposeUI or a ComposeUI application is
+   put together at a high level.
+2. We will have a concrete artifact around which to focus discussion,
+   before finalizing decisions.
+3. If we follow the process, decisions will be made deliberately, as a group.
+4. The main branch of our repositories will reflect the high-level
+   consensus of the steering group.
+5. We will have a useful persistent record of why the system is the way it is.

architecture/adr-002-configuration.md

@@ -0,0 +1,65 @@
+# Architecture Decision Record: Configuration
+
+## Context
+
+ComposeUI has to fulfill a number of different goals.
+
+1. It needs to be *modular*. Different software packages, written by
+   different developers, should be usable and swappable in the same
+   application with a minimum of effort.
+
+2. ComposeUI applications need to be *transparent* and
+   *introspectable*. It should always be as clear as possible what is
+   going on at any given moment, and why the application is behaving
+   in the way it does.
+
+3. As a general-purpose UI framework, it needs to provide a strong
+   set of default settings which are also highly overridable, and
+   *configurable* to suit the unique needs of users.
+
+## Decision
+
+ComposeUI will take the "Configurability" philosophy to its logical
+extreme, and encode as much information about the application as
+possible in a single, highly general structure, that can be queried
+through the communication bridge. This will include
+not just configuration that is normally thought of as "config" data -
+whether it is an information about which server to connect to or
+where a button is on a ribbon, this would be stored in an in memory
+data store that could be changed and get notified on the fly.
+
+Some concrete examples include (but not limited to):
+
+- Dependency injection components
+- Runtime entities
+- User interface component models
+- Persistent schemas
+- Locations of static and dynamic assets
+
+This configuration value will have a *schema* that defines what types
+of entities can exist in the configuration, and what their expected
+properties are.
+
+Each distinct module will have the ability to contribute to the schema
+and define entity types specific to its own domain. Modules may
+interact by referencing entity types and properties defined in other
+modules.
+
+## Status
+
+Proposed
+
+## Consequences
+
+- Applications will be defined comprehensively and declaratively by a
+  rich data structure.
+- The config schema provides an explicit, reliable contract and set of
+  extension points, which can be used by other modules to modify
+  entities or behaviors.
+- It will be easy to understand and inspect an application by
+  inspecting or querying its configuration. It will be possible to
+  write tools to make exploring and visualizing applications even easier.
+- Developers will need to carefully decide what types of things are
+  appropriate to encode statically in the configuration, and what must
+  be dynamic at runtime.
+