docs: document some architectural decisions

Signed-off-by: Mark Sagi-Kazar <mark.sagikazar@gmail.com>

.adr-dir

@@ -0,0 +1 @@
+docs/adr

docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,19 @@
+# 1. Record architecture decisions
+
+Date: 2021-07-20
+
+## Status
+
+Proposed
+
+## Context
+
+We need to record the architectural decisions made on this project.
+
+## Decision
+
+We will use Architecture Decision Records, as [described by Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions).
+
+## Consequences
+
+See Michael Nygard's article, linked above. For a lightweight ADR toolset, see Nat Pryce's [adr-tools](https://github.com/npryce/adr-tools).

docs/adr/0002-prefer-making-backward-compatible-changes.md

@@ -0,0 +1,30 @@
+# 2. Prefer making backward compatible changes
+
+Date: 2021-07-20
+
+## Status
+
+Proposed
+
+Referenced by [3. Extract components with heavy dependencies from the core](0003-extract-components-with-heavy-dependencies-from-the-core.md)
+
+Referenced by [4. Use separate GitHub organization for new packages](0004-use-separate-github-organization-for-new-packages.md)
+
+## Context
+
+Architecturally speaking Viper became a giant over the years: it hides a lot of complexity behind a simple interface.
+That simple interface, however, is what makes Viper extremely popular.
+
+## Decision
+
+In order to keep the library useful to people, we should prefer making backward compatible changes to Viper, even between major releases.
+This is not a hard rule forbiding breaking changes though: when it makes sense, breaking changes are allowed,
+but keeping things backward compatible is a priority.
+
+## Consequences
+
+Although major versions allow breaking changes, a major release is no reason to break things that already work for a lot of people,
+even if it might not be the best possible solution.
+
+Instead of breaking things, introducing new interfaces should be the default way of fixing architectural problems,
+leaving old interfaces intact.

docs/adr/0003-extract-components-with-heavy-dependencies-from-the-core.md

@@ -0,0 +1,26 @@
+# 3. Extract components with heavy dependencies from the core
+
+Date: 2021-07-20
+
+## Status
+
+Proposed
+
+References [2. Prefer making backward compatible changes](0002-prefer-making-backward-compatible-changes.md)
+
+Referenced by [4. Use separate GitHub organization for new packages](0004-use-separate-github-organization-for-new-packages.md)
+
+## Context
+
+Viper (v1) currently imports a bunch of external dependencies (for encoding/decoding, remote stores, etc)
+that make the library itself quite a heavy dependency.
+
+## Decision
+
+Move components with external dependencies out of the core to separate packages.
+
+## Consequences
+
+Viper 1 will have to continue importing all of these packages to maintain backwards compatibility.
+
+Viper 2 (and future versions) on the other hand can break backwards compatibility and require users to import the required packages.

docs/adr/0004-use-separate-github-organization-for-new-packages.md

@@ -0,0 +1,24 @@
+# 4. Use separate GitHub organization for new packages
+
+Date: 2021-07-20
+
+## Status
+
+Proposed
+
+References [2. Prefer making backward compatible changes](0002-prefer-making-backward-compatible-changes.md)
+
+References [3. Extract components with heavy dependencies from the core](0003-extract-components-with-heavy-dependencies-from-the-core.md)
+
+## Context
+
+The core Viper package is under a personal GitHub account which makes collaborative development a bit difficult.
+
+## Decision
+
+Create new Go modules in the [go-viper](https://github.com/go-viper) organization.
+Keep the core library under [Steve's personal account](https://github.com/spf13/viper) for backward compatibility purposes.
+
+## Consequences
+
+It'll be easier to create new modules and to add new functionality to Viper without having to add new dependencies to the core library.

docs/adr/0005-deprecate-setters-in-favor-of-functional-options-during-initialization.md

@@ -0,0 +1,28 @@
+# 5. Deprecate setters in favor of functional options during initialization
+
+Date: 2021-07-20
+
+## Status
+
+Proposed
+
+## Context
+
+The Viper struct currently acts as a facade for reading, writing and watching configuration for changes.
+Some of the configuration parameters can be changed runtime using setters which often lead to issues
+with concurrent activities.
+
+## Decision
+
+Deprecate setters in favor of using functional options for configuring Viper when it's initialized.
+
+Drop setters in Viper 2.
+
+## Consequences
+
+Since Viper's interface is usually invoked from a lot of places,
+moving configuration to the place where it is initialized makes using Viper safer
+(ie. someone can't just randomly call `Set` when they are only supposed to call `Get*`).
+
+This change will also clarify what roles Viper can be used in and
+makes the separation of internal components easier based on these roles.