Repository: nodejs/node
Pull request: doc: remove Corepack documentation

Keeping the `corepack.md` file so this can be backported without returning 404 in case there are links in the wild. I'll open a follow-up that removes it which should not be backported.

The reason for this is that the documentation is outdated and not well maintained, and Node.js TSC has decided Corepack won't be distributed on future release lines.

<!--
Before submitting a pull request, please read:

- the CONTRIBUTING guide at https://github.com/nodejs/node/blob/HEAD/CONTRIBUTING.md
- the commit message formatting guidelines at
  https://github.com/nodejs/node/blob/HEAD/doc/contributing/pull-requests.md#commit-message-guidelines

For code changes:
1. Include tests for any bug fixes or new features.
2. Update documentation if relevant.
3. Ensure that `make -j4 test` (UNIX), or `vcbuild test` (Windows) passes.

If you believe this PR should be highlighted in the Node.js CHANGELOG
please add the `notable-change` label.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.
-->


Changed files:
filename: doc/api/corepack.md
patch: @@ -12,139 +12,10 @@ added:
 
 > Stability: 1 - Experimental
 
-_[Corepack][Corepack repository]_ is an experimental tool to help with
-managing versions of your package managers. It exposes binary proxies for
-each [supported package manager][] that, when called, will identify whatever
-package manager is configured for the current project, download it if needed,
-and finally run it.
+Documentation for this tool can be found on the [Corepack repository][].
 
 Despite Corepack being distributed with default installs of Node.js, the package
-managers managed by Corepack are not part of the Node.js distribution and:
+managers managed by Corepack are not part of the Node.js distribution, and
+Corepack itself will no longer be distributed with future versions of Node.js.
 
-* Upon first use, Corepack downloads the latest version from the network.
-* Any required updates (related to security vulnerabilities or otherwise) are
-  out of scope of the Node.js project. If necessary end users must figure out
-  how to update on their own.
-
-This feature simplifies two core workflows:
-
-* It eases new contributor onboarding, since they won't have to follow
-  system-specific installation processes anymore just to have the package
-  manager you want them to.
-
-* It allows you to ensure that everyone in your team will use exactly the
-  package manager version you intend them to, without them having to
-  manually synchronize it each time you need to make an update.
-
-## Workflows
-
-### Enabling the feature
-
-Due to its experimental status, Corepack currently needs to be explicitly
-enabled to have any effect. To do that, run [`corepack enable`][], which
-will set up the symlinks in your environment next to the `node` binary
-(and overwrite the existing symlinks if necessary).
-
-From this point forward, any call to the [supported binaries][] will work
-without further setup. Should you experience a problem, run
-[`corepack disable`][] to remove the proxies from your system (and consider
-opening an issue on the [Corepack repository][] to let us know).
-
-### Configuring a package
-
-The Corepack proxies will find the closest [`package.json`][] file in your
-current directory hierarchy to extract its [`"packageManager"`][] property.
-
-If the value corresponds to a [supported package manager][], Corepack will make
-sure that all calls to the relevant binaries are run against the requested
-version, downloading it on demand if needed, and aborting if it cannot be
-successfully retrieved.
-
-You can use [`corepack use`][] to ask Corepack to update your local
-`package.json` to use the package manager of your choice:
-
-```bash
-corepack use pnpm@7.x # sets the latest 7.x version in the package.json
-corepack use yarn@* # sets the latest version in the package.json
-```
-
-### Upgrading the global versions
-
-When running outside of an existing project (for example when running
-`yarn init`), Corepack will by default use predefined versions roughly
-corresponding to the latest stable releases from each tool. Those versions can
-be overridden by running the [`corepack install`][] command along with the
-package manager version you wish to set:
-
-```bash
-corepack install --global yarn@x.y.z
-```
-
-Alternately, a tag or range may be used:
-
-```bash
-corepack install --global pnpm@*
-corepack install --global yarn@stable
-```
-
-### Offline workflow
-
-Many production environments don't have network access. Since Corepack
-usually downloads the package manager releases straight from their registries,
-it can conflict with such environments. To avoid that happening, call the
-[`corepack pack`][] command while you still have network access (typically at
-the same time you're preparing your deploy image). This will ensure that the
-required package managers are available even without network access.
-
-The `pack` command has [various flags][]. Consult the detailed
-[Corepack documentation][] for more information.
-
-## Supported package managers
-
-The following binaries are provided through Corepack:
-
-| Package manager | Binary names      |
-| --------------- | ----------------- |
-| [Yarn][]        | `yarn`, `yarnpkg` |
-| [pnpm][]        | `pnpm`, `pnpx`    |
-
-## Common questions
-
-### How does Corepack interact with npm?
-
-While Corepack could support npm like any other package manager, its
-shims aren't enabled by default. This has a few consequences:
-
-* It's always possible to run a `npm` command within a project configured to
-  be used with another package manager, since Corepack cannot intercept it.
-
-* While `npm` is a valid option in the [`"packageManager"`][] property, the
-  lack of shim will cause the global npm to be used.
-
-### Running `npm install -g yarn` doesn't work
-
-npm prevents accidentally overriding the Corepack binaries when doing a global
-install. To avoid this problem, consider one of the following options:
-
-* Don't run this command; Corepack will provide the package manager
-  binaries anyway and will ensure that the requested versions are always
-  available, so installing the package managers explicitly isn't needed.
-
-* Add the `--force` flag to `npm install`; this will tell npm that it's fine to
-  override binaries, but you'll erase the Corepack ones in the process. (Run
-  [`corepack enable`][] to add them back.)
-
-[Corepack documentation]: https://github.com/nodejs/corepack#readme
 [Corepack repository]: https://github.com/nodejs/corepack
-[Yarn]: https://yarnpkg.com
-[`"packageManager"`]: packages.md#packagemanager
-[`corepack disable`]: https://github.com/nodejs/corepack#corepack-disable--name
-[`corepack enable`]: https://github.com/nodejs/corepack#corepack-enable--name
-[`corepack install`]: https://github.com/nodejs/corepack#corepack-install--g--global---all--nameversion
-[`corepack pack`]: https://github.com/nodejs/corepack#corepack-pack---all--nameversion
-[`corepack use`]: https://github.com/nodejs/corepack#corepack-use-nameversion
-[`package.json`]: packages.md#nodejs-packagejson-field-definitions
-[pnpm]: https://pnpm.io
-[supported binaries]: #supported-package-managers
-[supported package manager]: #supported-package-managers
-[various flags]: https://github.com/nodejs/corepack#utility-commands

filename: doc/api/index.md
patch: @@ -21,7 +21,6 @@
 * [Cluster](cluster.md)
 * [Command-line options](cli.md)
 * [Console](console.md)
-* [Corepack](corepack.md)
 * [Crypto](crypto.md)
 * [Debugger](debugger.md)
 * [Deprecated APIs](deprecations.md)

filename: doc/api/packages.md
patch: @@ -259,21 +259,6 @@ For completeness there is also `--input-type=commonjs`, for explicitly running
 string input as CommonJS. This is the default behavior if `--input-type` is
 unspecified.
 
-## Determining package manager
-
-> Stability: 1 - Experimental
-
-While all Node.js projects are expected to be installable by all package
-managers once published, their development teams are often required to use one
-specific package manager. To make this process easier, Node.js ships with a
-tool called [Corepack][] that aims to make all package managers transparently
-available in your environment - provided you have Node.js installed.
-
-By default Corepack won't enforce any specific package manager and will use
-the generic "Last Known Good" versions associated with each Node.js release,
-but you can improve this experience by setting the [`"packageManager"`][] field
-in your project's `package.json`.
-
 ## Package entry points
 
 In a package's `package.json` file, two fields can define entry points for a
@@ -905,8 +890,6 @@ The following fields in `package.json` files are used in Node.js:
   by package managers as the name of the package.
 * [`"main"`][] - The default module when loading the package, if exports is not
   specified, and in versions of Node.js prior to the introduction of exports.
-* [`"packageManager"`][] - The package manager recommended when contributing to
-  the package. Leveraged by the [Corepack][] shims.
 * [`"type"`][] - The package type determining whether to load `.js` files as
   CommonJS or ES modules.
 * [`"exports"`][] - Package exports and conditional exports. When present,
@@ -971,33 +954,6 @@ via `require()`](modules.md#folders-as-modules).
 require('./path/to/directory');
 ```
 
-### `"packageManager"`
-
-<!-- YAML
-added:
-  - v16.9.0
-  - v14.19.0
--->
-
-> Stability: 1 - Experimental
-
-* Type: {string}
-
-```json
-{
-  "packageManager": "<package manager name>@<version>"
-}
-```
-
-The `"packageManager"` field defines which package manager is expected to be
-used when working on the current project. It can be set to any of the
-[supported package managers][], and will ensure that your teams use the exact
-same package manager versions without having to install anything else other than
-Node.js.
-
-This field is currently experimental and needs to be opted-in; check the
-[Corepack][] page for details about the procedure.
-
 ### `"type"`
 
 <!-- YAML
@@ -1137,7 +1093,6 @@ This field defines [subpath imports][] for the current package.
 
 [CommonJS]: modules.md
 [Conditional exports]: #conditional-exports
-[Corepack]: corepack.md
 [ES module]: esm.md
 [ES modules]: esm.md
 [Node.js documentation for this section]: https://github.com/nodejs/node/blob/HEAD/doc/api/packages.md#conditions-definitions
@@ -1148,7 +1103,6 @@ This field defines [subpath imports][] for the current package.
 [`"imports"`]: #imports
 [`"main"`]: #main
 [`"name"`]: #name
-[`"packageManager"`]: #packagemanager
 [`"type"`]: #type
 [`--conditions` / `-C` flag]: #resolving-user-conditions
 [`--no-addons` flag]: cli.md#--no-addons
@@ -1163,7 +1117,6 @@ This field defines [subpath imports][] for the current package.
 [self-reference]: #self-referencing-a-package-using-its-name
 [subpath exports]: #subpath-exports
 [subpath imports]: #subpath-imports
-[supported package managers]: corepack.md#supported-package-managers
 [the dual CommonJS/ES module packages section]: #dual-commonjses-module-packages
 [the full specifier path]: esm.md#mandatory-file-extensions
 [the package examples repository]: https://github.com/nodejs/package-examples

filename: test/doctool/test-make-doc.mjs
patch: @@ -45,7 +45,7 @@ const linkedHtmls = [...new Set(links)].map((link) => link.match(re)[1])
 const expectedJsons = linkedHtmls
                        .map((name) => name.replace('.html', '.json'));
 const expectedDocs = linkedHtmls.concat(expectedJsons);
-const renamedDocs = ['policy.json', 'policy.html'];
+const renamedDocs = ['corepack.json', 'corepack.html', 'policy.json', 'policy.html'];
 const skipedDocs = ['quic.json', 'quic.html'];
 
 // Test that all the relative links in the TOC match to the actual documents.