From b2ecbc6bed6f951a1b7f91524bdee180ecf7652b Mon Sep 17 00:00:00 2001 From: Jonathan Zempel Date: Wed, 14 Jun 2023 14:31:47 -0400 Subject: [PATCH 1/5] doc(adrs): add theming peer dependency ADR-001 --- docs/adrs/001-theming-peer-dependency.md | 39 ++++++++++++++++++++++++ docs/adrs/README.md | 6 ++++ 2 files changed, 45 insertions(+) create mode 100644 docs/adrs/001-theming-peer-dependency.md create mode 100644 docs/adrs/README.md diff --git a/docs/adrs/001-theming-peer-dependency.md b/docs/adrs/001-theming-peer-dependency.md new file mode 100644 index 00000000000..59b741b1c83 --- /dev/null +++ b/docs/adrs/001-theming-peer-dependency.md @@ -0,0 +1,39 @@ +# ADR-001: Theming peer dependency + +2023.04.24 + +## Context + +Garden provides a collection of React components through multiple NPM packages. +Each package has peerDependencies for `@zendeskgarden/react-theming`, `react`, +`react-dom`, and `styled-components`. Typically, a package should increase its +major version when there is a change in its peer dependency requirements. +However, Garden proposes a DECISION to deviate from this [general +rule](https://nodejs.org/en/blog/npm/peer-dependencies) and allow special +treatment for `@zendeskgarden/react-theming` peer dependency. + +While this decision conflicts with [semantic versioning](https://semver.org/), +it benefits both maintainers and consumers by enabling centralized and tested +hooks and utilities across the codebase. As a result, consumers are not required +to ingest duplicated and more brittle code. A console warning will notify the +consumer if a peer version is out-of-date. + +Ideally, all Garden package versions should align. However, at the very least, +the theming peer dependency should align with the highest version of Garden +component package dependency. + +## Decision + +As [centralized theming +utilities](https://garden.zendesk.com/components/utilities) are added or +modified (in non-breaking fashion), other Garden component packages may take +advantage of them by updating the `@zendeskgarden/react-theming` peer dependency +minor version without publishing a major version breaking change. + +## Consequences + +If a consumer upgrades a single Garden component package, they may see a console +warning indicating that the `@zendeskgarden/react-theming` package is +out-of-date. If the warning is ignored, there is a high likelihood that +component rendering will fail due to a missing theming utility. However, there +is no reason to believe that such a failure could slip through to production. diff --git a/docs/adrs/README.md b/docs/adrs/README.md new file mode 100644 index 00000000000..1024350fccd --- /dev/null +++ b/docs/adrs/README.md @@ -0,0 +1,6 @@ +# Architectural Decision Records + +Garden architectural decison records (ADRs) capture important decisions made, +along with context and consequences. + +- [ADR-001](./001-theming-peer-dependency.md): Theming peer dependency From 52b937a94e7e0e5805109c825b83575c8686b3db Mon Sep 17 00:00:00 2001 From: Jonathan Zempel Date: Wed, 14 Jun 2023 14:37:23 -0400 Subject: [PATCH 2/5] Add ADR link to root README --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 485c6fbb1c7..178a5e031d4 100644 --- a/README.md +++ b/README.md @@ -165,6 +165,7 @@ the links below to learn more. - Major release [migration](docs/migration.md) instructions - Component [API](docs/api.md) - [Development](docs/development.md) guidelines +- Architectural [decision](docs/adrs/README.md) records ## Contribution From 4634f79767a16fd60b885d9a19eb77f388acc229 Mon Sep 17 00:00:00 2001 From: Jonathan Zempel Date: Wed, 14 Jun 2023 14:38:50 -0400 Subject: [PATCH 3/5] Update link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 178a5e031d4..bd9e604a6b7 100644 --- a/README.md +++ b/README.md @@ -165,7 +165,7 @@ the links below to learn more. - Major release [migration](docs/migration.md) instructions - Component [API](docs/api.md) - [Development](docs/development.md) guidelines -- Architectural [decision](docs/adrs/README.md) records +- Architectural [decision](docs/adrs/#readme) records ## Contribution From d6b0b2dad03c83c83ededbb512e58f0e0ad0372a Mon Sep 17 00:00:00 2001 From: Jonathan Zempel Date: Thu, 15 Jun 2023 09:40:38 -0400 Subject: [PATCH 4/5] Apply suggestions from code review Co-authored-by: George Treviranus <3946669+geotrev@users.noreply.github.com> --- docs/adrs/001-theming-peer-dependency.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/adrs/001-theming-peer-dependency.md b/docs/adrs/001-theming-peer-dependency.md index 59b741b1c83..278710100ad 100644 --- a/docs/adrs/001-theming-peer-dependency.md +++ b/docs/adrs/001-theming-peer-dependency.md @@ -10,7 +10,7 @@ Each package has peerDependencies for `@zendeskgarden/react-theming`, `react`, major version when there is a change in its peer dependency requirements. However, Garden proposes a DECISION to deviate from this [general rule](https://nodejs.org/en/blog/npm/peer-dependencies) and allow special -treatment for `@zendeskgarden/react-theming` peer dependency. +treatment for `@zendeskgarden/react-theming`. While this decision conflicts with [semantic versioning](https://semver.org/), it benefits both maintainers and consumers by enabling centralized and tested @@ -19,7 +19,7 @@ to ingest duplicated and more brittle code. A console warning will notify the consumer if a peer version is out-of-date. Ideally, all Garden package versions should align. However, at the very least, -the theming peer dependency should align with the highest version of Garden +the theming peer dependency should align with the highest version of a Garden component package dependency. ## Decision @@ -27,7 +27,7 @@ component package dependency. As [centralized theming utilities](https://garden.zendesk.com/components/utilities) are added or modified (in non-breaking fashion), other Garden component packages may take -advantage of them by updating the `@zendeskgarden/react-theming` peer dependency +advantage of them by updating their `@zendeskgarden/react-theming` peer dependency minor version without publishing a major version breaking change. ## Consequences From 298f8b0806f44d01350327dc85ac27cecc3d017b Mon Sep 17 00:00:00 2001 From: Jonathan Zempel Date: Thu, 15 Jun 2023 14:42:50 -0400 Subject: [PATCH 5/5] Applied wording suggestions from @Francois-Esquire --- docs/adrs/001-theming-peer-dependency.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/adrs/001-theming-peer-dependency.md b/docs/adrs/001-theming-peer-dependency.md index 278710100ad..a23b99a9951 100644 --- a/docs/adrs/001-theming-peer-dependency.md +++ b/docs/adrs/001-theming-peer-dependency.md @@ -5,7 +5,7 @@ ## Context Garden provides a collection of React components through multiple NPM packages. -Each package has peerDependencies for `@zendeskgarden/react-theming`, `react`, +Each package has peer dependencies for `@zendeskgarden/react-theming`, `react`, `react-dom`, and `styled-components`. Typically, a package should increase its major version when there is a change in its peer dependency requirements. However, Garden proposes a DECISION to deviate from this [general @@ -13,14 +13,14 @@ rule](https://nodejs.org/en/blog/npm/peer-dependencies) and allow special treatment for `@zendeskgarden/react-theming`. While this decision conflicts with [semantic versioning](https://semver.org/), -it benefits both maintainers and consumers by enabling centralized and tested -hooks and utilities across the codebase. As a result, consumers are not required -to ingest duplicated and more brittle code. A console warning will notify the -consumer if a peer version is out-of-date. +it benefits both maintainers and consumers by enabling a centralized, tested +collection of hooks and utilities across the codebase. As a result, consumers +are not required to ingest duplicated and more brittle code. A terminal warning +will notify the consumer if a peer version is out-of-date. Ideally, all Garden package versions should align. However, at the very least, -the theming peer dependency should align with the highest version of a Garden -component package dependency. +the `@zendeskgarden/react-theming` peer dependency should align with the highest +version of a Garden component package dependency. ## Decision