From 185c283cf4796f2e4a7d9efc7a5420e5c13a667c Mon Sep 17 00:00:00 2001 From: Audrey Eschright Date: Thu, 20 Dec 2018 16:18:43 -0800 Subject: [PATCH 1/7] Add a package overrides feature. --- accepted/0000-package-overrides.md | 35 ++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 accepted/0000-package-overrides.md diff --git a/accepted/0000-package-overrides.md b/accepted/0000-package-overrides.md new file mode 100644 index 000000000..d47d371fb --- /dev/null +++ b/accepted/0000-package-overrides.md @@ -0,0 +1,35 @@ +# Implement a package override option + +## Summary + +Add a section to package.json that allows the user to designate packages as an 'override' at a particular version. + +## Motivation + +In some situations, allowing more than one version of a package to be installed at the same time can cause unwanted behaviors. This will allow users to fix that by explicitly setting a single version to use. + +## Detailed Explanation + +Users will be able to add an additional dependency section called 'overrides' where they give a list of one or more packages to be installed at a specific version. Having this section will ensure that the only version of that package that is eventually installed to the project is the one set as an override. This will not affect the name, source, path, or other aspects of the package's installation. + +## Rationale and Alternatives + +Users don't frequently need to do this sort of override because npm's nested tree structure allows for a collection of dependencies to require incompatible semvers for the same package. In many cases, the default behavior is acceptable and nothing further is needed. In other, more problematic situations, the user may encounter conflicting binaries or other components that cannot be used simultaneously. The only current options are to attempt to get the maintainers of the dependencies to make changes that will reduce these conflicts, or to use a tool like `https://www.npmjs.com/package/replace-deep-dep` to repair the requirements. + +## Implementation + +{{In order to do this, the npm installer will need to read in an overrides section from `package.json`. This will have a simple format such as `overrides: { 'foo': '1.2.3' }`. These values will need to be used at the end of the tree-building process to select the final version. [Is there also a pruning element to this?]}} + +## Prior Art + + - [Dart](https://www.dartlang.org/tools/pub/dependencies#dependency-overrides) uses a dependency override option that allows defining a specific source or version. + - [Bower](https://github.com/bower/spec/blob/master/json.md#resolutions) has a setting for 'resolutions', which are package versions to fall back to if there's a conflict. + - [Yarn](https://yarnpkg.com/en/docs/package-json#toc-resolutions) has a similar resolutions setting, which allows choosing a version or a file source. It allows a more complex system of selecting which packages the override will be applied to. + +Our goal in this RFC is to provide the simplest possible solution to a less common but impactful problem. The most important part of this feature is to define a safe fallback for package versions that conflict. + +## Unresolved Questions and Bikeshedding + +Are there error situations that could occur? When should the installer exit or warn because the override will not be possible? + +{{THIS SECTION SHOULD BE REMOVED BEFORE RATIFICATION}} From 7af3c00efecf8af17d659bf934d0d7af3a29495c Mon Sep 17 00:00:00 2001 From: Audrey Eschright Date: Thu, 20 Dec 2018 17:28:59 -0800 Subject: [PATCH 2/7] Formatting --- accepted/0000-package-overrides.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/accepted/0000-package-overrides.md b/accepted/0000-package-overrides.md index d47d371fb..3bf215672 100644 --- a/accepted/0000-package-overrides.md +++ b/accepted/0000-package-overrides.md @@ -18,7 +18,7 @@ Users don't frequently need to do this sort of override because npm's nested tre ## Implementation -{{In order to do this, the npm installer will need to read in an overrides section from `package.json`. This will have a simple format such as `overrides: { 'foo': '1.2.3' }`. These values will need to be used at the end of the tree-building process to select the final version. [Is there also a pruning element to this?]}} +In order to do this, the npm installer will need to read in an overrides section from `package.json`. This will have a simple format such as `overrides: { 'foo': '1.2.3' }`. These values will need to be used at the end of the tree-building process to select the final version. (Is there also a pruning element to this?) ## Prior Art From 89f5d36482f2332a1a7468e0a6c5c80ee9026c91 Mon Sep 17 00:00:00 2001 From: Audrey Eschright Date: Thu, 3 Jan 2019 17:34:54 -0800 Subject: [PATCH 3/7] Update 0000-package-overrides.md --- accepted/0000-package-overrides.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/accepted/0000-package-overrides.md b/accepted/0000-package-overrides.md index 3bf215672..2d34358da 100644 --- a/accepted/0000-package-overrides.md +++ b/accepted/0000-package-overrides.md @@ -2,7 +2,7 @@ ## Summary -Add a section to package.json that allows the user to designate packages as an 'override' at a particular version. +Add a section to package.json that allows the user to designate packages as an 'override' or replacement at a particular version. ## Motivation @@ -14,11 +14,13 @@ Users will be able to add an additional dependency section called 'overrides' wh ## Rationale and Alternatives -Users don't frequently need to do this sort of override because npm's nested tree structure allows for a collection of dependencies to require incompatible semvers for the same package. In many cases, the default behavior is acceptable and nothing further is needed. In other, more problematic situations, the user may encounter conflicting binaries or other components that cannot be used simultaneously. The only current options are to attempt to get the maintainers of the dependencies to make changes that will reduce these conflicts, or to use a tool like `https://www.npmjs.com/package/replace-deep-dep` to repair the requirements. +Users don't frequently need to do this sort of override/replacement because npm's nested tree structure allows for a collection of dependencies to require incompatible semvers for the same package. In many cases, the default behavior is acceptable and nothing further is needed. In other, more problematic situations, the user may encounter conflicting binaries or other components that cannot be used simultaneously. The only current options are to attempt to get the maintainers of the dependencies to make changes that will reduce these conflicts, or to use a tool like `https://www.npmjs.com/package/replace-deep-dep` to repair the requirements. ## Implementation -In order to do this, the npm installer will need to read in an overrides section from `package.json`. This will have a simple format such as `overrides: { 'foo': '1.2.3' }`. These values will need to be used at the end of the tree-building process to select the final version. (Is there also a pruning element to this?) +In order to do this, the npm installer will need to read in an replacement section from `package.json`. This will have a simple format such as `replace: { 'foo': '1.2.3' }`. These values will need to be used at the end of the tree-building process to select the final version. It will be applied in a 'flat' way -- the same version will be selected for all sub-dependencies that require that package. + +Users will not be allowed to `npm publish` a package with this kind of dependency (we may choose to revise this behavior later). If someone installs a package that does have a 'replace' section, we'll warn them that this may have unexpected results. ## Prior Art @@ -30,6 +32,8 @@ Our goal in this RFC is to provide the simplest possible solution to a less comm ## Unresolved Questions and Bikeshedding -Are there error situations that could occur? When should the installer exit or warn because the override will not be possible? +- Will a warning be sufficient if someone installs a package that contains an override in its own package.json? +- Do we want a `--force` option to allow publishing a package with this in place? +- Are there other workarounds users are likely to try, or edge cases to consider? {{THIS SECTION SHOULD BE REMOVED BEFORE RATIFICATION}} From a57ab285fbbf042b800bdc0d33095098ba201889 Mon Sep 17 00:00:00 2001 From: Audrey Eschright Date: Fri, 4 Jan 2019 11:05:18 -0800 Subject: [PATCH 4/7] Adding an additional question to resolve --- accepted/0000-package-overrides.md | 1 + 1 file changed, 1 insertion(+) diff --git a/accepted/0000-package-overrides.md b/accepted/0000-package-overrides.md index 2d34358da..d237e4e84 100644 --- a/accepted/0000-package-overrides.md +++ b/accepted/0000-package-overrides.md @@ -35,5 +35,6 @@ Our goal in this RFC is to provide the simplest possible solution to a less comm - Will a warning be sufficient if someone installs a package that contains an override in its own package.json? - Do we want a `--force` option to allow publishing a package with this in place? - Are there other workarounds users are likely to try, or edge cases to consider? +- Should this be applied to devDependencies, optionally or by default? {{THIS SECTION SHOULD BE REMOVED BEFORE RATIFICATION}} From e338a70d75596adecbfb732defce4ed1379decde Mon Sep 17 00:00:00 2001 From: Audrey Eschright Date: Fri, 4 Jan 2019 11:12:16 -0800 Subject: [PATCH 5/7] Switching 'override' for 'replace' --- accepted/0000-package-overrides.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/accepted/0000-package-overrides.md b/accepted/0000-package-overrides.md index d237e4e84..b1be5c9fd 100644 --- a/accepted/0000-package-overrides.md +++ b/accepted/0000-package-overrides.md @@ -10,7 +10,7 @@ In some situations, allowing more than one version of a package to be installed ## Detailed Explanation -Users will be able to add an additional dependency section called 'overrides' where they give a list of one or more packages to be installed at a specific version. Having this section will ensure that the only version of that package that is eventually installed to the project is the one set as an override. This will not affect the name, source, path, or other aspects of the package's installation. +Users will be able to add an additional dependency section called 'replace' where they give a list of one or more packages to be installed at a specific version. Having this section will ensure that the only version of that package that is eventually installed to the project is the one set as an replacement. This will not affect the name, source, path, or other aspects of the package's installation. ## Rationale and Alternatives From d312a45f6b8fe2ca4d7fb7240fd82629cda2a770 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kat=20March=C3=A1n?= Date: Thu, 10 Jan 2019 13:47:29 -0800 Subject: [PATCH 6/7] Update 0000-package-overrides.md --- accepted/0000-package-overrides.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/accepted/0000-package-overrides.md b/accepted/0000-package-overrides.md index b1be5c9fd..08c48c18d 100644 --- a/accepted/0000-package-overrides.md +++ b/accepted/0000-package-overrides.md @@ -30,11 +30,13 @@ Users will not be allowed to `npm publish` a package with this kind of dependenc Our goal in this RFC is to provide the simplest possible solution to a less common but impactful problem. The most important part of this feature is to define a safe fallback for package versions that conflict. -## Unresolved Questions and Bikeshedding +## Questions and Bikeshedding - Will a warning be sufficient if someone installs a package that contains an override in its own package.json? + - Yes, that's fine. Or no warning is fine (just a verbose log or somesuch) - Do we want a `--force` option to allow publishing a package with this in place? + - Yes. - Are there other workarounds users are likely to try, or edge cases to consider? + - Not aside from replace-deep-dep. It's fairly tricky to do without it. - Should this be applied to devDependencies, optionally or by default? - -{{THIS SECTION SHOULD BE REMOVED BEFORE RATIFICATION}} + - Yes. By default. From ca127d7c5fb7ecde534172d771351c0b8f819e79 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kat=20March=C3=A1n?= Date: Thu, 10 Jan 2019 13:47:43 -0800 Subject: [PATCH 7/7] Rename 0000-package-overrides.md to 0009-package-overrides.md --- accepted/{0000-package-overrides.md => 0009-package-overrides.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename accepted/{0000-package-overrides.md => 0009-package-overrides.md} (100%) diff --git a/accepted/0000-package-overrides.md b/accepted/0009-package-overrides.md similarity index 100% rename from accepted/0000-package-overrides.md rename to accepted/0009-package-overrides.md