docs(release): add release guide and RFC

ubugeeei · ubugeeei · commit 8a99d470d2e4 · 2026-04-09T13:14:05.000+09:00
diff --git a/README.md b/README.md
@@ -19,16 +19,12 @@ Vite+ is the unified entry point for local web development. It combines [Vite](h
 - **`vp build`:** Build applications for production with Vite + Rolldown
 - **`vp run`:** Execute monorepo tasks with caching and dependency-aware scheduling
 - **`vp pack`:** Build libraries for npm publishing or standalone app binaries
-- **`vp release`:** Version and publish workspace packages with native publish preflight during `--dry-run`, release checks before real publishes by default, retry-friendly exact version overrides via `--version`, optional changelog generation via `--changelog`, prerelease channels like `--preid alpha` / `beta` / `rc`, and `--projects` order respected between independent packages
+- **`vp release`:** Version and publish workspace packages
 - **`vp create` / `vp migrate`:** Scaffold new projects and migrate existing ones
 
 All of this is configured from your project root and works across Vite's framework ecosystem.
 Vite+ is fully open-source under the MIT license.
 
-`vp release` detects likely checks from `build`, `pack`, `prepack`, `prepublishOnly`, `prepare`, and `vitePlus.release.checkScripts`. Real releases run those checks before publishing unless you pass `--no-run-checks`; dry-runs stay lightweight by default and can opt in with `--run-checks`. `--dry-run` also runs the native publisher in dry-run mode from a temporary release manifest state when the git worktree is clean. Use `--yes` for CI or other non-interactive runs, and `--version <x.y.z>` when retrying a partial publish at an exact version.
-
-Real releases always create git tags after a successful publish. When every released package shares the same target version, `vp release` also creates a repository-level `v<version>` tag so GitHub Releases and repo-wide release notes can follow the same watermark. Preview-only flags such as `--skip-publish` and `--no-git-tag` are therefore limited to `--dry-run`.
-
 ## Getting Started
 
 Install Vite+ globally as `vp`:
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -56,6 +56,7 @@ const guideSidebar = [
     items: [
       { text: 'Build', link: '/guide/build' },
       { text: 'Pack', link: '/guide/pack' },
+      { text: 'Release', link: '/guide/release' },
     ],
   },
   {
diff --git a/docs/guide/index.md b/docs/guide/index.md
@@ -103,6 +103,7 @@ Vite+ can handle the entire local frontend development cycle from starting a pro
 
 - [`vp build`](/guide/build) builds apps.
 - [`vp pack`](/guide/pack) builds libraries or standalone artifacts.
+- [`vp release`](/guide/release) versions and publishes workspace packages.
 - [`vp preview`](/guide/build) previews the production build locally.
 
 ### Manage Dependencies
diff --git a/docs/guide/release.md b/docs/guide/release.md
@@ -0,0 +1,134 @@
+# Release
+
+`vp release` versions and publishes workspace packages from conventional commits and git tags. The intended workflow is: preview locally with `--dry-run`, then run the real publish from trusted-publishing CI.
+
+## Overview
+
+`vp release` is built for monorepos with multiple publishable packages:
+
+- It detects releasable changes from conventional commits.
+- It computes the next version for each selected package.
+- It updates internal dependency ranges before publish.
+- It runs publish preflight and release checks before a real release.
+- It creates package tags like `release/pkg-name/v1.2.3`.
+
+When every released package lands on the same version, `vp release` also creates a repository tag like `v1.2.3`.
+
+## Recommended Workflow
+
+### 1. Preview Locally
+
+Use a local dry-run to inspect the release plan without mutating files:
+
+```bash
+vp release --dry-run
+```
+
+This shows:
+
+- planned package versions
+- detected release checks
+- trusted publishing readiness
+- publish command shape
+- git tags that would be created
+
+If you want the dry-run to execute detected checks too:
+
+```bash
+vp release --dry-run --run-checks
+```
+
+### 2. Publish From CI
+
+Real publishes are designed for trusted-publishing CI:
+
+```bash
+vp release --yes
+```
+
+Use `--yes` in CI to skip the interactive confirmation prompt.
+
+## Common Flags
+
+### Limit the release to specific packages
+
+```bash
+vp release --projects vite-plus,@voidzero-dev/vite-plus-core --dry-run
+```
+
+When multiple package patterns are provided, their order is used as a tie-breaker for otherwise independent packages.
+
+### Publish a prerelease
+
+```bash
+vp release --preid alpha --yes
+vp release --preid beta --yes
+vp release --preid rc --yes
+```
+
+Custom prerelease channels are also supported:
+
+```bash
+vp release --preid canary --yes
+```
+
+### Retry a partial publish with an exact version
+
+If a publish stops partway through, rerun the remaining packages with an exact version:
+
+```bash
+vp release --projects vite-plus --version 1.2.3 --yes
+```
+
+## Release Checks
+
+`vp release` looks for likely pre-release checks from:
+
+- `build`
+- `pack`
+- `prepack`
+- `prepublishOnly`
+- `prepare`
+- `vitePlus.release.checkScripts`
+
+Real releases run these checks by default. Dry-runs stay lightweight by default, but can opt in with `--run-checks`.
+
+## First Release
+
+For the first publish of a workspace or package set:
+
+```bash
+vp release --first-release --dry-run
+```
+
+The first-release guidance explains:
+
+- the publish workflow file expected by trusted publishing
+- required `repository` metadata
+- `publishConfig.access = "public"` for scoped public packages
+- the commands to run for dry-run and real publish
+
+## Git Tags
+
+`vp release` uses git tags as the durable release watermark:
+
+- package tags: `release/<package>/v<version>`
+- repository tag: `v<version>` when all selected packages share the same target version
+
+Real releases always create git tags after a successful publish. Preview-only shortcuts such as `--skip-publish` and `--no-git-tag` are restricted to `--dry-run`.
+
+## Configuration
+
+Release-specific check scripts can be added in `package.json`:
+
+```json
+{
+  "vitePlus": {
+    "release": {
+      "checkScripts": ["release:verify"]
+    }
+  }
+}
+```
+
+Use this when your publish validation does not fit the default script names.
diff --git a/rfcs/release-command.md b/rfcs/release-command.md
@@ -0,0 +1,197 @@
+# RFC: `vp release` Command
+
+## Summary
+
+`vp release` versions and publishes workspace packages from conventional commits, package metadata, and git release tags. The user experience is split into two phases:
+
+1. local `--dry-run` planning and verification
+2. real publish from trusted-publishing CI
+
+## Motivation
+
+Publishing a multi-package workspace usually requires stitching together several fragile steps:
+
+```bash
+# Typical ad-hoc release flow
+changeset version
+pnpm -r build
+pnpm -r publish
+git tag ...
+git push ...
+```
+
+Pain points:
+
+- no single release boundary for versioning, publish, and tags
+- retries are hard after a partial publish
+- internal dependency ranges can drift
+- local dry-runs often fail to resemble the real publish path
+- CI workflows duplicate release logic instead of reusing the CLI
+
+`vp release` aims to make publishing feel like the rest of Vite+: one command, one predictable flow, one documented operator experience.
+
+## Goals
+
+- Make release planning visible before any mutation happens.
+- Derive versions from conventional commits and existing tags.
+- Support monorepo publishing with dependency-aware ordering.
+- Keep local dry-runs safe and informative.
+- Make partial publish retries explicit and recoverable.
+- Default real publishes to trusted-publishing CI.
+
+## Non-Goals
+
+- Replacing npm dist-tag semantics with a custom channel system
+- Managing post-release announcement workflows
+- Replacing package-manager-native publish implementations
+
+## User Experience
+
+### Local Preview
+
+Operators should be able to preview a release from a clean local checkout:
+
+```bash
+vp release --dry-run
+```
+
+The preview should show:
+
+- packages that will be released
+- current and next versions
+- detected release checks
+- trusted publishing readiness
+- publish commands that would run
+- tags that would be created
+
+### Real Release
+
+The real release is intended for CI:
+
+```bash
+vp release --yes
+```
+
+The CLI should:
+
+1. validate release options and trusted-publishing posture
+2. compute the release plan
+3. run release checks by default
+4. run native publish preflight
+5. publish packages
+6. persist final manifests and changelogs
+7. create the release commit and tags
+
+## Release Boundary
+
+`vp release` uses git tags as the durable watermark for future runs.
+
+### Package Tags
+
+Each published package gets a tag:
+
+```text
+release/<package>/v<version>
+```
+
+Examples:
+
+```text
+release/vite-plus/v1.2.3
+release/voidzero-dev/vite-plus-core/v1.2.3
+```
+
+### Repository Tag
+
+When all selected packages land on the same version, `vp release` also creates:
+
+```text
+v<version>
+```
+
+This repository tag is used for GitHub Releases and repo-wide release notes.
+
+## Version Sources
+
+### Conventional Commits
+
+Version bumps come from conventional commits:
+
+- `feat` -> minor
+- `fix`, `perf`, `refactor`, `revert` -> patch
+- breaking changes -> major
+
+For `0.y.z`, breaking changes are intentionally downgraded to the minor line.
+
+### Tag-Sourced Packages
+
+Some packages keep `"version": "0.0.0"` in source control and treat git tags as the real version history. `vp release` should support that workflow and still rewrite manifests correctly at publish time.
+
+## Prereleases and Retries
+
+### Prerelease Channels
+
+Standard prerelease channels:
+
+```bash
+vp release --preid alpha
+vp release --preid beta
+vp release --preid rc
+```
+
+Custom channels are also valid:
+
+```bash
+vp release --preid canary
+```
+
+Custom prerelease tags must round-trip through repository tags so retries and follow-up releases stay consistent.
+
+### Exact Version Retries
+
+If a publish succeeds for only part of the package set, operators should narrow the remaining packages and rerun with `--version`:
+
+```bash
+vp release --projects vite-plus --version 1.2.3 --yes
+```
+
+The CLI should infer the effective dist-tag from the exact target version when possible, instead of assuming `latest`.
+
+## Release Checks
+
+The default release checks should come from familiar script names:
+
+- `build`
+- `pack`
+- `prepack`
+- `prepublishOnly`
+- `prepare`
+- `vitePlus.release.checkScripts`
+
+Real releases run these checks by default. Dry-runs should remain lightweight unless `--run-checks` is requested.
+
+## First Release
+
+The first publish needs extra operator guidance:
+
+- required workflow permissions for trusted publishing
+- matching `repository` metadata
+- `publishConfig.access = "public"` for public scoped packages
+- recommended `vp release --first-release --dry-run` and CI commands
+
+The workflow template should be a starting point, not a hidden side effect of a dry-run.
+
+## Documentation Plan
+
+The public docs should describe how to use `vp release`, not just how it is implemented.
+
+This RFC pairs with:
+
+- `/guide/release` for operator-facing usage
+- a short README summary line instead of embedding the full release guide in the landing page
+
+## Open Questions
+
+- How much changelog generation should be configurable in the first public version?
+- Should the scaffolded publish workflow use floating major actions (`@v6`) or pinned SHAs?
+- Should the repository tag be optional for lockstep releases, or always created?

Original file line number	Diff line number	Diff line change
`@@ -56,6 +56,7 @@ const guideSidebar = [`
`56`	`56`	`items: [`
`57`	`57`	`{ text: 'Build', link: '/guide/build' },`
`58`	`58`	`{ text: 'Pack', link: '/guide/pack' },`
	`59`	`+ { text: 'Release', link: '/guide/release' },`
`59`	`60`	`],`
`60`	`61`	`},`
`61`	`62`	`{`