From 778a16f4167349c84680967a49cd8a083b44165a Mon Sep 17 00:00:00 2001 From: Ulises Gascon Date: Tue, 22 Oct 2024 21:41:24 +0200 Subject: [PATCH 01/12] adr: add policy on using caret (^) or tilde (~) with dependencies Signed-off-by: Ulises Gascon --- ...policy-on-using-caret-with-dependencies.md | 87 +++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 docs/adr/002-policy-on-using-caret-with-dependencies.md diff --git a/docs/adr/002-policy-on-using-caret-with-dependencies.md b/docs/adr/002-policy-on-using-caret-with-dependencies.md new file mode 100644 index 0000000..fc01d13 --- /dev/null +++ b/docs/adr/002-policy-on-using-caret-with-dependencies.md @@ -0,0 +1,87 @@ +# ADR 002: Policy on Using Caret (`^`) or tilde (`~`) with Dependencies in `package.json` + +## Status +Proposed + +## Submitters +- Ulises Gascón (@UlisesGascon) + +## Decision Owners +- Express TC (@expressjs/express-tc) + +## Context +Historically, the Express project has avoided using the caret (`^`) in the `package.json` files for its own dependencies. This decision aims to review whether this practice should continue or if adjustments are needed. + +**Why do we need this decision?** +Clarifying the policy on using caret (`^`) helps to ensure consistency across the Express ecosystem, reduce unnecessary maintenance, and prevent unexpected dependency updates. It also addresses concerns about the balance between keeping dependencies up-to-date and avoiding regressions. + +**What problem does it solve or avoid?** +This decision aims to avoid unexpected updates and regressions from external dependencies while reducing the maintenance burden of frequently updating pinned dependencies. + +**Are there any existing issues/discussions/pull requests related to this?** +- [Discussion: Using caret (^) with our own dependencies #279](https://github.com/expressjs/discussions/issues/279) +- [expressjs/express#6017 (comment)](https://github.com/expressjs/express/issues/6017) + +## Decision +We will adopt a policy where the caret (`^`) symbol is used for dependencies owned within the Express ecosystem (e.g., `body-parser` for Express), but continue to avoid using it for third-party dependencies that we do not maintain. + +**What will be done?** +- Update the `package.json` files to use `^` for our own dependencies. +- Continue using fixed versions (no caret or tilde) for external dependencies to minimize risks of unintended updates. + +**Note on `^` vs. `~`:** +- `^` allows updates to the most recent minor or patch version, offering greater flexibility and reducing the need for frequent manual updates. For example, `^1.2.3` will accept updates to `1.3.0`, `1.4.0`, but not `2.0.0`. +- `~` is more conservative, only allowing updates to patch versions. For example, `~1.2.3` will accept updates to `1.2.4`, `1.2.5`, but not `1.3.0`. +- For our own dependencies that adhere strictly to semver, `^` is preferred over `~`, while for third-party libraries, a stricter versioning strategy is maintained to prevent unexpected regressions. + +**What will not be done?** +- We will not use `^` or `~` for external dependencies that are not maintained by the Express organization, as they could introduce unexpected changes. +- We won't force to use `^` or `~` for own dependencies if there is a reason to use a fix version and it is properly documented. + +## Rationale + +**Alternatives Considered:** +- **Alternative 1:** Use `^` for all dependencies, including third-party libraries. +- **Reason for rejection:** This could increase the risk of unintended regressions and security issues from third-party updates. +- **Alternative 2:** Continue pinning all dependencies, including internal ones, to specific versions. +- **Reason for rejection:** This approach requires frequent updates and increases the maintenance burden, as each minor or patch update requires a new release. + +**Pros and Cons**: + +**Pros**: +- Reduces the number of PRs for updating our own dependencies. +- Allows for quicker adoption of minor and patch updates within the Express ecosystem. +- Users are still protected by lockfiles, mitigating the risk of regressions. + +**Cons**: +- There is still a risk of minor regressions from updates, even within internally managed dependencies. +- Requires discipline in maintaining lockfiles to ensure stability for end users. + +**Why is this decision the best option?** +This decision strikes a balance between reducing maintenance effort and managing risk. It allows Express to leverage the benefits of semver for our own dependencies while maintaining control over external libraries that could introduce breaking changes. + +## Consequences + +**Positive Impact**: +- Fewer manual updates required for internally managed dependencies. +- Users benefit from improvements and fixes in internal packages more quickly. + +**Negative Impact**: +- Potential risk of regressions if an internal dependency introduces a breaking change in a minor update. +- Users relying on strict version control may need to adjust their expectations when using our own dependencies. + +**Mitigations**: +- Strong test coverage and CI checks will help catch potential issues early. +- Clear communication in documentation and release notes to inform users of the updated dependency policy. +- Ensure that we are following strict semver when releasing our own libraries. + +## Implementation + +- **Phase 1**: Update `package.json` files across all packages to apply `^` for our own dependencies. +- **Phase 2**: Review and adjust documentation to include the new policy on dependency versioning. + +## References +- [NPM semver documentation](https://docs.npmjs.com/cli/v6/using-npm/semver) + +## Changelog +- **[2024-10-22]**: @UlisesGascon - Initial draft of ADR for using caret (`^`) or tilde (`~`) with our own dependencies. From 3893d04480b7785e413cfca395ed499040e60674 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulises=20Gasc=C3=B3n?= Date: Thu, 13 Feb 2025 09:47:07 +0100 Subject: [PATCH 02/12] Update docs/adr/002-policy-on-using-caret-with-dependencies.md Co-authored-by: Chris de Almeida --- docs/adr/002-policy-on-using-caret-with-dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/002-policy-on-using-caret-with-dependencies.md b/docs/adr/002-policy-on-using-caret-with-dependencies.md index fc01d13..22d9a23 100644 --- a/docs/adr/002-policy-on-using-caret-with-dependencies.md +++ b/docs/adr/002-policy-on-using-caret-with-dependencies.md @@ -36,7 +36,7 @@ We will adopt a policy where the caret (`^`) symbol is used for dependencies own **What will not be done?** - We will not use `^` or `~` for external dependencies that are not maintained by the Express organization, as they could introduce unexpected changes. -- We won't force to use `^` or `~` for own dependencies if there is a reason to use a fix version and it is properly documented. +- We won't force to use `^` or `~` for own dependencies if there is a reason to use a pinned version and it is properly documented. ## Rationale From 6e35bf8e49401f302175d99116fba08465590184 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulises=20Gasc=C3=B3n?= Date: Thu, 13 Feb 2025 09:47:15 +0100 Subject: [PATCH 03/12] Update docs/adr/002-policy-on-using-caret-with-dependencies.md Co-authored-by: Wes Todd --- docs/adr/002-policy-on-using-caret-with-dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/002-policy-on-using-caret-with-dependencies.md b/docs/adr/002-policy-on-using-caret-with-dependencies.md index 22d9a23..bec813a 100644 --- a/docs/adr/002-policy-on-using-caret-with-dependencies.md +++ b/docs/adr/002-policy-on-using-caret-with-dependencies.md @@ -77,7 +77,7 @@ This decision strikes a balance between reducing maintenance effort and managing ## Implementation -- **Phase 1**: Update `package.json` files across all packages to apply `^` for our own dependencies. +- **Phase 1**: Update `package.json` files across all packages to apply `^` for all dependencies. - **Phase 2**: Review and adjust documentation to include the new policy on dependency versioning. ## References From ea497f5179d9aa1696b7fc1a5dce6fab2693ac39 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulises=20Gasc=C3=B3n?= Date: Thu, 13 Feb 2025 09:47:27 +0100 Subject: [PATCH 04/12] Update docs/adr/002-policy-on-using-caret-with-dependencies.md Co-authored-by: Wes Todd --- docs/adr/002-policy-on-using-caret-with-dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/002-policy-on-using-caret-with-dependencies.md b/docs/adr/002-policy-on-using-caret-with-dependencies.md index bec813a..768558d 100644 --- a/docs/adr/002-policy-on-using-caret-with-dependencies.md +++ b/docs/adr/002-policy-on-using-caret-with-dependencies.md @@ -26,7 +26,7 @@ This decision aims to avoid unexpected updates and regressions from external dep We will adopt a policy where the caret (`^`) symbol is used for dependencies owned within the Express ecosystem (e.g., `body-parser` for Express), but continue to avoid using it for third-party dependencies that we do not maintain. **What will be done?** -- Update the `package.json` files to use `^` for our own dependencies. +- Update the `package.json` files to use `^` for all dependencies (both prod and dev). - Continue using fixed versions (no caret or tilde) for external dependencies to minimize risks of unintended updates. **Note on `^` vs. `~`:** From 16ece44c51454d988f2814d2302b60f87ad89f30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulises=20Gasc=C3=B3n?= Date: Thu, 13 Feb 2025 09:47:36 +0100 Subject: [PATCH 05/12] Update docs/adr/002-policy-on-using-caret-with-dependencies.md Co-authored-by: Wes Todd --- docs/adr/002-policy-on-using-caret-with-dependencies.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/adr/002-policy-on-using-caret-with-dependencies.md b/docs/adr/002-policy-on-using-caret-with-dependencies.md index 768558d..56ae6b3 100644 --- a/docs/adr/002-policy-on-using-caret-with-dependencies.md +++ b/docs/adr/002-policy-on-using-caret-with-dependencies.md @@ -27,7 +27,6 @@ We will adopt a policy where the caret (`^`) symbol is used for dependencies own **What will be done?** - Update the `package.json` files to use `^` for all dependencies (both prod and dev). -- Continue using fixed versions (no caret or tilde) for external dependencies to minimize risks of unintended updates. **Note on `^` vs. `~`:** - `^` allows updates to the most recent minor or patch version, offering greater flexibility and reducing the need for frequent manual updates. For example, `^1.2.3` will accept updates to `1.3.0`, `1.4.0`, but not `2.0.0`. From 9f5c0b50f23a36c5c1ced1e9841a8d9ef9cbbfe3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulises=20Gasc=C3=B3n?= Date: Thu, 13 Feb 2025 09:47:46 +0100 Subject: [PATCH 06/12] Update docs/adr/002-policy-on-using-caret-with-dependencies.md Co-authored-by: Wes Todd --- docs/adr/002-policy-on-using-caret-with-dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/002-policy-on-using-caret-with-dependencies.md b/docs/adr/002-policy-on-using-caret-with-dependencies.md index 56ae6b3..af8ba59 100644 --- a/docs/adr/002-policy-on-using-caret-with-dependencies.md +++ b/docs/adr/002-policy-on-using-caret-with-dependencies.md @@ -16,7 +16,7 @@ Historically, the Express project has avoided using the caret (`^`) in the `pack Clarifying the policy on using caret (`^`) helps to ensure consistency across the Express ecosystem, reduce unnecessary maintenance, and prevent unexpected dependency updates. It also addresses concerns about the balance between keeping dependencies up-to-date and avoiding regressions. **What problem does it solve or avoid?** -This decision aims to avoid unexpected updates and regressions from external dependencies while reducing the maintenance burden of frequently updating pinned dependencies. +This decision aims to reduce the maintenance burden of frequently updating pinned dependencies. **Are there any existing issues/discussions/pull requests related to this?** - [Discussion: Using caret (^) with our own dependencies #279](https://github.com/expressjs/discussions/issues/279) From 7a3e432b3be6f9545dff4e3a907187aa18efaae0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulises=20Gasc=C3=B3n?= Date: Thu, 13 Feb 2025 09:47:55 +0100 Subject: [PATCH 07/12] Update docs/adr/002-policy-on-using-caret-with-dependencies.md Co-authored-by: Wes Todd --- docs/adr/002-policy-on-using-caret-with-dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/002-policy-on-using-caret-with-dependencies.md b/docs/adr/002-policy-on-using-caret-with-dependencies.md index af8ba59..dc6e790 100644 --- a/docs/adr/002-policy-on-using-caret-with-dependencies.md +++ b/docs/adr/002-policy-on-using-caret-with-dependencies.md @@ -10,7 +10,7 @@ Proposed - Express TC (@expressjs/express-tc) ## Context -Historically, the Express project has avoided using the caret (`^`) in the `package.json` files for its own dependencies. This decision aims to review whether this practice should continue or if adjustments are needed. +Historically, the Express project has avoided using the caret (`^`) in the `package.json` files for its own dependencies. This proposal aims to review whether this practice should continue or if adjustments are needed. **Why do we need this decision?** Clarifying the policy on using caret (`^`) helps to ensure consistency across the Express ecosystem, reduce unnecessary maintenance, and prevent unexpected dependency updates. It also addresses concerns about the balance between keeping dependencies up-to-date and avoiding regressions. From f6e08a238b555fb7c24b7b6f370c1debb0c61091 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulises=20Gasc=C3=B3n?= Date: Thu, 13 Feb 2025 09:48:10 +0100 Subject: [PATCH 08/12] Update docs/adr/002-policy-on-using-caret-with-dependencies.md Co-authored-by: Wes Todd --- docs/adr/002-policy-on-using-caret-with-dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/002-policy-on-using-caret-with-dependencies.md b/docs/adr/002-policy-on-using-caret-with-dependencies.md index dc6e790..b0c7567 100644 --- a/docs/adr/002-policy-on-using-caret-with-dependencies.md +++ b/docs/adr/002-policy-on-using-caret-with-dependencies.md @@ -23,7 +23,7 @@ This decision aims to reduce the maintenance burden of frequently updating pinne - [expressjs/express#6017 (comment)](https://github.com/expressjs/express/issues/6017) ## Decision -We will adopt a policy where the caret (`^`) symbol is used for dependencies owned within the Express ecosystem (e.g., `body-parser` for Express), but continue to avoid using it for third-party dependencies that we do not maintain. +We will adopt a policy where the caret (`^`) symbol is used for dependencies all dependencies. **What will be done?** - Update the `package.json` files to use `^` for all dependencies (both prod and dev). From e5646934252a63044b5f7d61fe73e0aea0620b2c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulises=20Gasc=C3=B3n?= Date: Thu, 13 Feb 2025 09:55:26 +0100 Subject: [PATCH 09/12] Update docs/adr/002-policy-on-using-caret-with-dependencies.md --- docs/adr/002-policy-on-using-caret-with-dependencies.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/adr/002-policy-on-using-caret-with-dependencies.md b/docs/adr/002-policy-on-using-caret-with-dependencies.md index b0c7567..5f0a3e0 100644 --- a/docs/adr/002-policy-on-using-caret-with-dependencies.md +++ b/docs/adr/002-policy-on-using-caret-with-dependencies.md @@ -40,9 +40,7 @@ We will adopt a policy where the caret (`^`) symbol is used for dependencies all ## Rationale **Alternatives Considered:** -- **Alternative 1:** Use `^` for all dependencies, including third-party libraries. -- **Reason for rejection:** This could increase the risk of unintended regressions and security issues from third-party updates. -- **Alternative 2:** Continue pinning all dependencies, including internal ones, to specific versions. +- **Alternative:** Continue pinning all dependencies, including internal ones, to specific versions. - **Reason for rejection:** This approach requires frequent updates and increases the maintenance burden, as each minor or patch update requires a new release. **Pros and Cons**: From e40ea38be4fbb6eb2ef9ecd251c45060c4fc105b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulises=20Gasc=C3=B3n?= Date: Thu, 13 Feb 2025 09:55:34 +0100 Subject: [PATCH 10/12] Update docs/adr/002-policy-on-using-caret-with-dependencies.md --- docs/adr/002-policy-on-using-caret-with-dependencies.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/adr/002-policy-on-using-caret-with-dependencies.md b/docs/adr/002-policy-on-using-caret-with-dependencies.md index 5f0a3e0..8aaa399 100644 --- a/docs/adr/002-policy-on-using-caret-with-dependencies.md +++ b/docs/adr/002-policy-on-using-caret-with-dependencies.md @@ -34,8 +34,7 @@ We will adopt a policy where the caret (`^`) symbol is used for dependencies all - For our own dependencies that adhere strictly to semver, `^` is preferred over `~`, while for third-party libraries, a stricter versioning strategy is maintained to prevent unexpected regressions. **What will not be done?** -- We will not use `^` or `~` for external dependencies that are not maintained by the Express organization, as they could introduce unexpected changes. -- We won't force to use `^` or `~` for own dependencies if there is a reason to use a pinned version and it is properly documented. +- We won't force to use `^` or `~` for any dependency if there is a reason to use a pinned version and it is properly documented. ## Rationale From d2e0f58851e8788963f4331b43397def85e0daa1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulises=20Gasc=C3=B3n?= Date: Thu, 13 Feb 2025 09:55:42 +0100 Subject: [PATCH 11/12] Update docs/adr/002-policy-on-using-caret-with-dependencies.md --- docs/adr/002-policy-on-using-caret-with-dependencies.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/adr/002-policy-on-using-caret-with-dependencies.md b/docs/adr/002-policy-on-using-caret-with-dependencies.md index 8aaa399..cbe34f8 100644 --- a/docs/adr/002-policy-on-using-caret-with-dependencies.md +++ b/docs/adr/002-policy-on-using-caret-with-dependencies.md @@ -30,8 +30,7 @@ We will adopt a policy where the caret (`^`) symbol is used for dependencies all **Note on `^` vs. `~`:** - `^` allows updates to the most recent minor or patch version, offering greater flexibility and reducing the need for frequent manual updates. For example, `^1.2.3` will accept updates to `1.3.0`, `1.4.0`, but not `2.0.0`. -- `~` is more conservative, only allowing updates to patch versions. For example, `~1.2.3` will accept updates to `1.2.4`, `1.2.5`, but not `1.3.0`. -- For our own dependencies that adhere strictly to semver, `^` is preferred over `~`, while for third-party libraries, a stricter versioning strategy is maintained to prevent unexpected regressions. +- `~` is more conservative, only allowing updates to patch versions. For example, `~1.2.3` will accept updates to `1.2.4`, `1.2.5`, but not `1.3.0`. Some Node.js legacy versions only support this, like Node@0.8. **What will not be done?** - We won't force to use `^` or `~` for any dependency if there is a reason to use a pinned version and it is properly documented. From 5f56c7a2923b1338df538b8ee42a159354c0cdf5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulises=20Gasc=C3=B3n?= Date: Mon, 3 Mar 2025 22:20:45 +0100 Subject: [PATCH 12/12] Update docs/adr/002-policy-on-using-caret-with-dependencies.md Co-authored-by: Wes Todd --- docs/adr/002-policy-on-using-caret-with-dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/002-policy-on-using-caret-with-dependencies.md b/docs/adr/002-policy-on-using-caret-with-dependencies.md index cbe34f8..70daef0 100644 --- a/docs/adr/002-policy-on-using-caret-with-dependencies.md +++ b/docs/adr/002-policy-on-using-caret-with-dependencies.md @@ -72,7 +72,7 @@ This decision strikes a balance between reducing maintenance effort and managing ## Implementation -- **Phase 1**: Update `package.json` files across all packages to apply `^` for all dependencies. +- **Phase 1**: Update `package.json` files across all packages to apply `^` for all dependencies which support greater than node@0.10.0. - **Phase 2**: Review and adjust documentation to include the new policy on dependency versioning. ## References