diff --git a/README.md b/README.md index 485c6fbb1c7..bd9e604a6b7 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) records ## Contribution diff --git a/docs/adrs/001-theming-peer-dependency.md b/docs/adrs/001-theming-peer-dependency.md new file mode 100644 index 00000000000..a23b99a9951 --- /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 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 +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 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 `@zendeskgarden/react-theming` peer dependency should align with the highest +version of a 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 their `@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