From 65efee3ffa89cebfb49fd42e11973568917a7a9b Mon Sep 17 00:00:00 2001 From: Vitali Zaidman Date: Tue, 23 Oct 2018 20:33:04 +0300 Subject: [PATCH 1/7] Document package's info using yarn.comments Initial yarn-comments suggestion --- accepted/0000-yarn-comments.md | 106 +++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 accepted/0000-yarn-comments.md diff --git a/accepted/0000-yarn-comments.md b/accepted/0000-yarn-comments.md new file mode 100644 index 0000000..d1e75b9 --- /dev/null +++ b/accepted/0000-yarn-comments.md @@ -0,0 +1,106 @@ +- Start Date: 2018-10-21 +- RFC PR: +- Yarn Issue: + +# Summary + +I want developers to have a tool to comment about packages and their corresponding version ranges. + +# Motivation + +My team and I found ourselves with the need to document why some packages got +pinned down older versions. + +Here are the scenarios we encountered: + +1. We took a decision to stay with React 15 and not to update it to React 16 and +tis lead to many packages staying on older versions as well. There's currently +no convenient way to signal the next developer who would like to +upgrade the versions of all the packages in the project, that they should keep +some on older versions and why they should. + +2. Sometimes a bug is found even in minor version updates of packages and there is +no convenient way to signal developers why a package is pinned to a certain version. +I'd like a way to point to a bug and to ask the developer to unpin the package only +if it gets fixed. + +3. In some cases, we cloned a repository and fixed or modified npm libraries. In +the meantime, before our pull request was merged to the root repository and uploaded +to npm, we used our forked git repository as the version of the package. There's +currently, no convenient way to document when should the git repository URL be replaced +with the newest version of a package like this (probably when the PR is merged). + +4. Some packages appear in package.json to be installed in node_modules for the sake +of being used by other libraries and they are not used in the source code of the +project itself. It's very tempting to delete such packages because there's currently +no convenient way to signal the developers it's there for a reason and what's the reason. + +5. Some packages can be upgraded but the new versions have breaking changes which are not easy to +cope with. In that case, it would be useful to signal a developer there's a ticket to upgrade +that specific package and what work has been done on it. + +6. There's no convenient way to know what new package's versions didn't receive any +attention from the team yet. + +# Detailed design + +My idea is to save all this information in a separate file `yarn.comments` that +would be committed next to `package.json` and `yarn.lock`. This file would contain a +list of packages with comments on them and optionally with the pinned version the +author suggests. + +This file would be easy to read and maintain both manually and automatically. + +Upon running commands like `yarn upgrade` or `yarn upgrade-interactive`, comments +would appear to the user as info and warnings and confirmations about pinned versions +would run if something doesn't match. This can be suppressed with --skip-comments for +running in a CI for example. If `yarn.comments` is in use we can safely assume the +team cares about the pinned versions inside of it and can deal with adding this argument. + +Upon running commands like `yarn remove` the package's comment would appear and if the +the user still wants to delete it, it would also be deleted from `yarn.comments`. + +This file should be created by the user manually or as the result of choosing to do so +in one of the steps of `yarn upgrade-interactive` (Where the default is not to use it). + +Comments could be added to the file as part of the *user choosing older version* for a +package in `yarn upgrade-interactive` or directly to the file, manually. + +If the file doesn't exist, nothing would change for the user despite this one step in +`yarn upgrade-interactive`, which is *no* by default, with a link to the documentation +of the feature. + +# How We Teach This + +I believe adding it to the end of the documentation and adding a step in +`yarn upgrade-interactive` that would suggest the user use it with a link to the +documentation is enough. + +# Drawbacks + +Yarn having more files then it has now can make it seem verbose and too much "heavy", +even though using this feature is completely optional. + +Having versions appear in two places can be problematic both for users and for certain +commands. + +# Alternatives + +I thought to use a simple "packages.md" file or adding it to the readme, but then it +gets lost and it's too easy to miss. + +Another option was to somehow add it to package.json. I tried adding comments on +package.json but it's not possible. Also, I tried to add dummy packages next to packages +I wanted to comment on, but it gets messy and package managers rearrange it. + +Another option would be to use "GIT" to keep track of commits where package.json got +modified, but this can also be missed and not easy to maintain. + +# Unresolved questions + +I considered to suggest to use `yarn.lock` for this at first but I want the user to +be able to maintain it manually and to keep it noticeable. + +Another option would be to use .yarnrc for this purpose but its purpose is different +and it's very counter-intuitive and also this file might be created automatically in +some systems. From 4feaf31e5c4f67e15f4c159b3a96a964c67d5da3 Mon Sep 17 00:00:00 2001 From: Vitali Zaidman Date: Tue, 23 Oct 2018 21:07:06 +0300 Subject: [PATCH 2/7] Update 0000-yarn-comments.md added a line about `yarn install` --- accepted/0000-yarn-comments.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/accepted/0000-yarn-comments.md b/accepted/0000-yarn-comments.md index d1e75b9..b7c42ed 100644 --- a/accepted/0000-yarn-comments.md +++ b/accepted/0000-yarn-comments.md @@ -60,6 +60,9 @@ team cares about the pinned versions inside of it and can deal with adding this Upon running commands like `yarn remove` the package's comment would appear and if the the user still wants to delete it, it would also be deleted from `yarn.comments`. +Warnings should aslo run if there is a version mismatch between `package.json` and +`yarn.comments`. + This file should be created by the user manually or as the result of choosing to do so in one of the steps of `yarn upgrade-interactive` (Where the default is not to use it). From 4cfe6bf3c9ddc2ca65b2c565cb6b69a6e053b2f9 Mon Sep 17 00:00:00 2001 From: Vitali Zaidman Date: Wed, 24 Oct 2018 12:21:08 +0300 Subject: [PATCH 3/7] Update 0000-yarn-comments.md added an unresolved question regarding JSON5 --- accepted/0000-yarn-comments.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/accepted/0000-yarn-comments.md b/accepted/0000-yarn-comments.md index b7c42ed..09c84ea 100644 --- a/accepted/0000-yarn-comments.md +++ b/accepted/0000-yarn-comments.md @@ -101,6 +101,9 @@ modified, but this can also be missed and not easy to maintain. # Unresolved questions +Can we instead provide support to JSON5 which supports comments. I don't really understand the effects +of this change. + I considered to suggest to use `yarn.lock` for this at first but I want the user to be able to maintain it manually and to keep it noticeable. From 43507b7088edc726aaef87cfe172a6b81719e60e Mon Sep 17 00:00:00 2001 From: Vitali Zaidman Date: Wed, 24 Oct 2018 12:32:32 +0300 Subject: [PATCH 4/7] improved info regarding the "JSON5" alternative --- accepted/0000-yarn-comments.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/accepted/0000-yarn-comments.md b/accepted/0000-yarn-comments.md index 09c84ea..c9d859a 100644 --- a/accepted/0000-yarn-comments.md +++ b/accepted/0000-yarn-comments.md @@ -99,10 +99,13 @@ I wanted to comment on, but it gets messy and package managers rearrange it. Another option would be to use "GIT" to keep track of commits where package.json got modified, but this can also be missed and not easy to maintain. -# Unresolved questions +We could also provide support for JSON5 which supports comments. But, first of all, +many libraries and tools assume the'res `package.json` and that it is in a simple +JSON format. Making them adopt to the new one is defenetly a long shot. Also- +simply comments are weaker then this suggestion in terms of best practices like +single point of truth. -Can we instead provide support to JSON5 which supports comments. I don't really understand the effects -of this change. +# Unresolved questions I considered to suggest to use `yarn.lock` for this at first but I want the user to be able to maintain it manually and to keep it noticeable. From bb2b41dd6c94e584e3a4bc2d3177a95403998141 Mon Sep 17 00:00:00 2001 From: Vitali Zaidman Date: Wed, 24 Oct 2018 13:13:21 +0300 Subject: [PATCH 5/7] added alternatives --- accepted/0000-yarn-comments.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/accepted/0000-yarn-comments.md b/accepted/0000-yarn-comments.md index c9d859a..e9667d1 100644 --- a/accepted/0000-yarn-comments.md +++ b/accepted/0000-yarn-comments.md @@ -105,6 +105,14 @@ JSON format. Making them adopt to the new one is defenetly a long shot. Also- simply comments are weaker then this suggestion in terms of best practices like single point of truth. +Adding a block to package.json- We might support this as well or instead of using +`yarn.comments`. + +We can use a library to check version missmatches vs some file or vs a block in +`package.json` upon running different `yarn` (or even npm) scripts. This looks like +the fastest solution but it doesn't feel native. I want users to see the comments when +they run `yarn upgrade-interactive` near the packages in question for example. + # Unresolved questions I considered to suggest to use `yarn.lock` for this at first but I want the user to From cd99fa6dc54c8b5e1493395be75e2d3a2363f991 Mon Sep 17 00:00:00 2001 From: Vitali Zaidman Date: Sun, 14 Jul 2019 14:37:15 +0300 Subject: [PATCH 6/7] Update and rename 0000-yarn-comments.md to 0000-yarn-documentation.md --- accepted/0000-yarn-comments.md | 123 ---------------------------- accepted/0000-yarn-documentation.md | 108 ++++++++++++++++++++++++ 2 files changed, 108 insertions(+), 123 deletions(-) delete mode 100644 accepted/0000-yarn-comments.md create mode 100644 accepted/0000-yarn-documentation.md diff --git a/accepted/0000-yarn-comments.md b/accepted/0000-yarn-comments.md deleted file mode 100644 index e9667d1..0000000 --- a/accepted/0000-yarn-comments.md +++ /dev/null @@ -1,123 +0,0 @@ -- Start Date: 2018-10-21 -- RFC PR: -- Yarn Issue: - -# Summary - -I want developers to have a tool to comment about packages and their corresponding version ranges. - -# Motivation - -My team and I found ourselves with the need to document why some packages got -pinned down older versions. - -Here are the scenarios we encountered: - -1. We took a decision to stay with React 15 and not to update it to React 16 and -tis lead to many packages staying on older versions as well. There's currently -no convenient way to signal the next developer who would like to -upgrade the versions of all the packages in the project, that they should keep -some on older versions and why they should. - -2. Sometimes a bug is found even in minor version updates of packages and there is -no convenient way to signal developers why a package is pinned to a certain version. -I'd like a way to point to a bug and to ask the developer to unpin the package only -if it gets fixed. - -3. In some cases, we cloned a repository and fixed or modified npm libraries. In -the meantime, before our pull request was merged to the root repository and uploaded -to npm, we used our forked git repository as the version of the package. There's -currently, no convenient way to document when should the git repository URL be replaced -with the newest version of a package like this (probably when the PR is merged). - -4. Some packages appear in package.json to be installed in node_modules for the sake -of being used by other libraries and they are not used in the source code of the -project itself. It's very tempting to delete such packages because there's currently -no convenient way to signal the developers it's there for a reason and what's the reason. - -5. Some packages can be upgraded but the new versions have breaking changes which are not easy to -cope with. In that case, it would be useful to signal a developer there's a ticket to upgrade -that specific package and what work has been done on it. - -6. There's no convenient way to know what new package's versions didn't receive any -attention from the team yet. - -# Detailed design - -My idea is to save all this information in a separate file `yarn.comments` that -would be committed next to `package.json` and `yarn.lock`. This file would contain a -list of packages with comments on them and optionally with the pinned version the -author suggests. - -This file would be easy to read and maintain both manually and automatically. - -Upon running commands like `yarn upgrade` or `yarn upgrade-interactive`, comments -would appear to the user as info and warnings and confirmations about pinned versions -would run if something doesn't match. This can be suppressed with --skip-comments for -running in a CI for example. If `yarn.comments` is in use we can safely assume the -team cares about the pinned versions inside of it and can deal with adding this argument. - -Upon running commands like `yarn remove` the package's comment would appear and if the -the user still wants to delete it, it would also be deleted from `yarn.comments`. - -Warnings should aslo run if there is a version mismatch between `package.json` and -`yarn.comments`. - -This file should be created by the user manually or as the result of choosing to do so -in one of the steps of `yarn upgrade-interactive` (Where the default is not to use it). - -Comments could be added to the file as part of the *user choosing older version* for a -package in `yarn upgrade-interactive` or directly to the file, manually. - -If the file doesn't exist, nothing would change for the user despite this one step in -`yarn upgrade-interactive`, which is *no* by default, with a link to the documentation -of the feature. - -# How We Teach This - -I believe adding it to the end of the documentation and adding a step in -`yarn upgrade-interactive` that would suggest the user use it with a link to the -documentation is enough. - -# Drawbacks - -Yarn having more files then it has now can make it seem verbose and too much "heavy", -even though using this feature is completely optional. - -Having versions appear in two places can be problematic both for users and for certain -commands. - -# Alternatives - -I thought to use a simple "packages.md" file or adding it to the readme, but then it -gets lost and it's too easy to miss. - -Another option was to somehow add it to package.json. I tried adding comments on -package.json but it's not possible. Also, I tried to add dummy packages next to packages -I wanted to comment on, but it gets messy and package managers rearrange it. - -Another option would be to use "GIT" to keep track of commits where package.json got -modified, but this can also be missed and not easy to maintain. - -We could also provide support for JSON5 which supports comments. But, first of all, -many libraries and tools assume the'res `package.json` and that it is in a simple -JSON format. Making them adopt to the new one is defenetly a long shot. Also- -simply comments are weaker then this suggestion in terms of best practices like -single point of truth. - -Adding a block to package.json- We might support this as well or instead of using -`yarn.comments`. - -We can use a library to check version missmatches vs some file or vs a block in -`package.json` upon running different `yarn` (or even npm) scripts. This looks like -the fastest solution but it doesn't feel native. I want users to see the comments when -they run `yarn upgrade-interactive` near the packages in question for example. - -# Unresolved questions - -I considered to suggest to use `yarn.lock` for this at first but I want the user to -be able to maintain it manually and to keep it noticeable. - -Another option would be to use .yarnrc for this purpose but its purpose is different -and it's very counter-intuitive and also this file might be created automatically in -some systems. diff --git a/accepted/0000-yarn-documentation.md b/accepted/0000-yarn-documentation.md new file mode 100644 index 0000000..c59fd9e --- /dev/null +++ b/accepted/0000-yarn-documentation.md @@ -0,0 +1,108 @@ +- Start Date: 2018-10-21 +- RFC PR: +- Yarn Issue: + +# Summary + +I want to add the option to add ddocumentation for packages and their chosen version ranges. + +# Motivation + +My team and I found ourselves with the need to document why some packages got +pinned down to specific versions. + +## Examples where a feature like this is missing + +1. We took a decision to stay with React 15 and not to migrate to React 16 and +this lead to many packages staying on older versions as well. + +There's currently no convenient way to signal the next developer who would like to +upgrade the versions of packages in the project, that they should keep +some on older versions and why they should do it. + +2. Sometimes a bug is found even in minor version updates of packages and there is +no convenient way to signal developers why a package was pinned to a certain minor version. + +for example: +``` +"some-package": "1.0.4" +``` +Where `1.0.6` is available. + +A developer that sees this kind of version pin usually starts investigating the +git history and people who are involved in the pinning of the package. + +3. We had a few cases, where we cloned a repository and fixed or modified an npm library. + +For the time between our new code is ready and the time it's merged(sometimes it takes weeks or months) +We used our forked git repository as the version of the package: +``` +"some-package": "github:user/repo" +``` +There's currently no convenient way to document when should the git repository URL be replaced +with the newest version of a package like this (probably when the corresponding PR is merged). + +4. Some packages appear in package.json to be installed in node_modules for the sake +of being used by other libraries and they are not used in the source code of the +project itself. + +It's very tempting to delete such packages because they are "not used anywhere" but a +convenient way to document this could be very benefitial to the user. + +5. Some packages has breaking changes in their new versions that are not easy to +cope with. In that case, it would be useful to signal a developer there's a ticket to upgrade +that specific package and what work has been done on it. + +# Detailed design + +My idea is to save the documentation of packages in an additional optional per package `package.json` entry +with the following data structure: +``` +"dependencies-documentation": { + "some-package": "this package is used by some-package-b", + "some-package-b@1.1.3": "pinned because of the following bug: http://www.github.com/package/issues/20" +} +``` +Upon running commands like `yarn upgrade` or `yarn upgrade-interactive`, comments +would appear to the user as info and warnings and confirmations about pinned versions +would run. + +Upon running commands like `yarn remove` the package's comment would appear and if the +the user still wants to delete it, it would also be deleted from `dependencies-documentation`. + +If a package gets deleted manually and `yarn` is run where it is still in `dependencies-documentation` +the comment should be shown to the user with a prompt to delete it or add it back. + +Warnings should aslo run if there is a version mismatch between the package's version in `package.json` +and `dependencies-documentation`. + +All these features would only run if `dependencies-documentation` is added manually by the user. + +If the user doesnt add this field manually, nothing should change in how `yarn` works. + +# How We Teach This + +I believe adding it to the documentation and adding a message to +`yarn upgrade` and `yarn upgrade-interactive` that would suggest the user use it with a link to the +documentation is enough. + +# Drawbacks + +Having versions appear in two places can be problematic both for users and for certain +commands. + +# Alternatives + +* I thought to use a simple "packages.md" file or adding it to the readme, but then it +gets lost and it's too easy to miss. + +* Adding comments to package.json could work but it's not possible because too many tools +expect this file to be a simple JSON and not not a JSON5 file. + +* Another option would be to use repository commits messages to keep track of commits where package.json got +modified, but this can also be missed and not easy to maintain. + +* Simply adding this field to `package.json` without any enforcing from `yarn` might be enough +but + +* We can use an extra library to do this work. But it feels importent enough to be added to `yarn` as a native feature. From 8cfbcd351781b5263e897d0e0adafea687f720e0 Mon Sep 17 00:00:00 2001 From: Vitali Zaidman Date: Sun, 14 Jul 2019 14:37:38 +0300 Subject: [PATCH 7/7] Update 0000-yarn-documentation.md --- accepted/0000-yarn-documentation.md | 1 + 1 file changed, 1 insertion(+) diff --git a/accepted/0000-yarn-documentation.md b/accepted/0000-yarn-documentation.md index c59fd9e..0c5ccf4 100644 --- a/accepted/0000-yarn-documentation.md +++ b/accepted/0000-yarn-documentation.md @@ -1,4 +1,5 @@ - Start Date: 2018-10-21 +- Updated: 2019-07-14 - RFC PR: - Yarn Issue: