feat: add more documentation about --no-frozen-lockfile (#4156)

close #4151

.changeset/fair-hotels-suffer.md

@@ -0,0 +1,6 @@
+---
+"@pnpm/core": patch
+"@pnpm/headless": patch
+---
+
+Add more details to the frozen lockfile error.

.changeset/many-colts-think.md

@@ -0,0 +1,5 @@
+---
+"@pnpm/plugin-commands-installation": patch
+---
+
+Document `--no-frozen-lockfile` explicitly in the help of the install command.

packages/core/src/install/index.ts

@@ -251,7 +251,9 @@ export async function mutateModules (
       )
     ) {
       if (needsFullResolution) {
-        throw new PnpmError('FROZEN_LOCKFILE_WITH_OUTDATED_LOCKFILE', 'Cannot perform a frozen installation because the lockfile needs updates')
+        throw new PnpmError('FROZEN_LOCKFILE_WITH_OUTDATED_LOCKFILE', 'Cannot perform a frozen installation because the lockfile needs updates', {
+          hint: 'Note that in CI environments this setting is true by default. If you still need to run install in such cases, use "pnpm install --no-frozen-lockfile"',
+        })
       }
       if (!ctx.existsWantedLockfile) {
         if (ctx.projects.some((project) => pkgHasDependencies(project.manifest))) {

packages/headless/src/index.ts

@@ -155,7 +155,9 @@ export default async (opts: HeadlessOptions) => {
       if (!satisfiesPackageManifest(wantedLockfile, manifest, id)) {
         throw new PnpmError('OUTDATED_LOCKFILE',
           `Cannot install with "frozen-lockfile" because ${WANTED_LOCKFILE} is not up-to-date with ` +
-          path.relative(lockfileDir, path.join(rootDir, 'package.json')))
+          path.relative(lockfileDir, path.join(rootDir, 'package.json')), {
+            hint: 'Note that in CI environments this setting is true by default. If you still need to run install in such cases, use "pnpm install --no-frozen-lockfile"',
+          })
       }
     }
   }

packages/plugin-commands-installation/src/install.ts

@@ -123,8 +123,8 @@ For options that may be used with `-r`, see "pnpm help recursive"',
             name: '--lockfile-only',
           },
           {
-            description: "Don't generate a lockfile and fail if an update is needed",
-            name: '--frozen-lockfile',
+            description: "Don't generate a lockfile and fail if an update is needed. This setting is on by default in CI environments, so use --no-frozen-lockfile if you need to disable it for some reason",
+            name: '--[no-]frozen-lockfile',
           },
           {
             description: `If the available \`${WANTED_LOCKFILE}\` satisfies the \`package.json\` then perform a headless installation`,