Package management

[flaki]

I did some digging around package the management system to use for this repo. The motivation here is reducing friction and making it easier to use the build the docs locally and contribute.

npm is available by default in node.js, installing the website dependencies on my computer takes ~10seconds, and 135 MB worth of dependencies are downloaded into node_modules.

yarn would normally cause extra trouble to install, but the latest versions of Node.js 14 and onwards makes its installation trivial thanks to corepack. This means that on all supported Node.js versions (v12 is unsupported and the LTS expires on April anyway) yarn can be enabled by the corepack enable command, without further platform-specific installation.

With this hurdle out of the way, the question is Yarn (2.0 plus) or Yarn Classic (1.x). Since 1.x is already deprecated I wouldn't add an extra dependency just for this, so I'd argue only modern Yarn should be considered.

Using the latest Yarn stable (3.1.1) the installation time is is around 6 seconds (a nice improvement) and the installed file module cache in the .yarn folder clocks in at 53 MB, this is a ~60% reduction compared to npm.

Yarn wants to have the module cache committed into the repository. While yarn fares much better in this regard than npm, this would come with a few drawbacks:

1. The module changes would eventually inflate/bloat the repository and increase the size of the checkout through old git objects downloaded to all clients despite being superseded since
2. Certain dependencies, like those containing executables and shell scripts cannot be stored in the compressed format and must be unplugged in order to function correctly. While these modules amount for less than 10 MB of all dependencies, they contain several hundred files and would make git operations considerably slower if checked into the repo.

Due to the above issues, I cannot recommend checking in yarn's cache into the GitHub repo without further testing, but perhaps using yarn should not be outright dismissed due to its other significant benefits. That said, I would argue that we should choose a single documented and supported method of building the docs and reflect this in the README, to reduce support overhead and complexity for contributions.

[ospencer]

Overall, I think I would still vote to use npm. There are some benefits to Yarn 2 for sure, but I think it'll still cause some confusion around versioning, even if corepack is used. I feel like questions like "This project is Yarn 2, but I have Yarn 1. Will it work? What is corepack?" will come up. I could maybe see us relying on it if it were on by default, but it's not quite there yet. npm is a really safe choice and will be fairly familiar for people—I don't think we'd go wrong choosing it.

[flaki]

I agree that npm is the safest choice.

WRT Yarn 1 vs 2 I believe how it works is that if they have the latest Yarn 1 it will detect that the project uses a different Yarn (through yarn set version stable a .yarnrc file is generated that latest Yarn Classic will detect and adhere to). So it should "just work", but definitely more fragile than I'd like.

We could keep this issue open and see how yarn/corepack matures and revisit later with some more scientific evaluation of the pros and cons.

[LauraLangdon]

Is this issue duplicated (more or less) now in Issue #43? @flaki

[flaki]

@LauraLangdon yeah the two are closely related. I'll have a look at this again next week and try to come up with a proposal for the weekly meeting.

[flaki]

Docusaurus has existing plugin support for displaying npm/yarn commands automatically as tabs.

[LauraLangdon]

From yesterday's docs meeting notes:

• Laura: The docs should follow the behaviour of respecting the “selected” language, meaning that we should show a “language not available” type of message
• Ramón: Should we show all tabs, even if there’s no content for that language?
• Laura: That makes sense
• Ramón: Why not have a “Contribute this code block” kind of incentive when no code present for that language?
• @flaki Is this possible? Say if the “content” prop is empty, or something?

[hola-soy-milk]

As discussed with @callahad, we'll go with an opinionated ™️ approach and opt for npm:

Those who know yarn will use yarn