From 25d9f5fa6ecefff2e5929d85b5b31300320a2a37 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulrich-Matthias=20Sch=C3=A4fer?= Date: Thu, 19 Dec 2024 13:44:05 +0100 Subject: [PATCH 1/5] chore: update readme with actionable advice --- README.md | 93 ++++++++++++++++++++++++++----------------------------- 1 file changed, 44 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index 0e3f428..77f5f81 100644 --- a/README.md +++ b/README.md @@ -7,70 +7,65 @@ debt in the JS ecosystem. Our goal is to provide a cleaner, faster and simpler dependency tree in the JS ecosystem for those who are concerned with it. -## The problem +## How to help -Packages often have dependencies, and those dependencies themselves have -dependencies, and so on. This is fine and expected with how dependency trees -are structured. +All issues on our issue tracker are labeled and a lot of them contain actionable items you can start to work on right away. +Hence, an explanation of the labels is in order: -However, over the years many of these deepest dependencies are long since -obsolete utilities, polyfills, and so on. At the time they were introduced, -they were important and had their use, but are now arguably redundant to -most of us. +umbrella issue -For example, polyfills for `Array.prototype.includes` are often found -deep in most projects' dependency trees, and yet this feature has been available -since Node 6 (released in ~2016). +A list of repos that contain at least one dependency that can be replaced by a better alternative. Before you submit a PR, create an issue first if no contact has been made yet -Similarly, we have all collected "micro packages" over time without realising -it. These are very small (often one-liners) packages we depend on to do -simple pieces of logic the JavaScript language already allows us to do. For -example, `is-string`, `is-number`, `is-nan`, etc. +needs first contact -There are many reasons you could argue these are a bad idea. Security, -complexity, install time, bundle size and so on. We unnecessarily download, -install and include hundreds of these packages when the platform already -provides the same functionality. +The maintainer of the repo was not contacted yet. Create an issue and ask, if creating a PR is welcome -## They have their uses +has issue -Some of these packages do have their use, and a small group of consumers -strongly disagree with removing them (usually the creators of said packages). +There is an open issue for the repo but no PR yet. If the maintainer gave a positive response, you can go ahead and create a PR -For example, one primary argument for using the polyfill-like packages is -that a third-party package can override built-ins and break another package's -code. To counter this, these packages use a custom implementation/wrapper around -the native functionality instead of using the native functionality directly -(since nobody can override the wrapper). +has confirmation -If you need this kind of protection against the way JavaScript works, then of -course this cleanup is not for you. +The maintainer is welcoming PRs. Feel free to create PRs for all the issues you find -## The effort +has pr -This is not an easy problem to tackle since these packages are so deeply -embedded in our system, far below the packages we knowingly install day by day. +A PR has been created and waits to be merged. Nothing to do here for now. -To make things easier, we will be splitting up the work into much smaller -and more manageable tasks to gradually chip away instead of a big bang solution. +pr needs update -Some examples of what we will be doing: +The PR needs to be updated. Either there was a reponse / review by the maintainer or the PR has merge conflicts -- Remove these packages from popular packages as direct dependencies -- Fork packages which have officially stated they will never move off these -packages - - Where possible, make these forks track the original source repo (i.e. -catch up from main when the origin changes). -- Replace redundant polyfills with native functionality in popular packages -- Replace these packages with cleaner alternatives +blocked -The main goal is to _contribute_ to the packages we actually use (which depend -on these things), and as a final resort, fork what is immovable. +This PR is blocked by some other issue. Check regularly if that issue is resolved -## Contributing +rejected -If you'd like to contribute towards the effort, simply find an issue you would -like to help with and just let us know with a reply that you are going to tackle -it. We will be happy to help you along the way. +The PR or the idea of a PR has been rejected by the maintainer. Maybe try again after a few months -A good place to start is the [guide](./docs/guide.md). +needs alternative + +The package in question needs a replacement that we can bring forward. Feel free to create one. Maitenance burden is on you! + +## Where do I start + +- If you like to reach out, look for issues with the needs first contact label and create an issue (or use some other communication channel). Paste the issue you created as answer to tagged issue here +- If you want to create PRs, look for the has confirmation label. Paste the PR link in the tagged issue. +- If you want to own the whole chain, go through: + + needs first contact -> has issue -> has confirmation -> has pr -> merged + +- if you create an issue or pr for an umbrella issue issue, update the umbrella issue as well + +## Issue template + +``` +// needs work +``` + +## PR template + +``` +// needs work +``` From 4b8c453571fe537e274a97b080e6388bbecda3d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulrich-Matthias=20Sch=C3=A4fer?= Date: Thu, 19 Dec 2024 17:41:54 +0100 Subject: [PATCH 2/5] update label name --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 77f5f81..eb97459 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ The maintainer of the repo was not contacted yet. Create an issue and ask, if cr There is an open issue for the repo but no PR yet. If the maintainer gave a positive response, you can go ahead and create a PR -has confirmation +accepts prs The maintainer is welcoming PRs. Feel free to create PRs for all the issues you find @@ -51,10 +51,10 @@ The package in question needs a replacement that we can bring forward. Feel free ## Where do I start - If you like to reach out, look for issues with the needs first contact label and create an issue (or use some other communication channel). Paste the issue you created as answer to tagged issue here -- If you want to create PRs, look for the has confirmation label. Paste the PR link in the tagged issue. +- If you want to create PRs, look for the accepts prs label. Paste the PR link in the tagged issue. - If you want to own the whole chain, go through: - needs first contact -> has issue -> has confirmation -> has pr -> merged + needs first contact -> has issue -> accepts prs -> has pr -> merged - if you create an issue or pr for an umbrella issue issue, update the umbrella issue as well From 738df937d1d5842d8aeba0b25c39f83c04a1de14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulrich-Matthias=20Sch=C3=A4fer?= Date: Fri, 20 Dec 2024 14:39:30 +0100 Subject: [PATCH 3/5] Update README.md Co-authored-by: Ben McCann <322311+benmccann@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index eb97459..ce125b5 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,7 @@ The package in question needs a replacement that we can bring forward. Feel free ## Where do I start -- If you like to reach out, look for issues with the needs first contact label and create an issue (or use some other communication channel). Paste the issue you created as answer to tagged issue here +- If you'd like to reach out, look for issues with the needs first contact label and create an issue (or use some other communication channel). Paste the issue you created as answer to tagged issue here - If you want to create PRs, look for the accepts prs label. Paste the PR link in the tagged issue. - If you want to own the whole chain, go through: From b934b4186d2df9e7bc4253de7513d49a1c6eeb34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulrich-Matthias=20Sch=C3=A4fer?= Date: Fri, 20 Dec 2024 14:45:06 +0100 Subject: [PATCH 4/5] feedback --- README.md | 43 +++++++++---------------------------------- 1 file changed, 9 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index ce125b5..422f0c9 100644 --- a/README.md +++ b/README.md @@ -10,40 +10,16 @@ ecosystem for those who are concerned with it. ## How to help All issues on our issue tracker are labeled and a lot of them contain actionable items you can start to work on right away. -Hence, an explanation of the labels is in order: - -umbrella issue - -A list of repos that contain at least one dependency that can be replaced by a better alternative. Before you submit a PR, create an issue first if no contact has been made yet +Here are some examples: needs first contact The maintainer of the repo was not contacted yet. Create an issue and ask, if creating a PR is welcome -has issue - -There is an open issue for the repo but no PR yet. If the maintainer gave a positive response, you can go ahead and create a PR - accepts prs The maintainer is welcoming PRs. Feel free to create PRs for all the issues you find -has pr - -A PR has been created and waits to be merged. Nothing to do here for now. - -pr needs update - -The PR needs to be updated. Either there was a reponse / review by the maintainer or the PR has merge conflicts - -blocked - -This PR is blocked by some other issue. Check regularly if that issue is resolved - -rejected - -The PR or the idea of a PR has been rejected by the maintainer. Maybe try again after a few months - needs alternative The package in question needs a replacement that we can bring forward. Feel free to create one. Maitenance burden is on you! @@ -52,20 +28,19 @@ The package in question needs a replacement that we can bring forward. Feel free - If you'd like to reach out, look for issues with the needs first contact label and create an issue (or use some other communication channel). Paste the issue you created as answer to tagged issue here - If you want to create PRs, look for the accepts prs label. Paste the PR link in the tagged issue. -- If you want to own the whole chain, go through: - - needs first contact -> has issue -> accepts prs -> has pr -> merged - - if you create an issue or pr for an umbrella issue issue, update the umbrella issue as well +- This is no must, but we usually try to follow the following process: + + needs first contact -> has issue -> accepts prs -> has pr -> merged! ## Issue template ``` -// needs work -``` +I would like to propose to replace/update x with the smaller and faster y. +As part of the e18e initiative (ecosystem cleanup), we try to reduce the burden of old or big libs and modernize the ecosystem. -## PR template +y currently pulls in {number} dependencies while x only uses {number} dependencies. +Using y instead of x would reduce the package size by {number} bytes and traffic generated by the package by {number} bytes. -``` -// needs work +If you welcome this change, i would be happy to provide a PR! ``` From caa8facf4cae89b761b1799da136be790a3cb6c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulrich-Matthias=20Sch=C3=A4fer?= Date: Fri, 20 Dec 2024 16:06:38 +0100 Subject: [PATCH 5/5] add example issues --- README.md | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 422f0c9..0918542 100644 --- a/README.md +++ b/README.md @@ -33,14 +33,7 @@ The package in question needs a replacement that we can bring forward. Feel free needs first contact -> has issue -> accepts prs -> has pr -> merged! -## Issue template +## Example issues -``` -I would like to propose to replace/update x with the smaller and faster y. -As part of the e18e initiative (ecosystem cleanup), we try to reduce the burden of old or big libs and modernize the ecosystem. - -y currently pulls in {number} dependencies while x only uses {number} dependencies. -Using y instead of x would reduce the package size by {number} bytes and traffic generated by the package by {number} bytes. - -If you welcome this change, i would be happy to provide a PR! -``` +- dom-testing-library: https://github.com/testing-library/dom-testing-library/issues/1340 +- webpack-dev-server: https://github.com/webpack/webpack-dev-server/issues/5368