From d2e3a7e5c2684f95d9e5da639139c1278367f62b Mon Sep 17 00:00:00 2001 From: Mark Sagi-Kazar Date: Tue, 20 Jul 2021 23:54:12 +0200 Subject: [PATCH] docs: document some architectural decisions Signed-off-by: Mark Sagi-Kazar --- .adr-dir | 1 + .../adr/0001-record-architecture-decisions.md | 19 ++++++++++++ ...efer-making-backward-compatible-changes.md | 30 +++++++++++++++++++ ...s-with-heavy-dependencies-from-the-core.md | 26 ++++++++++++++++ ...te-github-organization-for-new-packages.md | 24 +++++++++++++++ ...unctional-options-during-initialization.md | 28 +++++++++++++++++ 6 files changed, 128 insertions(+) create mode 100644 .adr-dir create mode 100644 docs/adr/0001-record-architecture-decisions.md create mode 100644 docs/adr/0002-prefer-making-backward-compatible-changes.md create mode 100644 docs/adr/0003-extract-components-with-heavy-dependencies-from-the-core.md create mode 100644 docs/adr/0004-use-separate-github-organization-for-new-packages.md create mode 100644 docs/adr/0005-deprecate-setters-in-favor-of-functional-options-during-initialization.md diff --git a/.adr-dir b/.adr-dir new file mode 100644 index 0000000..c73b64a --- /dev/null +++ b/.adr-dir @@ -0,0 +1 @@ +docs/adr diff --git a/docs/adr/0001-record-architecture-decisions.md b/docs/adr/0001-record-architecture-decisions.md new file mode 100644 index 0000000..634e98a --- /dev/null +++ b/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). diff --git a/docs/adr/0002-prefer-making-backward-compatible-changes.md b/docs/adr/0002-prefer-making-backward-compatible-changes.md new file mode 100644 index 0000000..fc1e4e3 --- /dev/null +++ b/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. diff --git a/docs/adr/0003-extract-components-with-heavy-dependencies-from-the-core.md b/docs/adr/0003-extract-components-with-heavy-dependencies-from-the-core.md new file mode 100644 index 0000000..e330cea --- /dev/null +++ b/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. diff --git a/docs/adr/0004-use-separate-github-organization-for-new-packages.md b/docs/adr/0004-use-separate-github-organization-for-new-packages.md new file mode 100644 index 0000000..4223256 --- /dev/null +++ b/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. diff --git a/docs/adr/0005-deprecate-setters-in-favor-of-functional-options-during-initialization.md b/docs/adr/0005-deprecate-setters-in-favor-of-functional-options-during-initialization.md new file mode 100644 index 0000000..0993ed3 --- /dev/null +++ b/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.