From c8c2ee060900c0e5b53d5cb7ae272c4b714d61bb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carbon=20=E7=A2=B3=E8=8B=AF?= <carbon1024@foxmail.com>
Date: Sat, 21 Feb 2026 12:09:02 +0800
Subject: [PATCH] docs: add CHANGELOG.md and update README with installation
 troubleshooting and changelog reference

---
 .github/workflows/Release.yml | 27 +++++++++++++--------------
 CHANGELOG.md                  | 28 ++++++++++++++++++++++++++++
 CONTRIBUTING-CN.md            |  6 ++++++
 CONTRIBUTING.md               |  6 ++++++
 README.md                     | 14 ++++++++++++++
 README.zh-CN.md               | 14 ++++++++++++++
 6 files changed, 81 insertions(+), 14 deletions(-)
 create mode 100644 CHANGELOG.md

diff --git a/.github/workflows/Release.yml b/.github/workflows/Release.yml
index e88cfe1..d4431df 100644
--- a/.github/workflows/Release.yml
+++ b/.github/workflows/Release.yml
@@ -126,20 +126,6 @@ jobs:
       - name: List packages
         run: ls -R ./npm
         shell: bash
-      - name: Add optionalDependencies for publish
-        run: |
-          node -e "
-          const fs = require('fs');
-          const p = JSON.parse(fs.readFileSync('package.json', 'utf8'));
-          const v = p.version;
-          p.optionalDependencies = {
-            '@rush-fs/rush-fs-win32-x64-msvc': v,
-            '@rush-fs/rush-fs-darwin-x64': v,
-            '@rush-fs/rush-fs-linux-x64-gnu': v,
-            '@rush-fs/rush-fs-darwin-arm64': v
-          };
-          fs.writeFileSync('package.json', JSON.stringify(p, null, 2));
-          "
       - name: Update platform package names to use scope (@rush-fs/xxx)
         run: |
           for dir in npm/*/; do
@@ -193,6 +179,19 @@ jobs:
           # 主包 index.js 里 require 的是 rush-fs-xxx，改为 @rush-fs/rush-fs-xxx 才能找到已发布的平台包
           sed -i "s/require('rush-fs-/require('@rush-fs\/rush-fs-/g" index.js
           sed -i 's/require(\"rush-fs-/require(\"@rush-fs\/rush-fs-/g' index.js
+          # optionalDependencies 必须在 prepublish 之后注入，否则会被 prepublish 覆盖，导致用户 pnpm i rush-fs 时不会自动安装平台包
+          node -e "
+          const fs = require('fs');
+          const p = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+          const v = p.version;
+          p.optionalDependencies = {
+            '@rush-fs/rush-fs-win32-x64-msvc': v,
+            '@rush-fs/rush-fs-darwin-x64': v,
+            '@rush-fs/rush-fs-linux-x64-gnu': v,
+            '@rush-fs/rush-fs-darwin-arm64': v
+          };
+          fs.writeFileSync('package.json', JSON.stringify(p, null, 2));
+          "
           npm publish --access public
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..3dde315
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to Rush-FS are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+- (Add new changes here before each release.)
+
+## [0.0.4] - (release date TBD)
+
+### Fixed
+
+- **Publish:** `optionalDependencies` are now injected **after** `napi prepublish` in the Release workflow, so the published npm package correctly lists platform packages. Installing `rush-fs` will again auto-install the native binding for your OS/arch (e.g. `@rush-fs/rush-fs-darwin-arm64`). If you are on an older version and see "Cannot find native binding", see [README#Installation](./README.md#installation) for a manual fix.
+
+### Added
+
+- **Docs:** Nextra-based documentation site under `docs/` with i18n (EN / 中文), guide, API reference, and benchmarks.
+- **README:** Installation troubleshooting: how to reinstall or manually add the platform package when the native binding is missing.
+
+## [0.0.3] - (historical)
+
+- Earlier releases; see [GitHub Releases](https://github.com/CoderSerio/rush-fs/releases) for tags and assets.
+
+---
+
+[Unreleased]: https://github.com/CoderSerio/rush-fs/compare/v0.0.4...HEAD
+[0.0.4]: https://github.com/CoderSerio/rush-fs/compare/v0.0.3...v0.0.4
+[0.0.3]: https://github.com/CoderSerio/rush-fs/releases/tag/v0.0.3
diff --git a/CONTRIBUTING-CN.md b/CONTRIBUTING-CN.md
index cebff5b..31f31bc 100644
--- a/CONTRIBUTING-CN.md
+++ b/CONTRIBUTING-CN.md
@@ -506,3 +506,9 @@ GitHub Actions 会在 push / PR 时自动执行：
 4. **Publish** — 版本 tag 触发自动发布到 npm
 
 本地开发只需关注 `pnpm build:debug` + `pnpm test`，CI 会处理跨平台验证。
+
+### 发布前/后检查（维护者）
+
+在打新版本（例如运行 Release 工作流前后）：
+
+- 更新 [CHANGELOG.md](CHANGELOG.md)：将 **\[Unreleased]** 下的条目移到新的 `## [x.y.z] - YYYY-MM-DD` 小节，并在文末补充该版本的链接（`[x.y.z]: https://github.com/CoderSerio/rush-fs/compare/vA.B.C...vx.y.z`）。
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5ac0d17..6f21f37 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -508,3 +508,9 @@ GitHub Actions on push/PR:
 4. **Publish** — Triggered by version tags; see [Release workflow](.github/workflows/Release.yml)
 
 For local development, `pnpm build:debug` and `pnpm test` are enough; CI handles cross-platform checks.
+
+### Release checklist (maintainers)
+
+When cutting a new version (e.g. before or after running the Release workflow):
+
+- Update [CHANGELOG.md](CHANGELOG.md): move items from **\[Unreleased]** into a new `## [x.y.z] - YYYY-MM-DD` section, and add the version link at the bottom (`[x.y.z]: https://github.com/CoderSerio/rush-fs/compare/vA.B.C...vx.y.z`).
diff --git a/README.md b/README.md
index c9a54e3..787333d 100644
--- a/README.md
+++ b/README.md
@@ -25,6 +25,15 @@ npm install rush-fs
 pnpm add rush-fs
 ```
 
+When you install `rush-fs`, the package manager should automatically install the **platform-specific native binding** for your OS/arch via `optionalDependencies` (e.g. `@rush-fs/rush-fs-darwin-arm64` on macOS ARM). If the native binding is missing and you see "Cannot find native binding", try:
+
+1. Remove `node_modules` and the lockfile (`package-lock.json` or `pnpm-lock.yaml`), then run `pnpm install` (or `npm i`) again.
+2. Or install the platform package explicitly:  
+   **macOS ARM:** `pnpm add @rush-fs/rush-fs-darwin-arm64`  
+   **macOS x64:** `pnpm add @rush-fs/rush-fs-darwin-x64`  
+   **Windows x64:** `pnpm add @rush-fs/rush-fs-win32-x64-msvc`  
+   **Linux x64 (glibc):** `pnpm add @rush-fs/rush-fs-linux-x64-gnu`
+
 ## Usage
 
 ```ts
@@ -466,6 +475,10 @@ We are rewriting `fs` APIs one by one.
 
 - **Status**: ❌
 
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for a summary of changes in each version. Release tags are listed in [GitHub Releases](https://github.com/CoderSerio/rush-fs/releases).
+
 ## Contributing
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full development guide: environment setup, Node.js reference, Rust implementation, testing, and benchmarking.
@@ -476,6 +489,7 @@ Releases are handled by the [Release workflow](.github/workflows/Release.yml): i
 
 1. **Secrets:** In the repo **Settings → Secrets and variables → Actions**, add **NPM_TOKEN** (npm Classic or Automation token with Publish permission).
 2. **Release:** Either run **Actions → Release → Run workflow** (uses the current `package.json` version on `main`), or bump version in `package.json` and `Cargo.toml`, push to `main`, then create and push a tag: `git tag v<version> && git push origin v<version>`.
+3. **Changelog:** Update [CHANGELOG.md](./CHANGELOG.md) before or right after the release (move entries from `[Unreleased]` to a new version heading and add the compare link).
 
 The workflow injects `optionalDependencies` and publishes all packages; no need to edit `package.json` manually for release.
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 8959566..9d0925a 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -24,6 +24,15 @@ npm install rush-fs
 pnpm add rush-fs
 ```
 
+安装 `rush-fs` 时，包管理器会通过 `optionalDependencies` 自动安装**当前平台**的本地绑定（例如 macOS ARM 上的 `@rush-fs/rush-fs-darwin-arm64`）。若未安装或出现「Cannot find native binding」：
+
+1. 删除 `node_modules` 和锁文件（`package-lock.json` 或 `pnpm-lock.yaml`）后重新执行 `pnpm install`（或 `npm i`）。
+2. 或手动安装对应平台包：  
+   **macOS ARM：** `pnpm add @rush-fs/rush-fs-darwin-arm64`  
+   **macOS x64：** `pnpm add @rush-fs/rush-fs-darwin-x64`  
+   **Windows x64：** `pnpm add @rush-fs/rush-fs-win32-x64-msvc`  
+   **Linux x64 (glibc)：** `pnpm add @rush-fs/rush-fs-linux-x64-gnu`
+
 ## 用法
 
 ```ts
@@ -465,6 +474,10 @@ graph TD
 
 - **状态**：❌
 
+## 更新日志
+
+各版本变更见 [CHANGELOG.md](./CHANGELOG.md)。发布 tag 列表见 [GitHub Releases](https://github.com/CoderSerio/rush-fs/releases)。
+
 ## 贡献
 
 参阅 [CONTRIBUTING-CN.md](./CONTRIBUTING-CN.md) 获取完整开发指南：环境搭建、参考 Node.js 源码、编写 Rust 实现、测试与性能基准。
@@ -475,6 +488,7 @@ graph TD
 
 1. **Secrets：** 在仓库 **Settings → Secrets and variables → Actions** 中添加 **NPM_TOKEN**（npm Classic 或 Automation token，需具备 Publish 权限）。
 2. **发布：** 在 **Actions → Release → Run workflow** 中手动运行（使用当前 `main` 上的 `package.json` 版本），或先更新 `package.json` 与 `Cargo.toml` 中的版本号并推送到 `main`，再创建并推送 tag：`git tag v<版本号> && git push origin v<版本号>`。
+3. **更新日志：** 发布前或发布后更新 [CHANGELOG.md](./CHANGELOG.md)（将 `[Unreleased]` 下的条目移到新版本标题下并补充 compare 链接）。
 
 工作流会自动注入 `optionalDependencies` 并发布所有包，无需在 `package.json` 中手动填写。