Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: update readme with actionable advice #143

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

chore: update readme with actionable advice #143

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
25d9f5f
chore: update readme with actionable advice
Fuzzyma Dec 19, 2024
4b8c453
update label name
Fuzzyma Dec 19, 2024
738df93
Update README.md
Fuzzyma Dec 20, 2024
b934b41
feedback
Fuzzyma Dec 20, 2024
caa8fac
add example issues
Fuzzyma Dec 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 18 additions & 55 deletions README.md
View file
Open in desktop
Copy link

@JoshuaKGoldberg JoshuaKGoldberg Dec 23, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey I really like that you're documenting processes like this! (thanks @43081j for pointing me to this PR) ❤️

A point of feedback as a maintainer who's received quite a few PRs from e18e/ecosystem-cleanup initiatives: please tell participants to always follow repository contributing guidelines. I've seen quite a few PRs that don't address accepted issues, have failing CI, don't use the right conventional commit PR titles, etc.

There are two reasons why I think this is important:

  • This initiative is more than just rote dependency swap-outs. It's also about convincing the ecosystem at large that this is important enough to spend time on. If people affiliated with an initiative consistently trample over the repos they're trying to "help" then it looks like it's just mindless enthusiasm - not something thought deeply on by people who understand open source and maintenance. That devalues the initiative and biases us maintainers against it.
  • Those processes are there for a reason! Oftentimes there are multiple possible replacements for a package. Projects often need time to discuss and figure out their preferred replacement strategy. Sending a PR early can be wasted work.

To be clear, I'm in favor of cleaning up the ecosystem. It's valuable work and I'm happy to see so much progress on it. I hope this comes across as constructive feedback and trying to help, not external criticism. 🙂

Original file line number Diff line number Diff line change
Expand Up @@ -7,70 +7,33 @@ 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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section kind of duplicates the next one. The only one here that isn't below is "needs alternative". I wonder if we can remove this section and potentially add that one below


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.
Here are some examples:

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.
<img src="https://img.shields.io/badge/needs%20first%20contact-b60205?style=flat" alt="needs first contact" style="vertical-align: middle"/>

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).
The maintainer of the repo was not contacted yet. Create an issue and ask, if creating a PR is welcome

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.
<img src="https://img.shields.io/badge/accepts%20prs-DBE1EF?style=flat" alt="accepts prs" style="vertical-align: middle"/>

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 is welcoming PRs. Feel free to create PRs for all the issues you find

## They have their uses
<img src="https://img.shields.io/badge/needs%20alternative-F32096?style=flat" alt="needs alternative" style="vertical-align: middle"/>

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).
The package in question needs a replacement that we can bring forward. Feel free to create one. Maitenance burden is on you!

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).
## Where do I start

If you need this kind of protection against the way JavaScript works, then of
course this cleanup is not for you.
- If you'd like to reach out, look for issues with the <a href="https://github.com/es-tooling/ecosystem-cleanup/issues?q=is%3Aissue+is%3Aopen+label%3A%22needs+first+contact%22"><img src="https://img.shields.io/badge/needs%20first%20contact-b60205?style=flat" alt="needs first contact" style="vertical-align: middle"/></a> 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 <a href="https://github.com/es-tooling/ecosystem-cleanup/issues?q=is%3Aissue+is%3Aopen+label%3A%22accepts+prs%22"><img src="https://img.shields.io/badge/accepts%20prs-DBE1EF?style=flat" alt="accepts prs" style="vertical-align: middle"/></a> label. Paste the PR link in the tagged issue.
- if you create an issue or pr for an <a href="https://github.com/es-tooling/ecosystem-cleanup/issues?q=is%3Aissue+is%3Aopen+label%3A%22umbrella+issue%22"><img src="https://img.shields.io/badge/umbrella%20issue-30EF5D?style=flat" alt="umbrella issue" style="vertical-align: middle"/></a> issue, update the umbrella issue as well
- This is no must, but we usually try to follow the following process:

## The effort
<a href="https://github.com/es-tooling/ecosystem-cleanup/issues?q=is%3Aissue+is%3Aopen+label%3A%22needs+first+contact%22"><img src="https://img.shields.io/badge/needs%20first%20contact-b60205?style=flat" alt="needs first contact" style="vertical-align: middle"/></a> -> <a href="https://github.com/es-tooling/ecosystem-cleanup/issues?q=is%3Aissue+is%3Aopen+label%3A%22has+issue%22"><img src="https://img.shields.io/badge/has%20issue-697830?style=flat" alt="has issue" style="vertical-align: middle"/></a> -> <a href="https://github.com/es-tooling/ecosystem-cleanup/issues?q=is%3Aissue+is%3Aopen+label%3A%22accepts+prs%22"><img src="https://img.shields.io/badge/accepts%20prs-DBE1EF?style=flat" alt="accepts prs" style="vertical-align: middle"/></a> -> <a href="https://github.com/es-tooling/ecosystem-cleanup/issues?q=is%3Aissue+is%3Aopen+label%3A%22has+pr%22"><img src="https://img.shields.io/badge/has%20pr-6E4234?style=flat" alt="has pr" style="vertical-align: middle"/></a> -> merged!

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.
## Example issues

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.

Some examples of what we will be doing:

- 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

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.

## Contributing

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.

A good place to start is the [guide](./docs/guide.md).
- 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