Document some architectural decisions

.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,32 @@
+# 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)
+
+Referenced by [7. Drop writing support](0007-drop-writing-support.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,30 @@
+# 5. Deprecate setters in favor of functional options during initialization
+
+Date: 2021-07-20
+
+## Status
+
+Proposed
+
+Referenced by [8. Deprecate the global Viper instance](0008-deprecate-the-global-viper-instance.md)
+
+## 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.

docs/adr/0006-go-version-support.md

@@ -0,0 +1,20 @@
+# 6. Go version support
+
+Date: 2021-09-16
+
+## Status
+
+Proposed
+
+## Context
+
+From time to time new features are released in the Go language.
+Relying on those features means dropping support for older Go versions.
+
+## Decision
+
+Follow the [Go release policy](https://golang.org/doc/devel/release#policy) and support the last two major versions of Go.
+
+## Consequences
+
+Support for older Go versions will happen every 6 months according to the Go release cycle.

docs/adr/0007-drop-writing-support.md

@@ -0,0 +1,22 @@
+# 7. Drop writing support
+
+Date: 2021-09-22
+
+## Status
+
+Proposed
+
+References [2. Prefer making backward compatible changes](0002-prefer-making-backward-compatible-changes.md)
+
+## Context
+
+The number one source of issues for Viper comes from the fact that it supports both reading and writing.
+It causes concurrency issues and has lots of inconsistencies.
+
+## Decision
+
+Drop file writing support from Viper in v2.
+
+## Consequences
+
+This is going to be a major breaking change in the library, but it will make maintenance significantly easier.

docs/adr/0008-deprecate-the-global-viper-instance.md

@@ -0,0 +1,23 @@
+# 8. Deprecate the global Viper instance
+
+Date: 2021-09-23
+
+## Status
+
+Proposed
+
+References [5. Deprecate setters in favor of functional options during initialization](0005-deprecate-setters-in-favor-of-functional-options-during-initialization.md)
+
+## Context
+
+With the deprecation of setters in favor of functional options, it becomes almost impossible to get away with instantiating Viper.
+In addition to that, people should be discouraged from accessing a global Viper instance.
+
+## Decision
+
+Deprecate the global Viper instance and the global access functions.
+
+## Consequences
+
+People will still be able to create a global instance of their own,
+but instantiating a custom Viper instance will become the primary solution for using Viper.