docs: add release management guide - #1932
Merged
Merged
Conversation
Deploying rslib with
|
| Latest commit: |
075a3ff
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://c41577d3.rslib.pages.dev |
| Branch Preview URL: | https://docs-release-management.rslib.pages.dev |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b9314fb455
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Critical workflow security and prerelease-tagging issues, plus validation gaps, remain unresolved.
Get a fresh assessment by requesting another Copilot review.
Pull request overview
Adds bilingual Rslib release-management documentation covering versioning, validation, publishing, and GitHub Actions workflows.
Changes:
- Added English and Chinese release guides.
- Documented changelogs, prereleases, artifact validation, and staged publishing.
- Added both guides to advanced navigation indexes.
File summaries
| File | Description |
|---|---|
website/docs/en/guide/advanced/release-management.mdx |
English release guide |
website/docs/zh/guide/advanced/release-management.mdx |
Chinese release guide |
website/docs/en/guide/advanced/_meta.json |
Adds English navigation entry |
website/docs/zh/guide/advanced/_meta.json |
Adds Chinese navigation entry |
Review details
Suppressed comments (10)
website/docs/en/guide/advanced/release-management.mdx:370
- Pin this action to an immutable commit SHA, and apply the same to
setup-nodeandpnpm/action-setupin this snippet. This copy-paste release workflow grantsid-token: write; mutable@v7/@v6tags let a retargeted action run unreviewed code with publishing credentials. The repository's release workflow uses SHA-pinned refs (.github/workflows/release.yml:36-48).
uses: actions/checkout@v7
website/docs/en/guide/advanced/release-management.mdx:44
- Link each option in this release-critical table to its canonical Node.js or npm documentation instead of presenting unlinked names. The page introduces
exports,types,files,engines.node,publishConfig, and dependency fields as configuration APIs, but only the Rslib dependency behavior has a link, so readers cannot verify the rest.
| `exports`, `types` | Point the exports and type declarations to the actual build artifacts generated by Rslib. |
| `files` | Explicitly list the files to publish to avoid accidentally publishing tests, configuration, and other unrelated content. |
| `engines.node` | Declare the minimum supported Node.js version. |
| `publishConfig` | Scoped packages can set `access: "public"` for public publishing. This field can also override the registry used when publishing. |
| `dependencies`, `optionalDependencies`, `peerDependencies`, `devDependencies` | Rslib applies default external rules to third-party dependencies based on these fields. Declare dependencies according to their actual purpose; see [Default handling of third-party dependencies](/guide/advanced/third-party-deps#default-handling-of-third-party-dependencies) for details. |
website/docs/en/guide/advanced/release-management.mdx:238
- Link the
@rslib/corepackage used by this copy-paste example to its canonical package page. The surrounding plugin names are linked, but this package is not, which leaves one of the guide's required package references unlinked.
The following configuration enables the checks with the `CI` environment variable set by most CI platforms, avoiding an impact on local build workflows. The checks run automatically when packages are built during the release workflow:
website/docs/en/guide/advanced/release-management.mdx:238
- This build-artifact-check section duplicates the explanation and full configuration already in
website/docs/en/blog/v1-0.mdx:244-264(and the Chinese counterpart). Keep one canonical explanation—prefer this release guide—and link to it from the blog so plugin changes do not require synchronized edits in two places.
You can also check the package structure, exports, and type declarations to ensure that the final npm package can be resolved and installed correctly. Rslib supports the following Rsbuild plugins for these checks:
- [rsbuild-plugin-publint](https://github.com/rstackjs/rsbuild-plugin-publint): Checks common issues in `package.json`, package structure, and exports.
- [rsbuild-plugin-arethetypeswrong](https://github.com/rstackjs/rsbuild-plugin-arethetypeswrong): Checks whether type declarations work correctly with different module resolution strategies.
Install the plugins first, then add them to the `plugins` configuration. The plugins check release artifacts after the build completes.
import { PackageManagerTabs } from '@theme';
<PackageManagerTabs command="add rsbuild-plugin-publint rsbuild-plugin-arethetypeswrong -D" />
The following configuration enables the checks with the `CI` environment variable set by most CI platforms, avoiding an impact on local build workflows. The checks run automatically when packages are built during the release workflow:
website/docs/en/guide/advanced/release-management.mdx:104
- Limit this section to pnpm workspaces or document a separate standalone-package flow:
pnpm changeis workspace-only, so this command fails in the single-package repository described later. The page currently presents it as the common first step for both release shapes.
After completing changes that need to be released, run [pnpm change](https://pnpm.io/cli/change) to record the affected packages, version bump level, and change summary:
```bash
pnpm change
website/docs/zh/guide/advanced/release-management.mdx:370
- Pin this action to an immutable commit SHA, and apply the same to
setup-nodeandpnpm/action-setupin this snippet. This copy-paste release workflow grantsid-token: write; mutable@v7/@v6tags let a retargeted action run unreviewed code with publishing credentials. The repository's release workflow uses SHA-pinned refs (.github/workflows/release.yml:36-48).
uses: actions/checkout@v7
website/docs/zh/guide/advanced/release-management.mdx:44
- Link each option in this release-critical table to its canonical Node.js or npm documentation instead of presenting unlinked names. The page introduces
exports,types,files,engines.node,publishConfig, and dependency fields as configuration APIs, but only the Rslib dependency behavior has a link, so readers cannot verify the rest.
| `exports`、`types` | 导出配置和类型声明应指向 Rslib 的实际构建产物。 |
| `files` | 明确需要发布的文件，避免将测试、配置等内容意外发布。 |
| `engines.node` | 声明包最低支持的 Node.js 版本。 |
| `publishConfig` | 带 scope 的包可以设置 `access: "public"` 公开发布，还可以通过该字段覆盖发布时使用的 registry 等配置。 |
| `dependencies`、`optionalDependencies`、`peerDependencies` 和 `devDependencies` | Rslib 会根据这些字段对三方依赖应用默认的 external 规则，因此需要按照依赖的实际用途正确声明，具体规则可以参考 [三方依赖的默认处理](/guide/advanced/third-party-deps#三方依赖的默认处理)。 |
website/docs/zh/guide/advanced/release-management.mdx:238
- Link the
@rslib/corepackage used by this copy-paste example to its canonical package page. The surrounding plugin names are linked, but this package is not, which leaves one of the guide's required package references unlinked.
下面的配置通过大多数 CI 平台默认设置的 `CI` 环境变量启用检查，避免影响本地构建流程。在发布流程中构建包时会自动执行这些检查：
website/docs/zh/guide/advanced/release-management.mdx:238
- 此产物检查部分重复了
website/docs/zh/blog/v1-0.mdx:244-264（以及英文对应页面）中已有的说明和完整配置。请保留一个权威位置（建议以本发布指南为准），并让博客链接到这里，避免插件变更时需要同步维护两处内容。
我们还可以进一步对包结构、导出配置和类型声明进行检查，确保最终的 npm 包能够被正确解析和安装。Rslib 支持使用以下 Rsbuild 插件完成检查：
- [rsbuild-plugin-publint](https://github.com/rstackjs/rsbuild-plugin-publint)：检查 `package.json`、包结构和导出配置等常见问题。
- [rsbuild-plugin-arethetypeswrong](https://github.com/rstackjs/rsbuild-plugin-arethetypeswrong)：检查类型声明能否在不同的模块解析方式下正确使用。
使用时，先安装插件，再将它们添加到 `plugins` 配置中。插件会在构建完成后检查发布产物。
import { PackageManagerTabs } from '@theme';
<PackageManagerTabs command="add rsbuild-plugin-publint rsbuild-plugin-arethetypeswrong -D" />
下面的配置通过大多数 CI 平台默认设置的 `CI` 环境变量启用检查，避免影响本地构建流程。在发布流程中构建包时会自动执行这些检查：
website/docs/zh/guide/advanced/release-management.mdx:104
- 将本节限制为 pnpm workspace，或补充独立单包项目的流程：
pnpm change只支持 workspace，因此在后文所述的单包仓库中执行会失败。目前页面把它作为两种发布方式的通用第一步。
完成需要发布的改动后，可以运行 [pnpm change](https://pnpm.io/cli/change) 记录受影响的包、版本变更级别和变更摘要：
```bash
pnpm change
- Files reviewed: 4/4 changed files
- Comments generated: 6
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
Document a consistent pnpm-based release process for Rslib npm packages in both Chinese and English, including version updates, artifact validation, publishing options, and GitHub Actions workflows.
Changes