From d2e3a7e5c2684f95d9e5da639139c1278367f62b Mon Sep 17 00:00:00 2001 From: Mark Sagi-Kazar Date: Tue, 20 Jul 2021 23:54:12 +0200 Subject: [PATCH 1/4] 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. From a0f1caa4edf0c6becf919535b5e1687e4e390843 Mon Sep 17 00:00:00 2001 From: Mark Sagi-Kazar Date: Thu, 16 Sep 2021 09:04:54 +0200 Subject: [PATCH 2/4] docs: document a decision about Go version support Signed-off-by: Mark Sagi-Kazar --- docs/adr/0006-go-version-support.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 docs/adr/0006-go-version-support.md diff --git a/docs/adr/0006-go-version-support.md b/docs/adr/0006-go-version-support.md new file mode 100644 index 0000000..2b63518 --- /dev/null +++ b/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. From c943b3ef2755a136bd2fb2b2cadb1ad939f1539b Mon Sep 17 00:00:00 2001 From: Mark Sagi-Kazar Date: Wed, 22 Sep 2021 23:10:51 +0200 Subject: [PATCH 3/4] docs: propose dropping file writing support Signed-off-by: Mark Sagi-Kazar --- ...efer-making-backward-compatible-changes.md | 2 ++ docs/adr/0007-drop-writing-support.md | 22 +++++++++++++++++++ 2 files changed, 24 insertions(+) create mode 100644 docs/adr/0007-drop-writing-support.md diff --git a/docs/adr/0002-prefer-making-backward-compatible-changes.md b/docs/adr/0002-prefer-making-backward-compatible-changes.md index fc1e4e3..4651d28 100644 --- a/docs/adr/0002-prefer-making-backward-compatible-changes.md +++ b/docs/adr/0002-prefer-making-backward-compatible-changes.md @@ -10,6 +10,8 @@ Referenced by [3. Extract components with heavy dependencies from the core](0003 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. diff --git a/docs/adr/0007-drop-writing-support.md b/docs/adr/0007-drop-writing-support.md new file mode 100644 index 0000000..c740dc1 --- /dev/null +++ b/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. From 99e9188c7cbfabee4b23cfc7b88817d4240ee571 Mon Sep 17 00:00:00 2001 From: Mark Sagi-Kazar Date: Thu, 23 Sep 2021 10:07:37 +0200 Subject: [PATCH 4/4] docs: propose deprecating the global Viper instance Signed-off-by: Mark Sagi-Kazar --- ...unctional-options-during-initialization.md | 2 ++ ...008-deprecate-the-global-viper-instance.md | 23 +++++++++++++++++++ 2 files changed, 25 insertions(+) create mode 100644 docs/adr/0008-deprecate-the-global-viper-instance.md 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 index 0993ed3..35f3009 100644 --- 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 @@ -6,6 +6,8 @@ Date: 2021-07-20 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. diff --git a/docs/adr/0008-deprecate-the-global-viper-instance.md b/docs/adr/0008-deprecate-the-global-viper-instance.md new file mode 100644 index 0000000..f4be40d --- /dev/null +++ b/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.