From 3690000aa34325922b1e47979a9f99e17ba63887 Mon Sep 17 00:00:00 2001 From: Derk-Jan Karrenbeld Date: Fri, 18 Oct 2024 21:35:00 +0200 Subject: [PATCH] Update docs for corepack and pnpm --- CONTRIBUTING.md | 14 +++++++------- config/exercise-readme-insert.md | 10 ++++++++-- docs/INSTALLATION.md | 31 ++++++++++++++++++------------- docs/TESTS.md | 6 +++--- exercises/shared/.docs/tests.md | 16 +++++++--------- 5 files changed, 43 insertions(+), 34 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 835c0e5dc4..ec294a03a0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ It's not uncommon that people discover incorrect implementations of certain test We welcome contributions of all sorts and sizes, from reporting issues to submitting patches, as well as joining the current [discussions 💬][issue-discussion]. -> [!WARNING] +> [!WARNING] > This guide is slightly outdated and doesn't hold the V3 changes yet. --- @@ -168,7 +168,7 @@ You may improve these files by making the required changes and opening a new Pul ## Tools You'll need LTS or higher Node.js to contribute to the _code_ in this repository. -Run `npm install` in the root to be able to run the scripts as listed below. +Run `corepack pnpm install` in the root to be able to run the scripts as listed below. We use the following dependencies: - `shelljs` to provide shell interface to scripts @@ -177,9 +177,9 @@ We use the following dependencies: - `babel` to transpile everything so it works _regardless of your version of Node.js_. We also use `prettier` to format the files. -**Prettier is installed when using `npm install`**. -You may use `npx babel-node scripts/format` to run prettier. -If you want to auto-format using your editor, install via `npm install` and it will Just Work™. +**Prettier is installed when using `corepack pnpm install`**. +You may use `corepack pnpm node scripts/format.mjs` to run prettier. +If you want to auto-format using your editor, install via `corepack pnpm install` and it will Just Work™. ### Fetch configlet @@ -210,7 +210,7 @@ It then interactively gives the maintainer the option to include or exclude test We have various `scripts` to aid with maintaining and contributing to this repository. -> [!IMPORTANT] +> [!IMPORTANT] > If you encounter the following error: > > ```text @@ -243,7 +243,7 @@ We have various `scripts` to aid with maintaining and contributing to this repos ``` Use this action to format all the files using the correct version of prettier. -If you want your editor to do this automatically, install the project development dependencies (`npm i`), which includes `prettier`. +If you want your editor to do this automatically, install the project development dependencies (`corepack pnpm install`), which includes `prettier`. The correct version will be extracted when running `.github/workflows/verify-code-formatting.yml`. #### `lint` diff --git a/config/exercise-readme-insert.md b/config/exercise-readme-insert.md index d2fa14273b..7927d0366a 100644 --- a/config/exercise-readme-insert.md +++ b/config/exercise-readme-insert.md @@ -14,7 +14,13 @@ Please `cd` into exercise directory before running all below commands. Install assignment dependencies: ```bash -$ npm install +$ corepack pnpm install +``` + +If `corepack` complains about not being enabled, you can do so by running: + +```bash +corepack enable pnpm ``` ## Making the test suite pass @@ -22,7 +28,7 @@ $ npm install Execute the tests with: ```bash -$ npm test +$ corepack pnpm test ``` In the test suites all tests but the first have been skipped. diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index a32eab521c..ee9a3f4818 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -70,6 +70,14 @@ The version should match the one on the website. > > Close any open terminals and open a new one. +## Enabling corepack + +In order to use a versioned package manager compatible with this track, `corepack` needs to be enabled once: + +```shell +corepack enable pnpm +``` + ## Assignment Requirements Please follow [these instructions][cli-walkthrough] to download the Exercism CLI for your OS. @@ -84,26 +92,23 @@ Each assignment then needs some tools to run the tests. They can be installed running this command within each assignment directory: ```shell -npm install +corepack pnpm install ``` -> [!IMPORTANT] > _**Help**_: `'' is missing / cannot be found` -> -> If you see this after _upgrading_ your exercise, welcome to npm 7. -> Delete `node_modules` and `package-lock.json` and re-run the command to resolve this. - -If you're concerned about disk space and are okay installing another tool, take a look at [pnpm](https://pnpm.io/), which ensure only one copy of each package-version is ever installed on disk. -In this case, run `pnpm install` instead of `npm install`, and everything should work as expected. +As this track has switched to pnpm, you should not be concerned about disk space. +Take a look at [pnpm](https://pnpm.io/), which ensures only one copy of each package-version is ever installed on disk. -> **But what is npm and why does this work?** +> **But what is corepack and why does this work?** > > You don't need this information to complete the JavaScript track, but if you're eager to understand what just happened, the following paragraphs are for you: > -> This works because `npm` is a package manager that comes bundled with Node.js, which has been installed per the steps above. -> The `npm` command looks for a `package.json` file, which is present in _each_ assignment folder. -> This file lists the `"dependencies"` above, which are then downloaded by `npm` and placed into the `node_modules` folder. +> This works because `corepack` is a tool that comes bundled with Node.js, which has been installed per the steps above. +> It can install the package manager `pnpm`. It configures the system +> The `corepack` command looks for a `package.json` file, which is present in _each_ assignment folder. +> It then checks `packageManager` which matches `pnpm`, so it may continue. If necessary it will upgrade `pnpm` first. +> This file also lists the `"dependencies"` above, which are then downloaded by `pnpm` and placed into a local cache. > -> The scripts in the `package.json` use the binaries from the local `node_modules` folder, and it's these scripts that are used to run the tests, as listed in the `exercise` description. +> The scripts in the `package.json` use the binaries from the local cache, and it's these scripts that are used to run the tests, as listed in the `exercise` description. [web-nodejs]: https://nodejs.org/ [web-nodejs-download]: https://nodejs.org/en/download/ diff --git a/docs/TESTS.md b/docs/TESTS.md index 5923ad06f9..c45bf03a65 100644 --- a/docs/TESTS.md +++ b/docs/TESTS.md @@ -3,20 +3,20 @@ Execute the tests with: ```shell -npm run test +corepack pnpm test ``` Be sure your code follows best practices and coding styles, as other users do, with ESLint, a tool to perform static analysis on your code. Sometimes, tools like this save you some time detecting typos or silly mistakes in your JavaScript code: ```shell -npm run lint +corepack pnpm lint ``` You can also run Jest in "watch" mode, which will re-run your tests automatically when you save changes to the code or test module: ```shell -npm run watch +corepack pnpm watch ``` ## Understanding Skip Tests diff --git a/exercises/shared/.docs/tests.md b/exercises/shared/.docs/tests.md index c7f3fdb47a..45f813eb55 100644 --- a/exercises/shared/.docs/tests.md +++ b/exercises/shared/.docs/tests.md @@ -9,11 +9,13 @@ Go through the setup [instructions for JavaScript][docs-exercism-javascript] to Install assignment dependencies: ```shell -# Using npm -npm install +corepack pnpm install +``` + +If `corepack` complains about not being enabled, you can do so by running: -# Alternatively using yarn -yarn +```bash +corepack enable pnpm ``` ## Making the test suite pass @@ -22,11 +24,7 @@ All exercises come with a test suite to help you validate your solution before s You can execute these tests by opening a command prompt in the exercise's directory, and then running: ```bash -# Using npm -npm test - -# Alternatively using yarn -yarn test +corepack pnpm test ``` In some test suites all tests but the first have been skipped.