Skip to content

docs(rfcs): review RFCs for drift from the implementation #3396

Open

Description

@hyunbinseo

Documentation is

  • Missing
  • Outdated
  • Confusing
  • Not sure

Explain in Detail

Several RFCs in rfcs/ have drifted from the implementation. voidzero-dev/vite-plus#3383 fixed the .nvmrc part, and listed other gaps it left out:

  • rfcs/env-command.md: the CLI usage comment # Pin a specific version in current directory (creates .node-version) predates the devEngines.runtime default target.
  • rfcs/env-command.md: the "Pin Command" section covers Node pins only. --target package-manager isn't mentioned.
  • rfcs/dev-engines.md: the decision table (row 4) lists only --target node-version / --target dev-engines.

These were found while working on one topic, so there are likely more. Some RFCs also mix the original decision with later revisions (e.g. "Breaking revision: unified environments" in rfcs/env-command.md), so it's unclear which parts should track the implementation.

Your Suggestion for Changes

Ideally, the team reviews the RFCs as a whole, since it knows which decisions changed and why. It could also clarify whether RFCs are living specs or historical records — the dev-engines.md decision table was left unchanged in #3383 for that reason.

If that's not feasible, I can continue with follow-up PRs, one topic each.

@liangmiQwQ, following up on your comment here, since replying in the merged PR would be noise.

Relevant Page

https://github.com/voidzero-dev/vite-plus/tree/main/rfcs

Activity

  1. hyunbinseo commented on Nov 9, 2026

    @hyunbinseo
    ContributorAuthor

    @jong-kyung Thanks for assigning, but could the team review the RFCs as a whole first? It's hard for me to decide alone:

    • I don't know which development decisions changed later, or why.
    • I can't determine how to fix the drift — update RFCs as living specs, or keep them as historical records.

    Happy to help with PRs once that's settled.

  2. jong-kyung commented on Nov 9, 2026

    @jong-kyung
    Collaborator

    @liangmiQwQ knows the env-command.md and dev-engines.md changes better than I do. Could you take a look?

  3. added theissue type on Nov 9, 2026
  4. liangmiQwQ commented on Nov 9, 2026

    @liangmiQwQ
    Collaborator

    @liangmiQwQ knows the env-command.md and dev-engines.md changes better than I do. Could you take a look?

    Okay! I would check when I have time.

  5. liangmiQwQ commented on Nov 20, 2026

    @liangmiQwQ
    Collaborator

    I reviewed the RFCs against main and found the following outdated items. For the items below, the documentation should follow the current implementation. Sections explicitly describing deferred or future work are outside this list.

    # RFC / section Outdated content Current behavior / documentation change
    1 env-command.md: Diagnostic Commands and Current Command; dev-engines.md: §3.4 Examples use vp env --current and vp env --print. Use the vp env current and vp env print subcommands.
    2 env-command.md: Version Management Commands and pin examples Pinning is described as creating .node-version, and unpinning as deleting that file. Preserve an existing .node-version or an effective local .nvmrc; otherwise write devEngines.runtime when the current directory has a package.json, falling back to .node-version when it does not. Update the examples accordingly.
    3 env-command.md: Pin Command The detailed section covers Node pins only, and its target list omits package-manager pins. Document package-manager pinning at the workspace root, versus Node pinning in the current directory. The targets are node-version, nvmrc, dev-engines, and package-manager; dev-engines can target either component.
    4 env-command.md: List, List-Remote, and Current JSON examples The examples retain the old Node-only / flattened JSON contracts. Current returns node and package_manager; both list commands return node and package_managers. Scoped calls omit unselected components. Package-manager current information uses bin_paths.
    5 env-command.md: Exec Command --npm is marked unimplemented, and --package-manager is missing. Both are implemented. --npm X is an alias for --package-manager npm@X; using both together is rejected.
    6 env-command.md: Clean Command It says all downloaded package-manager installs are removed. Cleanup protects the current shim selection, the selected version for vp commands, and the configured default for each family. If protection cannot be resolved for a family, cleanup skips that family.
    7 dev-engines.md: §2.1 Read priority The complete read-priority list omits .nvmrc, although §2.4 already discusses it. Include .nvmrc after engines.node, with project sources checked in priority order within each directory before walking to its parent.
    8 package-manager-detection.md: Priority 3/5 and Version Resolution Lockfile/config/default detection is described as resolving every manager to registry latest. Detection returns the internal default marker. In particular, an unversioned npm selection uses npm on the effective PATH rather than downloading registry latest. See the npm details below.
    9 package-manager-detection.md: create selection priority The list omits the package-manager override, launcher detection, and the npm fallback. I will handle this item, together with the related changes I am working on.
    10 Directory-layout descriptions and code examples in env-command.md, js-runtime.md, global-cli-rust-binary.md, upgrade-command.md, and related RFCs Several examples present the monolithic ~/.vite-plus layout as the default, or reference the removed get_vite_plus_home() helper. I will handle this item. I intend to remove outdated duplicated code examples and refer to directory-layout.md / VpDirs. Explicit VP_HOME and grandfathered installations still support the monolithic layout.
    11 split-global-cli.md: Delegate to local CLI Commands It says the global CLI prompts to install a missing local CLI into the project. It falls back to the global installation's JS CLI, with a missing-local warning for projects, rather than automatically adding a project dependency.
    12 implode-command.md: User Stories and Confirmation The confirmation word is uninstall. The current confirmation word is boom.
    13 Test instructions across multiple RFCs References still point to packages/cli/snap-tests*, packages/global/snap-tests, and old snap-test-global scripts. Use crates/vp_cli_snapshots/tests/cli_snapshots/fixtures and the current just snapshot-test / just snapshot-test-global commands. Historical descriptions of the old runner can remain identified as historical.

    (🤖 Generated with Codex)

    I am actively working on the create package-manager selection and directory-layout issues in items 9 and 10, so I will update those parts myself. For the remaining items, please follow the current implementation; documentation PRs are welcome.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

documentationImprovements or additions to documentation

Type

Fields

Priority

None yet

Effort

None yet

Target date

None yet

Start date

None yet

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions