From d012f722b44b57a9a5bb94f6732b8abae88a3d79 Mon Sep 17 00:00:00 2001 From: Aram Limpens Date: Fri, 19 Apr 2024 13:51:11 +0200 Subject: [PATCH 01/12] Add packages as peer deps --- packages/css/package.json | 5 ++++- packages/react/package.json | 1 + pnpm-lock.yaml | 9 ++++++++- 3 files changed, 13 insertions(+), 2 deletions(-) diff --git a/packages/css/package.json b/packages/css/package.json index 1b0751ab25..6e6f325448 100644 --- a/packages/css/package.json +++ b/packages/css/package.json @@ -19,7 +19,10 @@ "clean": "rimraf dist/" }, "devDependencies": { - "@amsterdam/design-system-tokens": "workspace:*", "sass": "1.75.0" + }, + "peerDependencies": { + "@amsterdam/design-system-tokens": "workspace:*", + "@amsterdam/design-system-assets": "workspace:*" } } diff --git a/packages/react/package.json b/packages/react/package.json index d06f558bf7..ea895c234e 100644 --- a/packages/react/package.json +++ b/packages/react/package.json @@ -72,6 +72,7 @@ "tslib": "2.6.2" }, "peerDependencies": { + "@amsterdam/design-system-css": "workspace:*", "react": "16 - 18", "react-dom": "16 - 18" } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 1202df0192..f9ca52f983 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -97,16 +97,23 @@ importers: version: 7.2.0 packages/css: - devDependencies: + dependencies: + '@amsterdam/design-system-assets': + specifier: workspace:* + version: link:../../proprietary/assets '@amsterdam/design-system-tokens': specifier: workspace:* version: link:../../proprietary/tokens + devDependencies: sass: specifier: 1.75.0 version: 1.75.0 packages/react: dependencies: + '@amsterdam/design-system-css': + specifier: workspace:* + version: link:../css '@amsterdam/design-system-react-icons': specifier: workspace:* version: link:../../proprietary/react-icons From 92cd32e31361eeaf2f8de0d4d6c4f2bf1e5b1fe5 Mon Sep 17 00:00:00 2001 From: Aram Limpens Date: Fri, 19 Apr 2024 13:54:36 +0200 Subject: [PATCH 02/12] Update getting started docs --- packages/react/README.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/packages/react/README.md b/packages/react/README.md index f2199a4085..1c4c892c09 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -5,9 +5,8 @@ The `@amsterdam/design-system-react` package contains React implementations of various components. You can use this package in React apps. -The design tokens and css used in these components are published in separate npm packages, so don’t forget to install and include `@amsterdam/design-system-tokens` and `@amsterdam/design-system-css` too. - - +The design tokens and CSS used in these components are published in separate npm packages, +which are automatically installed when you install the React package. ## Stability of the components @@ -19,11 +18,11 @@ Make sure you specify the exact version as dependency, so you can schedule to up ## Getting started -Install the packages you need, for instance: +Install the React packages, like so: -`npm install @amsterdam/design-system-react @amsterdam/design-system-tokens @amsterdam/design-system-assets @amsterdam/design-system-css` +`npm install @amsterdam/design-system-react` -Import the packages you need. +Import the components and CSS you need, for example: ```javascript import { Paragraph } from "@amsterdam/design-system-react"; From ea87d4bc6236506475adb225d480e87177141474 Mon Sep 17 00:00:00 2001 From: Aram Limpens Date: Fri, 19 Apr 2024 14:30:15 +0200 Subject: [PATCH 03/12] Update publishing docs --- documentation/publishing.md | 44 +++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/documentation/publishing.md b/documentation/publishing.md index 825e42d982..1f5302b767 100644 --- a/documentation/publishing.md +++ b/documentation/publishing.md @@ -63,3 +63,47 @@ Release Please will not create a new release PR if it thinks there is a pending To fix this, check whether any closed PRs still have the `autorelease: pending` or `autorelease: triggered` labels, and remove them. [See the Release Please docs for more information](https://github.com/googleapis/release-please?tab=readme-ov-file#release-please-bot-does-not-create-a-release-pr-why). + +## Dependencies between packages + +We’ve defined (peer) dependencies between our packages, in order to simplify the install process. +For example, our React package has a peer dependency on our CSS package. +When installing our React package, the correct version of our CSS package is automatically installed with it. + +The dependency tree looks like this: + +```mermaid +graph LR + RI["React icons"] --> React + Tokens --> CSS + Assets --> CSS + CSS --> React +``` + +These dependencies mean we have to pay some extra attention when publishing. +Generally, the dependencies between our packages our defined using [PNPM’s `workspace:*` feature](https://pnpm.io/workspaces#publishing-workspace-packages). +This means that when publishing our upstream packages (CSS and React), the latest version of our downstream packages (tokens, assets and React icons) +are defined as dependencies. + +This works, as long as the publish at least includes new versions of both our CSS and React packages. +But say we do a publish which only includes a new version of our tokens and assets packages. +They get a new version, but our CSS and React packages don’t have any changes, which means they don’t get new versions. +This means the latest version of our CSS package has a peer dependency on an older version of our tokens package. + +To fix this, we can manually add the latest version of our tokens package as a peer dependency of our CSS package. +In other words, we’d replace `"@amsterdam/design-system-tokens": "workspace:*"` with `"@amsterdam/design-system-tokens": "1.2.3"`. +After this, don’t forget to run `pnpm i` to update the lockfile. +The changes to the `package.json` and the lockfile mean we can release a new version of our CSS package, which will contain the correct peer dependency. + +Seeing as our CSS package is itself also a peer dependency of our React package, in the most extreme case we would have to do something like: + +1. Release a new version of our tokens and / or assets packages only +2. Manually change the peer dependency of our CSS package and release that +3. Manually change the peer dependency of our React package and release that + +This probably won’t happen very often, seeing as we usually make changes to both our CSS and React packages in between publishes, +but in the future it might. + +Manually changing a peer dependency of an upstream package means it’s defined statically, not dynamically. +For the next release of our upstream package, we probably want to change it back to a dynamic definition (i.e. `workspace:*`). +Don’t forget to run `pnpm i` after doing this, to update the lockfile. From 6d30e1870bd13a0b4021f7877a59ef689c2c885e Mon Sep 17 00:00:00 2001 From: Aram Limpens Date: Fri, 19 Apr 2024 14:31:49 +0200 Subject: [PATCH 04/12] Add periods --- documentation/publishing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/publishing.md b/documentation/publishing.md index 1f5302b767..04e8526aa0 100644 --- a/documentation/publishing.md +++ b/documentation/publishing.md @@ -97,9 +97,9 @@ The changes to the `package.json` and the lockfile mean we can release a new ver Seeing as our CSS package is itself also a peer dependency of our React package, in the most extreme case we would have to do something like: -1. Release a new version of our tokens and / or assets packages only -2. Manually change the peer dependency of our CSS package and release that -3. Manually change the peer dependency of our React package and release that +1. Release a new version of our tokens and / or assets packages only. +2. Manually change the peer dependency of our CSS package and release that. +3. Manually change the peer dependency of our React package and release that. This probably won’t happen very often, seeing as we usually make changes to both our CSS and React packages in between publishes, but in the future it might. From eda0095f58d575145217bec17196ca743db32349 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Fri, 19 Apr 2024 21:16:22 +0200 Subject: [PATCH 05/12] Apply suggestions from code review Co-authored-by: Ruben Sibon --- documentation/publishing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/publishing.md b/documentation/publishing.md index 04e8526aa0..ee4bd3c50a 100644 --- a/documentation/publishing.md +++ b/documentation/publishing.md @@ -66,7 +66,7 @@ To fix this, check whether any closed PRs still have the `autorelease: pending` ## Dependencies between packages -We’ve defined (peer) dependencies between our packages, in order to simplify the install process. +We’ve defined (peer) dependencies between our packages, to simplify the installation process. For example, our React package has a peer dependency on our CSS package. When installing our React package, the correct version of our CSS package is automatically installed with it. From 0adda1a13bbf4a2a1096e3d6fc81df1c03aae680 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Fri, 19 Apr 2024 21:16:54 +0200 Subject: [PATCH 06/12] Apply suggestions from code review --- documentation/publishing.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/documentation/publishing.md b/documentation/publishing.md index ee4bd3c50a..0b20e4bd35 100644 --- a/documentation/publishing.md +++ b/documentation/publishing.md @@ -82,28 +82,26 @@ graph LR These dependencies mean we have to pay some extra attention when publishing. Generally, the dependencies between our packages our defined using [PNPM’s `workspace:*` feature](https://pnpm.io/workspaces#publishing-workspace-packages). -This means that when publishing our upstream packages (CSS and React), the latest version of our downstream packages (tokens, assets and React icons) -are defined as dependencies. +This means that when publishing our upstream packages (CSS and React), the latest version of our downstream packages (tokens, assets, and React icons) are defined as dependencies. -This works, as long as the publish at least includes new versions of both our CSS and React packages. -But say we do a publish which only includes a new version of our tokens and assets packages. +This works, as long as the publishing at least includes new versions of both our CSS and React packages. +But say, we do a publishing which only includes a new version of our tokens and assets packages. They get a new version, but our CSS and React packages don’t have any changes, which means they don’t get new versions. This means the latest version of our CSS package has a peer dependency on an older version of our tokens package. To fix this, we can manually add the latest version of our tokens package as a peer dependency of our CSS package. In other words, we’d replace `"@amsterdam/design-system-tokens": "workspace:*"` with `"@amsterdam/design-system-tokens": "1.2.3"`. -After this, don’t forget to run `pnpm i` to update the lockfile. +After this, please don't forget to run `pnpm i` to update the lockfile. The changes to the `package.json` and the lockfile mean we can release a new version of our CSS package, which will contain the correct peer dependency. Seeing as our CSS package is itself also a peer dependency of our React package, in the most extreme case we would have to do something like: -1. Release a new version of our tokens and / or assets packages only. +1. Release a new version of our tokens or assets packages only. 2. Manually change the peer dependency of our CSS package and release that. 3. Manually change the peer dependency of our React package and release that. -This probably won’t happen very often, seeing as we usually make changes to both our CSS and React packages in between publishes, -but in the future it might. +This probably won’t happen frequently, seeing as we usually modify both our CSS and React packages in between publishes, but in the future it might. Manually changing a peer dependency of an upstream package means it’s defined statically, not dynamically. -For the next release of our upstream package, we probably want to change it back to a dynamic definition (i.e. `workspace:*`). -Don’t forget to run `pnpm i` after doing this, to update the lockfile. +For the next release of our upstream package, we likely want to change it back to a dynamic definition (i.e. `workspace:*`). +Please remember to run `pnpm i` after doing this, to update the lockfile. From 12a3624e3993b82435d0ec6e23609c4094b2459d Mon Sep 17 00:00:00 2001 From: Aram Limpens Date: Wed, 24 Apr 2024 09:04:05 +0200 Subject: [PATCH 07/12] Fix small typo's --- documentation/publishing.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/documentation/publishing.md b/documentation/publishing.md index 0b20e4bd35..865e7dff79 100644 --- a/documentation/publishing.md +++ b/documentation/publishing.md @@ -58,7 +58,7 @@ This will cause a major version bump in both packages on release and add its des Release Please uses labels to determine the status of a release. A release PR gets the label `autorelease: pending` or `autorelease: triggered`. When running the action again, the PR with those labels gets released, and the labels should be removed. -However, due to GitHub API failures, it's possible that the label was not removed correctly upon a previous release and Release Please thinks that the previous release is still pending. +However, due to GitHub API failures, it’s possible that the label was not removed correctly upon a previous release and Release Please thinks that the previous release is still pending. Release Please will not create a new release PR if it thinks there is a pending release. To fix this, check whether any closed PRs still have the `autorelease: pending` or `autorelease: triggered` labels, and remove them. @@ -81,17 +81,17 @@ graph LR ``` These dependencies mean we have to pay some extra attention when publishing. -Generally, the dependencies between our packages our defined using [PNPM’s `workspace:*` feature](https://pnpm.io/workspaces#publishing-workspace-packages). +Generally, the dependencies between our packages are defined using [PNPM’s `workspace:*` feature](https://pnpm.io/workspaces#publishing-workspace-packages). This means that when publishing our upstream packages (CSS and React), the latest version of our downstream packages (tokens, assets, and React icons) are defined as dependencies. -This works, as long as the publishing at least includes new versions of both our CSS and React packages. -But say, we do a publishing which only includes a new version of our tokens and assets packages. +This works, as long as the release at least includes new versions of both our CSS and React packages. +But say, we do a release which only includes a new version of our tokens and assets packages. They get a new version, but our CSS and React packages don’t have any changes, which means they don’t get new versions. This means the latest version of our CSS package has a peer dependency on an older version of our tokens package. To fix this, we can manually add the latest version of our tokens package as a peer dependency of our CSS package. In other words, we’d replace `"@amsterdam/design-system-tokens": "workspace:*"` with `"@amsterdam/design-system-tokens": "1.2.3"`. -After this, please don't forget to run `pnpm i` to update the lockfile. +After this, please don’t forget to run `pnpm i` to update the lockfile. The changes to the `package.json` and the lockfile mean we can release a new version of our CSS package, which will contain the correct peer dependency. Seeing as our CSS package is itself also a peer dependency of our React package, in the most extreme case we would have to do something like: @@ -100,7 +100,7 @@ Seeing as our CSS package is itself also a peer dependency of our React package, 2. Manually change the peer dependency of our CSS package and release that. 3. Manually change the peer dependency of our React package and release that. -This probably won’t happen frequently, seeing as we usually modify both our CSS and React packages in between publishes, but in the future it might. +This probably won’t happen frequently, seeing as we usually modify both our CSS and React packages in between releases, but in the future it might. Manually changing a peer dependency of an upstream package means it’s defined statically, not dynamically. For the next release of our upstream package, we likely want to change it back to a dynamic definition (i.e. `workspace:*`). From 813055b49c27bc0c31deb8086b34931884f8a250 Mon Sep 17 00:00:00 2001 From: Aram Limpens Date: Wed, 24 Apr 2024 09:06:45 +0200 Subject: [PATCH 08/12] Use correct casing for CSS, fix small typo --- packages/react/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/react/README.md b/packages/react/README.md index 1c4c892c09..6e5c7ee3f2 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -42,7 +42,7 @@ export default App; For applications, the large text and ample white space of the theme can be counterproductive. That’s why there is a compact mode. -To use the compact mode, import the compact css **after** theme css, like so: +To use the compact mode, import the compact CSS **after** the theme CSS, like so: ```javascript import "@amsterdam/design-system-tokens/dist/index.css"; From a7a44c8cc1a42e7cecbb1bb21084986779c09ef7 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Wed, 24 Apr 2024 15:15:08 +0200 Subject: [PATCH 09/12] Make dependency documentation more compact --- documentation/publishing.md | 43 +++++++++++++++---------------------- 1 file changed, 17 insertions(+), 26 deletions(-) diff --git a/documentation/publishing.md b/documentation/publishing.md index 865e7dff79..336c5fee01 100644 --- a/documentation/publishing.md +++ b/documentation/publishing.md @@ -66,42 +66,33 @@ To fix this, check whether any closed PRs still have the `autorelease: pending` ## Dependencies between packages -We’ve defined (peer) dependencies between our packages, to simplify the installation process. -For example, our React package has a peer dependency on our CSS package. -When installing our React package, the correct version of our CSS package is automatically installed with it. +We’ve established dependencies between our packages for smoother installation. +For instance, our React package relies on our CSS package. +When you install React, the corresponding version of our CSS package is automatically included. -The dependency tree looks like this: +Here’s the dependency structure: ```mermaid graph LR - RI["React icons"] --> React + RI["React Icons"] --> React Tokens --> CSS Assets --> CSS CSS --> React ``` -These dependencies mean we have to pay some extra attention when publishing. -Generally, the dependencies between our packages are defined using [PNPM’s `workspace:*` feature](https://pnpm.io/workspaces#publishing-workspace-packages). -This means that when publishing our upstream packages (CSS and React), the latest version of our downstream packages (tokens, assets, and React icons) are defined as dependencies. +Managing these dependencies requires extra attention when publishing. +We use [PNPM’s workspace feature](https://pnpm.io/workspaces#publishing-workspace-packages) to define dependencies among our packages. +When we publish upstream packages like CSS and React, the latest specific versions of downstream packages (Tokens, Assets, and React Icons) get listed as dependencies. -This works, as long as the release at least includes new versions of both our CSS and React packages. -But say, we do a release which only includes a new version of our tokens and assets packages. -They get a new version, but our CSS and React packages don’t have any changes, which means they don’t get new versions. -This means the latest version of our CSS package has a peer dependency on an older version of our tokens package. +This setup works well when we update both CSS and React in a release. +However, issues arise if a release only updates Tokens and Assets without changes to CSS or React. +The latest version of CSS then depends on an older version of Tokens. -To fix this, we can manually add the latest version of our tokens package as a peer dependency of our CSS package. -In other words, we’d replace `"@amsterdam/design-system-tokens": "workspace:*"` with `"@amsterdam/design-system-tokens": "1.2.3"`. -After this, please don’t forget to run `pnpm i` to update the lockfile. -The changes to the `package.json` and the lockfile mean we can release a new version of our CSS package, which will contain the correct peer dependency. +To resolve this, we can manually let CSS depend on the latest version of Tokens. +We replace `"@amsterdam/design-system-tokens": "workspace:*"` with `"@amsterdam/design-system-tokens": "x.y.z"` and run `pnpm i` to update the lockfile. +These changes enable a correct peer dependency in the new CSS package. -Seeing as our CSS package is itself also a peer dependency of our React package, in the most extreme case we would have to do something like: +After that, restore the dynamic dependency (`workspace:*`) and run `pnpm i` again. -1. Release a new version of our tokens or assets packages only. -2. Manually change the peer dependency of our CSS package and release that. -3. Manually change the peer dependency of our React package and release that. - -This probably won’t happen frequently, seeing as we usually modify both our CSS and React packages in between releases, but in the future it might. - -Manually changing a peer dependency of an upstream package means it’s defined statically, not dynamically. -For the next release of our upstream package, we likely want to change it back to a dynamic definition (i.e. `workspace:*`). -Please remember to run `pnpm i` after doing this, to update the lockfile. +The most extreme case requires us to release a new version of Tokens or Assets only, then update and release CSS , then update and release React. +Although infrequent, this scenario might occur in the future. From bba04522283dfd5c30ac2ddcca5cb57e27381f77 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Wed, 24 Apr 2024 15:24:22 +0200 Subject: [PATCH 10/12] =?UTF-8?q?Mention=20dependencies=20in=20the=20?= =?UTF-8?q?=E2=80=98Getting=20started=E2=80=99=C2=A0section?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- packages/react/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/react/README.md b/packages/react/README.md index 6e5c7ee3f2..ad65d42512 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -18,11 +18,13 @@ Make sure you specify the exact version as dependency, so you can schedule to up ## Getting started -Install the React packages, like so: +Install the React package: `npm install @amsterdam/design-system-react` -Import the components and CSS you need, for example: +This will automatically add separate packages containing our design tokens, assets, icons, and stylesheets. + +Import the components and stylesheets you need, for example: ```javascript import { Paragraph } from "@amsterdam/design-system-react"; From 63c89c7e360c881256bf6fbcdca56b7f9530874f Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Thu, 25 Apr 2024 10:35:26 +0200 Subject: [PATCH 11/12] Apply suggestions from code review Co-authored-by: Aram <37216945+alimpens@users.noreply.github.com> --- documentation/publishing.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/documentation/publishing.md b/documentation/publishing.md index 336c5fee01..5f4bb95fb7 100644 --- a/documentation/publishing.md +++ b/documentation/publishing.md @@ -68,7 +68,7 @@ To fix this, check whether any closed PRs still have the `autorelease: pending` We’ve established dependencies between our packages for smoother installation. For instance, our React package relies on our CSS package. -When you install React, the corresponding version of our CSS package is automatically included. +When you install our React package, the corresponding version of our CSS package is automatically included. Here’s the dependency structure: @@ -81,7 +81,7 @@ graph LR ``` Managing these dependencies requires extra attention when publishing. -We use [PNPM’s workspace feature](https://pnpm.io/workspaces#publishing-workspace-packages) to define dependencies among our packages. +We use [PNPM’s workspace feature](https://pnpm.io/workspaces#publishing-workspace-packages) to define dependencies between our packages. When we publish upstream packages like CSS and React, the latest specific versions of downstream packages (Tokens, Assets, and React Icons) get listed as dependencies. This setup works well when we update both CSS and React in a release. @@ -90,9 +90,9 @@ The latest version of CSS then depends on an older version of Tokens. To resolve this, we can manually let CSS depend on the latest version of Tokens. We replace `"@amsterdam/design-system-tokens": "workspace:*"` with `"@amsterdam/design-system-tokens": "x.y.z"` and run `pnpm i` to update the lockfile. -These changes enable a correct peer dependency in the new CSS package. +We then release a new version of our CSS package, with the correct peer dependency. After that, restore the dynamic dependency (`workspace:*`) and run `pnpm i` again. -The most extreme case requires us to release a new version of Tokens or Assets only, then update and release CSS , then update and release React. +The most extreme case requires us to release a new version of Tokens or Assets only, then update and release CSS, then update and release React. Although infrequent, this scenario might occur in the future. From 13b968de33aa7d2e38088ad976c0e83f1a6b1189 Mon Sep 17 00:00:00 2001 From: Vincent Smedinga Date: Thu, 25 Apr 2024 10:38:58 +0200 Subject: [PATCH 12/12] Improve sentence --- documentation/publishing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/publishing.md b/documentation/publishing.md index 5f4bb95fb7..ee55c47109 100644 --- a/documentation/publishing.md +++ b/documentation/publishing.md @@ -92,7 +92,7 @@ To resolve this, we can manually let CSS depend on the latest version of Tokens. We replace `"@amsterdam/design-system-tokens": "workspace:*"` with `"@amsterdam/design-system-tokens": "x.y.z"` and run `pnpm i` to update the lockfile. We then release a new version of our CSS package, with the correct peer dependency. -After that, restore the dynamic dependency (`workspace:*`) and run `pnpm i` again. +After that, consider restoring the dynamic dependency (`workspace:*`) and updating the lockfile (`pnpm i`) accordingly. The most extreme case requires us to release a new version of Tokens or Assets only, then update and release CSS, then update and release React. Although infrequent, this scenario might occur in the future.