Add policy on using caret (^) or tilde (~) with dependencies #290

UlisesGascon · 2024-10-22T19:43:15Z

Policy on using caret (^) or tilde (~) with dependencies

Establishes policy for using caret (^) or tilde (~) for dependencies that we maintain while avoiding its use for third-party dependencies.
Explains the differences between caret (^) and tilde (~) version ranges.
Documents the rationale, alternatives considered, and implementation plan.

Context

Signed-off-by: Ulises Gascon <ulisesgascongonzalez@gmail.com>

ljharb · 2024-10-22T19:55:54Z

docs/adr/002-policy-on-using-caret-with-dependencies.md

+- [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.


why not also for third party deps? most maintainers don't backport fixes to previous minors.

Agreed, we should always use ^ and use dependencies/authors we trust, no need to fight the ecosystem.

Agreed!

Suggested change

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.

Suggested change

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 all dependencies.

ljharb · 2024-10-22T19:56:35Z

docs/adr/002-policy-on-using-caret-with-dependencies.md

+
+**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.


imo this risk is lower than the risk of dependency vulnerability/regression fixes from not being available to downstream users.

blakeembrey

TL;DR I think we should try to be high trust and good examples of OSS by treating all dependencies the same.

blakeembrey · 2024-10-22T20:40:10Z

docs/adr/002-policy-on-using-caret-with-dependencies.md

+- [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.


Agreed, we should always use ^ and use dependencies/authors we trust, no need to fight the ecosystem.

blakeembrey · 2024-10-22T20:41:10Z

docs/adr/002-policy-on-using-caret-with-dependencies.md

+- 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.


I'm not sure there's any reason to use ~ either, I think we would have used it instead of ^ due to supported NPM versions.

That's indeed the only reason express used ~, because v4 came out at a time when not every npm version supported ^.

wesleytodd

If @UlisesGascon is alright with the suggestions to use ^ for all, I tried to make change suggestions to everywhere I noticed where it was referenced. Personally I think the conservative approach used in earlier days is not necessary anymore and so am in favor of using it for all deps.

wesleytodd · 2024-10-24T14:35:15Z

docs/adr/002-policy-on-using-caret-with-dependencies.md

+- 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.


Suggested change

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.

wesleytodd · 2024-10-24T14:37:09Z

docs/adr/002-policy-on-using-caret-with-dependencies.md

+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.


Suggested change

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.

wesleytodd · 2024-10-24T14:37:36Z

docs/adr/002-policy-on-using-caret-with-dependencies.md

+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.


Suggested change

- 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).

wesleytodd · 2024-10-24T14:37:45Z

docs/adr/002-policy-on-using-caret-with-dependencies.md

+
+**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.


Suggested change

- Continue using fixed versions (no caret or tilde) for external dependencies to minimize risks of unintended updates.

wesleytodd · 2024-10-24T14:39:05Z

docs/adr/002-policy-on-using-caret-with-dependencies.md

+
+## Implementation
+
+- **Phase 1**: Update `package.json` files across all packages to apply `^` for our own dependencies.


Suggested change

- **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.

UlisesGascon · 2024-10-26T17:23:13Z

Worth mentioning that the caret (^) is not supported on Node@0.8, as noted in this comment. Therefore, this change might be considered semver-major in many scenarios unless we decide that dropping support for Node@0.8 is not a major change. 😄

ljharb · 2024-10-27T00:22:26Z

@UlisesGascon it's not supported on the npm that comes with node 0.8, but if you use nvm install-latest-npm to get the latest one, then it works just fine :-)

either way, i think it can be fine if you need a newer node to install it as long as it works in old node (albeit, not ideal)

bjohansebas · 2024-10-27T00:31:49Z

So we need to prepare the CI for the packages that still support node.js@0.8 before making any changes to the dependencies

ljharb · 2024-10-27T00:33:01Z

Yes, for any package that isn't already declaring engines, the first step should be testing (manual or automated) to determine on which versions it's already working - because those are the engines that it's non-breaking to declare.

bjohansebas · 2024-11-01T23:12:23Z

@expressjs/express-tc, the way forward is to update the CI, or do we prefer to do this in a major version when support for Node.js 0.8 is removed?

UlisesGascon requested a review from a team October 22, 2024 19:43

UlisesGascon self-assigned this Oct 22, 2024

UlisesGascon force-pushed the adr/dependecies branch from bb4078a to f8b639b Compare October 22, 2024 19:44

UlisesGascon mentioned this pull request Oct 22, 2024

Discussion: Using caret (^) with our own dependencies #279

Open

adr: add policy on using caret (^) or tilde (~) with dependencies

778a16f

Signed-off-by: Ulises Gascon <ulisesgascongonzalez@gmail.com>

UlisesGascon force-pushed the adr/dependecies branch from f8b639b to 778a16f Compare October 22, 2024 19:46

UlisesGascon mentioned this pull request Oct 22, 2024

docs: Add ADR template #291

Merged

ljharb reviewed Oct 22, 2024

View reviewed changes

blakeembrey reviewed Oct 22, 2024

View reviewed changes

wesleytodd requested changes Oct 24, 2024

View reviewed changes

yatiac mentioned this pull request Oct 25, 2024

Dependencies: parseurl@^1.3.3 pillarjs/router#132

Open

wesleytodd mentioned this pull request Oct 25, 2024

deps: parseurl@^1.3.3 pillarjs/router#133

Merged

dcastillogi mentioned this pull request Oct 25, 2024

deps: migrate from tilde to caret expressjs/session#999

Open

raiandexter0607 mentioned this pull request Oct 25, 2024

deps: ispromise@^4.0.0 pillarjs/router#135

Open

Machinarius mentioned this pull request Oct 25, 2024

deps: basic-auth@^2.0.1 expressjs/morgan#298

Open

This was referenced Oct 25, 2024

Dependencies: accepts@^1.3.8 expressjs/compression#198

Closed

Dependencies: vary@^1.1.2 expressjs/compression#199

Open

This was referenced Oct 25, 2024

Add caret for body-parser dependencies expressjs/body-parser#552

Open

Add caret to dependencies (fresh and setprototypeof) pillarjs/request#1

Open

jonchurch added the ADR label Nov 2, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add policy on using caret (^) or tilde (~) with dependencies #290

Add policy on using caret (^) or tilde (~) with dependencies #290

UlisesGascon commented Oct 22, 2024 •

edited

Loading

ljharb Oct 22, 2024

blakeembrey Oct 22, 2024

wesleytodd Oct 24, 2024

ljharb Oct 24, 2024

ljharb Oct 22, 2024

blakeembrey left a comment

blakeembrey Oct 22, 2024

blakeembrey Oct 22, 2024

ljharb Oct 22, 2024

wesleytodd left a comment

wesleytodd Oct 24, 2024

wesleytodd Oct 24, 2024

wesleytodd Oct 24, 2024

wesleytodd Oct 24, 2024

wesleytodd Oct 24, 2024

UlisesGascon commented Oct 26, 2024 •

edited

Loading

ljharb commented Oct 27, 2024

bjohansebas commented Oct 27, 2024

ljharb commented Oct 27, 2024

bjohansebas commented Nov 1, 2024

	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.

	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.

	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.

	- 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).


		## Implementation

		- Phase 1: Update `package.json` files across all packages to apply `^` for our own dependencies.

Add policy on using caret (^) or tilde (~) with dependencies #290

Are you sure you want to change the base?

Add policy on using caret (^) or tilde (~) with dependencies #290

Conversation

UlisesGascon commented Oct 22, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

blakeembrey left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wesleytodd left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

UlisesGascon commented Oct 26, 2024 • edited Loading

ljharb commented Oct 27, 2024

bjohansebas commented Oct 27, 2024

ljharb commented Oct 27, 2024

bjohansebas commented Nov 1, 2024

UlisesGascon commented Oct 22, 2024 •

edited

Loading

UlisesGascon commented Oct 26, 2024 •

edited

Loading