From 2377de8e4b38092952a1673b5768f7bf66674024 Mon Sep 17 00:00:00 2001 From: Liang Date: Sat, 26 Sep 2026 16:58:04 +0800 Subject: [PATCH 1/4] wip --- CONTRIBUTING.md | 35 +++++++++++++++++++++++++++++++---- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a2f66a24e..ae9c5d658e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,12 +2,31 @@ ## Initial Setup +You'll need the following tools installed on your system: + +- Node.js (version specified in [`.node-version`](.node-version)) +- pnpm (version specified in the `packageManager` field of [`package.json`](package.json)) +- Just +- CMake +- Rust and Cargo +- cargo-binstall + +If you haven't installed Node.js and pnpm, we recommend using Vite+ to manage them. See [environment management](docs/guide/env.md) for details. + ### macOS / Linux -You'll need the following tools installed on your system: +If you need Node.js and pnpm, install Vite+ and enable environment management when prompted: ```bash -brew install pnpm node just cmake +curl -fsSL https://vite.plus | bash +``` + +After installing Vite+, restart your terminal to activate the `node` and `pnpm` shims. + +You'll also need Just and CMake: + +```bash +brew install just cmake ``` Install Rust & Cargo using rustup: @@ -25,10 +44,18 @@ just init ### Windows -You'll need the following tools installed on your system. You can use [winget](https://learn.microsoft.com/en-us/windows/package-manager/). +If you need Node.js and pnpm, install Vite+ and enable environment management when prompted: + +```powershell +irm https://viteplus.dev/install.ps1 | iex +``` + +After installing Vite+, restart your terminal to activate the `node` and `pnpm` shims. + +You'll also need Just and CMake. You can install them using [winget](https://learn.microsoft.com/en-us/windows/package-manager/): ```powershell -winget install pnpm.pnpm OpenJS.NodeJS.LTS Casey.Just Kitware.CMake +winget install Casey.Just Kitware.CMake ``` Install Rust & Cargo from [rustup.rs](https://rustup.rs/), then install `cargo-binstall`: From 4b3ce7d624b86a056d6ece4f00d7baec3a71049a Mon Sep 17 00:00:00 2001 From: Liang Date: Sat, 26 Sep 2026 17:02:03 +0800 Subject: [PATCH 2/4] wip --- CONTRIBUTING.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ae9c5d658e..6771c253d4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,14 +11,14 @@ You'll need the following tools installed on your system: - Rust and Cargo - cargo-binstall -If you haven't installed Node.js and pnpm, we recommend using Vite+ to manage them. See [environment management](docs/guide/env.md) for details. +If you haven't installed Node.js and pnpm, we recommend using Vite+ to manage them. See [environment management](https://viteplus.dev/guide/env) for details. ### macOS / Linux -If you need Node.js and pnpm, install Vite+ and enable environment management when prompted: +If you haven't installed Node.js and pnpm, we recommend installing them with Vite+: ```bash -curl -fsSL https://vite.plus | bash +curl -fsSL https://vite.plus | VP_NODE_MANAGER=yes VP_PM_MANAGER=yes bash ``` After installing Vite+, restart your terminal to activate the `node` and `pnpm` shims. @@ -44,9 +44,11 @@ just init ### Windows -If you need Node.js and pnpm, install Vite+ and enable environment management when prompted: +If you haven't installed Node.js and pnpm, we recommend installing them with Vite+: ```powershell +$env:VP_NODE_MANAGER = "yes" +$env:VP_PM_MANAGER = "yes" irm https://viteplus.dev/install.ps1 | iex ``` From 3a09a3b4b71702c655e10111dc643972d9c9a735 Mon Sep 17 00:00:00 2001 From: Liang Date: Sat, 26 Sep 2026 17:08:02 +0800 Subject: [PATCH 3/4] wip --- CONTRIBUTING.md | 25 ------------------------- 1 file changed, 25 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6771c253d4..b87f325264 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -200,31 +200,6 @@ gh extension install github/gh-stack Stacked pull requests require all branches to be in this repository; GitHub does not support cross-fork stacks ([reference](https://docs.github.com/en/pull-requests/reference/stacked-pull-requests)). If you contribute from a fork, split large work into a sequence of standalone PRs instead. -## Verified Commits - -All commits in PR branches should be GitHub-verified so reviewers can confirm commit authenticity. - -Set up local commit signing and GitHub verification first: - -- Follow GitHub's guide for GPG commit signature verification: https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification#gpg-commit-signature-verification - -After setup, re-sign any existing commits in your branch so the full branch is verified: - -```bash -# Re-sign each commit on your branch (replace origin/main with your branch base if needed) -git rebase -i origin/main -# At each stop: -git commit --amend --date=now --no-edit -S -# Then continue: -git rebase --continue -``` - -When done, force-push the updated branch history: - -```bash -git push --force-with-lease -``` - ## Release and recovery The [release workflow](.github/workflows/release.yml) publishes packages in dependency order: platform packages → `@voidzero-dev/vite-plus-core` → `vite-plus`. After each tier, it waits up to 10 minutes for the exact versions and their tarballs to become available. It then waits another 60 seconds for CDN propagation. From 924ae56749daf11def1b9e12c54769fd6f474baa Mon Sep 17 00:00:00 2001 From: Liang Date: Sat, 26 Sep 2026 17:17:55 +0800 Subject: [PATCH 4/4] wip --- CONTRIBUTING.md | 33 ++++----------------------------- MAINTENANCE.md | 19 ++++++++++++++++++- packages/tools/README.md | 10 ++++++++++ 3 files changed, 32 insertions(+), 30 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b87f325264..dc90678a49 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -133,7 +133,7 @@ Verify the link with `ls -l node_modules/vite-plus` (it should be a symlink into ### Test `vp migrate` / `vp create` through a local npm registry -`pnpm link` swaps the code inside an existing project, but `vp migrate` and `vp create` pin the exact CLI version and then _install_ it, so the checkout's `vite-plus` / `@voidzero-dev/vite-plus-core` must be resolvable from a registry. `packages/tools/src/local-npm-registry.ts` provides that: it packs the checkout, serves the tarballs behind a real registry HTTP interface, and proxies every other package upstream. This replaces the old pkg.pr.new publish + registry-bridge round-trip for local iteration; you can verify migrate/create logic immediately after a build. +`pnpm link` swaps the code inside an existing project, but `vp migrate` and `vp create` pin the exact CLI version and then _install_ it. Use the local npm registry to make your built checkout available to these commands. ```bash pnpm build # the served packages are built artifacts; rebuild after JS changes @@ -148,20 +148,11 @@ pnpm local-registry --pack --serve # copy the printed `export ...` lines into the shell where you run vp ``` -Notes: - -- The served versions carry an old publish time, so `minimumReleaseAge` gates never quarantine them, and wrapped runs get throwaway Yarn Berry / bun caches (both cache registry state in ways that would otherwise leak stale local builds between runs). -- The same server backs PTY snapshot cases with `local-registry = true` and ecosystem e2e (`ecosystem-ci/patch-project.ts`), so a flow that works here works there too. -- `pnpm local-registry:ps` lists any registry processes still running (e.g. a `--serve` you forgot, or a wrapper that was killed mid-run); `pnpm local-registry:kill` stops them all and removes their leftover temp caches. +`pnpm local-registry:ps` lists any registry processes still running; `pnpm local-registry:kill` stops them all and removes their leftover temp caches. See the [tool documentation](packages/tools/README.md#local-npm-registry) for implementation details and test integration. ### Global CLI (Rust) changes -`pnpm link` only swaps the JS side; the `vp` binary on `PATH` (and the Rust-backed commands it handles directly, such as package-manager commands) is still whatever is installed in `~/.vite-plus`. For changes to the Rust global CLI (`crates/`), install it from source, and combine with `pnpm link` when the change spans both layers: - -```bash -pnpm bootstrap-cli -vp --version -``` +`pnpm link` only swaps the JS side; the `vp` binary on `PATH` (and the Rust-backed commands it handles directly, such as package-manager commands) is still the installed binary. For changes to the Rust global CLI (`crates/`), follow [the source installation steps](#install-the-vite-global-cli-from-source-code), and combine with `pnpm link` when the change spans both layers. ## Workflow for build and test @@ -190,23 +181,7 @@ The full case/step/interaction reference (including the `vpt` helper tool and mi ## Submitting Pull Requests -Prioritize stacked pull requests when your work splits into reviewable layers, for example a refactor PR with the feature PR that depends on it stacked on top. Reviewers handle a stack of small PRs faster than one large PR, and each layer merges on its own. - -GitHub has built-in stacked pull requests ([public preview](https://github.blog/changelog/2026-07-30-stacked-pull-requests-are-now-in-public-preview/), rolling out to all repositories). Create stacks on github.com, or from the terminal: - -```bash -gh extension install github/gh-stack -``` - -Stacked pull requests require all branches to be in this repository; GitHub does not support cross-fork stacks ([reference](https://docs.github.com/en/pull-requests/reference/stacked-pull-requests)). If you contribute from a fork, split large work into a sequence of standalone PRs instead. - -## Release and recovery - -The [release workflow](.github/workflows/release.yml) publishes packages in dependency order: platform packages → `@voidzero-dev/vite-plus-core` → `vite-plus`. After each tier, it waits up to 10 minutes for the exact versions and their tarballs to become available. It then waits another 60 seconds for CDN propagation. - -A propagation timeout fails the release job and stops subsequent steps. This does not mean npm rejected the upload; npm may have accepted it and still be scanning the packages. - -Once the packages become available, open the failed workflow run in GitHub Actions and select **Re-run failed jobs**. The workflow skips versions that npm has published and checks availability again before continuing. Keep the same version. +Keep pull requests small and focused. Split changes that can be reviewed and merged independently into separate PRs. If one change depends on another, submit the dependent PR after its prerequisite has merged. ## Pull upstream dependencies diff --git a/MAINTENANCE.md b/MAINTENANCE.md index 5f4b90a4d7..90fef2796d 100644 --- a/MAINTENANCE.md +++ b/MAINTENANCE.md @@ -1,6 +1,6 @@ # Maintenance -## Publishing Preview Packages +## Publishing preview packages Add the `preview-build` label to the PR. Each labeled commit is published to the [registry bridge](https://registry-bridge.viteplus.dev/-/refs) as the npm @@ -19,3 +19,20 @@ Or pin it in a project through the bridge registry (`.npmrc`: ```sh pnpm add vite-plus@0.0.0-commit. ``` + +## Publishing releases + +The [release workflow](.github/workflows/release.yml) publishes platform packages before `@voidzero-dev/vite-plus-core`, then publishes `vite-plus`. It checks that the required package versions and tarballs are available before continuing to dependent steps. + +The [propagation helper](.github/scripts/wait-for-npm-packages.ts) defaults to a 10-minute timeout and an additional 60-second wait for CDN propagation after availability checks pass. + +### Recovering from a propagation timeout + +A propagation timeout fails the release job and stops subsequent steps. This does not mean npm rejected the upload; npm may have accepted it and still be scanning the packages. + +Keep the same version when resuming the release: + +1. Wait until the affected package versions and tarballs are available on npm. +2. Open the failed workflow run in GitHub Actions and select **Re-run failed jobs**. + +The [publish helper](.github/scripts/publish-npm-package.ts) skips versions that npm has published, and the workflow checks availability again before continuing. diff --git a/packages/tools/README.md b/packages/tools/README.md index 725b0fe57e..befe427be0 100644 --- a/packages/tools/README.md +++ b/packages/tools/README.md @@ -14,3 +14,13 @@ Run with `tool `: platform data directory. - brand-vite: Apply Vite+ branding patches to the synced vite source (also runs at the end of sync-remote) - local-npm-registry: Serve locally packed checkout packages behind a real registry HTTP interface for snapshot tests, ecosystem e2e, and local `vp migrate`/`vp create` iteration + +## Local npm registry + +See the [contributing guide](../../CONTRIBUTING.md#test-vp-migrate--vp-create-through-a-local-npm-registry) for local build and usage commands. + +[`src/local-npm-registry.ts`](src/local-npm-registry.ts) packs the checkout, serves its tarballs through a registry HTTP interface, and proxies other packages upstream. + +- Served versions use an old publish time so package-manager minimum-release-age checks allow local builds immediately. +- Wrapped commands use temporary Yarn Berry and bun caches to avoid reusing stale local builds with the same package version. +- The server also backs [PTY snapshot cases](../../crates/vp_cli_snapshots/tests/cli_snapshots/README.md) with `local-registry = true` and [ecosystem e2e tests](../../ecosystem-ci/patch-project.ts).