NOTE: This is a **DRAFT** RfC in the preparation phase. Please discuss the **contents** of this RFC on the [[ https://www.mediawiki.org/wiki/User_talk:Aron_Manning/RfC:_Evaluate_alternative_Node_package_managers_for_improved_package_security | talk page ]] and **respond** to the RFC here, preferably after it's finalized.
See [[ https://www.mediawiki.org/wiki/User:Aron_Manning/RfC:_Evaluate_alternative_Node_package_managers_for_improved_package_security#Motivation | "Motivation" ]], [[ https://www.mediawiki.org/wiki/User:Aron_Manning/RfC:_Evaluate_alternative_Node_package_managers_for_improved_package_security#Status_quo | "Status quo" ]], [[ https://www.mediawiki.org/wiki/User:Aron_Manning/RfC:_Evaluate_alternative_Node_package_managers_for_improved_package_security#A_few_examples_of_NPM_incidents | "A few examples of NPM incidents" ]] sections in the detailed RFC on wiki.
Descoped from {T199004}
This RFC is about evaluating alternative package managers in regards of:
* security benefits
* impact on development and deployment workflows
* migration workload
The purpose is to test these PMs without changing or disrupting established workflows. One or both PMs can be introduced for testing by developers as an optional alternative in the codebase, without impacting production.
This testing phase might take months, involving compatibility updates to wikimedia projects and upstream packages.
If such test is successful, it can be considered to migrate production workflows from NPM to a chosen alternative.
The package managers in scope (details below, feel free to expand):
- Npm (currently in use)
- [[ https://yarnpkg.com/features/offline-cache | Yarn 2 (berry) ]]
- [[ https://pnpm.js.org/en/about-package-store | Pnpm ]]
==== Scope
This ticket is only concerned about the tool '''distributing''' already audited packages.RfC is only concerned with the tool **distributing**- already audited packages. Code auditing practices, tools and the matter of tracking vetted package versions is the scope of T257072, Code auditing practices and tools are out of scopea central package store is discussed in T257061.
In this ticket it is assumed that libraryupgrader2 (or similar) would be used to track all packages in our dependency trees, down to the last leaf.
If the matter of tracking vetted package versions need to be discussed, please open a separate ticketdown to the last leaf.
==== Package managers
Without aiming for completeness, there are 2 recent solutions that target specifically the question of security:
====== Yarn 2 (berry)
# `npm i -g yarn@berry`
# [[ https://dev.to/arcanis/introducing-yarn-2-4eh1 | Introductory article ]]
# Yarn 2 was released in 2020. It is a recent, fundamentally different version from (Classic) [[ https://classic.yarnpkg.com/en/docs/migrating-from-npm | Yarn 1 ]] ([[ https://classic.yarnpkg.com/blog/2016/11/24/offline-mirror/ | offline mirror ]]), which made only minor improvements to npm.
# A central offline cache can be synced to individual nodes through a git repository, or presumably other means, thus guaranteeing complete control over outside source-code entering the Wikimedia ecosystem.
# With Yarn 2, package files are loaded directly from the [[ https://yarnpkg.com/features/offline-cache | offline cache (doc) ]], thereby eliminating the 'node_modules' folders, the duplicated packages and speeding up the install step. This breaks many packages assuming the presence of 'node_modules'.
# Packages using [[ https://www.npmjs.com/package/resolve/v/1.9.0 | resolve 1.9.0 ]] (published 2 years ago) are compatible ([[ https://yarnpkg.com/features/pnp#native-support | popular packages ]]).
# Some upstream packages and wikimedia projects need to be upgraded to use 'resolve'. In the meantime an adapter called [[ https://yarnpkg.com/advanced/pnpify | 'pnpify' ]] can be used to execute these. If 'pnpify' fails then the package can be [[ https://yarnpkg.com/advanced/lexicon#unplugged-package | 'unplugged' ]] traditional 'node_modules' can be created with the [[ https://yarnpkg.com/configuration/yarnrc#nodeLinker | nodeLinker: node-modules ]] setting ([[ https://yarnpkg.com/advanced/migration#if-required-enable-the-node-modules-plugin | migration ]]).
# In strict mode only direct dependencies are reachable by packages. This is the correct behavior, but NPM's flattening of node_modules allowed developers to look for indirect dependencies too. Those packages need to be upgraded or the [[ https://yarnpkg.com/features/pnp#pnp-loose-mode | pnpMode: loose ]] setting set.
# Migration: [[ https://yarnpkg.com/advanced/migration#cli-commands | CLI ]], [Q&A] (https://yarnpkg.com/advanced/qa#how-easy-should-you-expect-the-migration-from-classic-to-modern-to-be)
# Yarn supports [[ https://yarnpkg.com/features/workspaces | workspaces ]], but uses a confusing vocabulary where Project > Worktree > Workspace. Our git repos (skins, extensions) would be called [[ https://yarnpkg.com/advanced/lexicon#workspace | "workspace" ]]. The "core" repo would be the "project" or "worktree".
# Script names containing ':' are global, can be executed in any "workspace" of the "project". Scripts like 'svgmin' need to be defined only in the root package.json.
# '.yarn/cache' is stored only in the root.
# The classic version was created by Facebook, Exponent, Google, and Tilde ([[ https://engineering.fb.com/web/yarn-a-new-package-manager-for-javascript/ | article ]]), GitHub lists [[ https://github.com/yarnpkg/yarn/graphs/contributors | 511 contributors ]]. The active developers now are not Facebook employees (ref: [[ https://yarnpkg.com/advanced/qa#is-yarn-operated-by-facebook | Q&A ]]). Being released just half a year ago, it's popularity is beneficial when it comes to its drawback: [[ https://yarnpkg.com/features/pnp#native-support | incompatibility ]].
====== Pnpm
# `npm i -g pnpm`
# Pnpm [[ https://pnpm.js.org/en/about-package-store | package store ]].
# Pnpm was released in 2017, after Classic Yarn.
# Pnpm deduplicates packages using symlinks, recreates node_modules, but only including direct (top-level) dependencies without flattening the dependency tree.
# Packages can load only direct dependencies. Other than that there aren't many complications and setup is easier: if a tool is missing a package, add it to 'devDependencies'.
# Supports [[ https://pnpm.js.org/en/workspaces | workspaces ]] with a simple vocabulary: Workspace > Project. Node packages are linked to the instance in the workspace root if the version constraints allow it. This is the case with libraryupgrader2 keeping dependency versions consistent along projects.
# Drawback of its workspace implementation: 'pnpm install' anywhere in the workspace attempts to create/fix the 'node_modules' folder of all projects in the workspace, even if the developer only needs to do that for one project. If installing a package fails in any of the repos, the install process fails for all repos, creating an unusable state. This might be a reason to not use workspaces, or find a way around this behavior.
# Pnpm was created by one person, it's sponsored by [[ https://github.com/pnpm/pnpm#sponsors | 2 companies ]], used by [[ https://pnpm.js.org/en/users.html | quite a few know companies ]] and GitHub lists [[ https://github.com/pnpm/pnpm/graphs/contributors | 61 contributors ]].
# An [[ https://www.takeshape.io/articles/why-we-switched-from-yarn-to-pnpm/ | article ]] briefly mentioning why Pnpm workspaces were simpler to set up than Yarn 2's.
====== npm
* For completeness it should be mentioned that full control over package versions is achievable with plain old NPM by generating 'package-lock.json' from libraryupgrader2, or using a 'package.json' generated with the exact version of all dependencies, direct and indirect. If developers use `npm ci` instead of `npm i`, their installed version will match too.
====== Common
The configuration and lock files of all 3 PMs can be checked into the same repository without conflict. The PM to use on any box can be chosen independently, allowing the testing of an alternative PM while NPM is used in production. Depending on usability and personal preference, it's also an option for developers to chose their favored PM to use. The workspace management features and simple setup might be reasons to choose on PM over the other.
# 'package.json' is shared, the package versions installed are expected to be the same if run at the same time as NPM (same state of NPM repo).
# 'package-lock.json' is NOT shared, there are individual 'yarn.lock' and 'pnpm-lock.yaml' files, these need to be generated separately.
# Plugins often use 'peerDependencies' to refer to their main package (eg. eslint-plugin-*, stylelint-plugin-*). Both PMs are stricter than NPM and require that the main package is properly declared as dependencies besides the plugins. Some wikimedia 'package.json' files need to be updated to satisfy this constraint, most notably by adding 'eslint', 'stylelint' and their plugins. This strictness might be unwelcome at first, but quickly adapted.
# Grunt currently can't load plugins with either PM. [[ https://github.com/gruntjs/grunt/issues/1713 | Issue ]] submitted upstream. Grunt has lost momentum in last years, so I'll be looking into submitting a PR.
==== Questions
# Security:
## How much control it gives over package versions and code integrity?
## How to integrate with libraryupgrader2 ?
## How much delay is between a version is published on NPM #> delivered to 1) developers, 2) CI, 3) pre#deploy build?
## How much time a version is exposed to CI before being delivered to 1) developers, 2) pre#deploy build?
## How much time a version is exposed to developers before being used for pre#deploy build?
# Progressive transition:
## Is the PM usable in parallel with NPM to allow preparation without disrupting the established processes?
## What features require committing to changing those processes, what's the impact?
## What's the impact of changing PM on CI nodes, developer machines?
# Changes to package loading:
## How to "unplug" (Yarn terminology) packages incompatible with alternative package store (node_modules)?
## What packages need to be unplugged or upgraded to load dependencies (those using custom loaders, not `require.resolve()`)?
# What steps are necessary to make wikimedia projects compatible with the PM, in detail:
## The install process works without warnings: `$PM install`
## Installed packages work (load) as expected.
## Scripts work as with NPM: `$PM run <scriptname>`
# What's the resource usage:
## Storage space required for package store (central), local cache (each CI node and developer box), installed packages (in workspace and each project).
## Network usage vs cache usage.
## Install and update time.
# Usability:
## What are the changes to developers?
## What are the common problems encountered by users?
## Is the developer experience improved?
# Workspaces:
## Is it suitable to the multi#repository setup?
## What benefits it gives to managing the multiple projects that make up a MediaWiki developer instance?