From b067f78ed37e8b6503efbf8c2b320b7f1e48369a Mon Sep 17 00:00:00 2001 From: Jon Koops Date: Thu, 5 May 2022 16:16:51 +0200 Subject: [PATCH] Use CI friendly commands in documentation (#326) --- README.md | 12 ++++++--- docs/advanced-usage.md | 58 +++++++++++++++++++++++++++++++++--------- 2 files changed, 54 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 4c6ff06e..8e8be6ef 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ steps: - uses: actions/setup-node@v3 with: node-version: 14 -- run: npm install +- run: npm ci - run: npm test ``` @@ -41,6 +41,10 @@ major versions: `12`, `14`, `16` more specific versions: `10.15`, `14.2.0`, `16.3.0` nvm lts syntax: `lts/erbium`, `lts/fermium`, `lts/*` +### Checking in lockfiles + +It's **always** recommended to commit the lockfile of your package manager for security and performance reasons. For more information consult the "Working with lockfiles" section of the [Advanced usage](docs/advanced-usage.md#working-with-lockfiles) guide. + ## Caching global packages data The action has a built-in functionality for caching and restoring dependencies. It uses [actions/cache](https://github.com/actions/cache) under the hood for caching global packages data but requires less configuration settings. Supported package managers are `npm`, `yarn`, `pnpm` (v6.10+). The `cache` input is optional, and caching is turned off by default. @@ -60,7 +64,7 @@ steps: with: node-version: 14 cache: 'npm' -- run: npm install +- run: npm ci - run: npm test ``` @@ -74,7 +78,7 @@ steps: node-version: 14 cache: 'npm' cache-dependency-path: subdir/package-lock.json -- run: npm install +- run: npm ci - run: npm test ``` @@ -94,7 +98,7 @@ jobs: uses: actions/setup-node@v3 with: node-version: ${{ matrix.node }} - - run: npm install + - run: npm ci - run: npm test ``` diff --git a/docs/advanced-usage.md b/docs/advanced-usage.md index 3fed348e..e49ea6e2 100644 --- a/docs/advanced-usage.md +++ b/docs/advanced-usage.md @@ -1,4 +1,38 @@ -# Advanced usage +## Working with lockfiles + +All supported package managers recommend that you **always** commit the lockfile, although implementations vary doing so generally provides the following benefits: + +- Enables faster installation for CI and production environments, due to being able to skip package resolution. +- Describes a single representation of a dependency tree such that teammates, deployments, and continuous integration are guaranteed to install exactly the same dependencies. +- Provides a facility for users to "time-travel" to previous states of `node_modules` without having to commit the directory itself. +- Facilitates greater visibility of tree changes through readable source control diffs. + +In order to get the most out of using your lockfile on continuous integration follow the conventions outlined below for your respective package manager. + +### NPM + +Ensure that `package-lock.json` is always committed, use `npm ci` instead of `npm install` when installing packages. + +**See also:** +- [Documentation of `package-lock.json`](https://docs.npmjs.com/cli/v8/configuring-npm/package-lock-json) +- [Documentation of `npm ci`](https://docs.npmjs.com/cli/v8/commands/npm-ci) + +### Yarn + +Ensure that `yarn.lock` is always committed, pass `--frozen-lockfile` to `yarn install` when installing packages. + +**See also:** +- [Documentation of `yarn.lock`](https://classic.yarnpkg.com/en/docs/yarn-lock) +- [Documentation of `--frozen-lockfile` option](https://classic.yarnpkg.com/en/docs/cli/install#toc-yarn-install-frozen-lockfile) +- [QA - Should lockfiles be committed to the repoistory?](https://yarnpkg.com/getting-started/qa/#should-lockfiles-be-committed-to-the-repository) + +### PNPM + +Ensure that `pnpm-lock.yaml` is always committed, when on CI pass `--frozen-lockfile` to `pnpm install` when installing packages. + +**See also:** +- [Working with Git - Lockfiles](https://pnpm.io/git#lockfiles) +- [Documentation of `--frozen-lockfile` option](https://pnpm.io/cli/install#--frozen-lockfile) ## Check latest version @@ -15,7 +49,7 @@ steps: with: node-version: '14' check-latest: true -- run: npm install +- run: npm ci - run: npm test ``` @@ -31,7 +65,7 @@ steps: - uses: actions/setup-node@v3 with: node-version-file: '.nvmrc' -- run: npm install +- run: npm ci - run: npm test ``` @@ -51,7 +85,7 @@ jobs: with: node-version: '14' architecture: 'x64' # optional, x64 or x86. If not specified, x64 will be used by default - - run: npm install + - run: npm ci - run: npm test ``` @@ -67,7 +101,7 @@ steps: with: node-version: '14' cache: 'yarn' -- run: yarn install +- run: yarn install --frozen-lockfile - run: yarn test ``` @@ -89,7 +123,7 @@ steps: with: node-version: '14' cache: 'pnpm' -- run: pnpm install +- run: pnpm install --frozen-lockfile - run: pnpm test ``` @@ -102,7 +136,7 @@ steps: node-version: '14' cache: 'npm' cache-dependency-path: '**/package-lock.json' -- run: npm install +- run: npm ci - run: npm test ``` @@ -117,7 +151,7 @@ steps: cache-dependency-path: | server/app/package-lock.json frontend/app/package-lock.json -- run: npm install +- run: npm ci - run: npm test ``` @@ -152,7 +186,7 @@ jobs: with: node-version: ${{ matrix.node_version }} architecture: ${{ matrix.architecture }} - - run: npm install + - run: npm ci - run: npm test ``` @@ -164,7 +198,7 @@ steps: with: node-version: '14.x' registry-url: 'https://registry.npmjs.org' -- run: npm install +- run: npm ci - run: npm publish env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} @@ -184,7 +218,7 @@ steps: with: node-version: '14.x' registry-url: -- run: yarn install +- run: yarn install --frozen-lockfile - run: yarn publish env: NODE_AUTH_TOKEN: ${{ secrets.YARN_TOKEN }} @@ -206,7 +240,7 @@ steps: registry-url: 'https://registry.npmjs.org' # Skip post-install scripts here, as a malicious # script could steal NODE_AUTH_TOKEN. -- run: npm install --ignore-scripts +- run: npm ci --ignore-scripts env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # `npm rebuild` will run all those post-install scripts for us.