[English](CONTRIBUTING_EN.md) · 中文
# 贡献指南（dsh-tui-vscode）
感谢你考虑为 dsh-tui-vscode 做贡献！以下是参与开发的流程与约定，**均由 CI 服务端强制**（贡献者无法通过修改仓库文件削弱检查）。
## 开发环境
- Node.js 24（开发默认；CI 测试矩阵为 Node 22/24）；包管理用 **npm**（`npm ci` 安装）。
- e2e 的"真实 dsh-tui 恢复测试"需要本机全局安装 `dsh` CLI 与 `dsh-tui`（无则自动跳过该用例）。
- 开发时建议安装本地钩子：`node scripts/install-commit-hook.mjs`（拦截提交消息格式等快速可逆问题）。
## 运行测试
```bash
npm run typecheck # tsc --noEmit
npm test # 编译 + 数据层单元测试（node:test）
npm run test:e2e # 真实扩展宿主测试（@vscode/test-electron；Linux 用 xvfb-run -a）
npm run package # 编译 + 生成 .vsix
```
## 变更流程
1. 从 `main` 创建功能分支，**分支前缀**必须是 `feat/` `fix/` `docs/` `chore/` `hotfix/` `ci/` `test/`（CI pr-policy 强制，`feature/` 会被拒绝）。
2. 提交消息遵循 **Conventional Commits**：`fix: ...` / `feat: ...` / `docs: ...` / `ci: ...`（CI 逐个提交审计）。
3. 发起 Pull Request：**标题同样遵循 Conventional Commits**；正文使用 `.github/PULL_REQUEST_TEMPLATE.md` 的五段结构（摘要 / 改动范围 / 验证 / 自查 / 审查注意点），**删除或省略任何段落或勾选项即失败**。
4. 行为变化**必须记入 `CHANGELOG.md` 的 Unreleased 段**（中英同步）；勾选"行为变化已记入 CHANGELOG"时，分支必须相对基线有实际的 CHANGELOG diff（防虚假自查）。
5. 文档改动必须**中英双语同步**（CI 强制行数差 ≤ 10，CoC 除外）。
## 代码约定
- 与 VS Code API 无关的纯逻辑放 `src/session.ts` / `src/sessions.ts`，**不带 `vscode` import**，便于单元测试。
- **断言平台无关**：路径分隔符用 `join()` 构造期望值；CI 在 Linux 与 Windows 双平台运行，Windows 风格硬编码断言会在 Linux 失败（已有前车之鉴）。
- 只暂存显式路径，不用 `git add -A` 大杂烩；提交前自查 `git diff --check`。
- 不提交凭据、密钥、个人路径或本地产物（`.vsix`、`.e2e-workspace` 等已在 `.gitignore`）。
## 提交规范
- 每个变更单独提交，勿混入无关改动。
- 提交信息：`(): `，如 `fix(sessions): projectNameOf 双分隔符解析`。
## 提交流程
1. Fork 本仓库，从 `main` 建分支（`git checkout -b fix/your-change`）。
2. 提交改动（`git commit -m 'fix: describe the change'`）。
3. 推送到分支（`git push origin fix/your-change`）。
4. 发起 Pull Request（标题同样遵循 Conventional Commits 前缀）。
本地预检：安装 pre-commit 钩子（`node scripts/install-commit-hook.mjs`），CI 服务端兜底其余检查。
## 发布 / Publishing
- 当前发布方式：`npm run package` 生成 vsix → https://marketplace.visualstudio.com/manage 网页上传（官方"手动发布"路径，无需 PAT）。
- 版本流程：改 `package.json` version → 同步 README 徽章与 CHANGELOG（release-consistency CI 强制五处一致）→ 打 `v*` tag → 网页上传新版本。
- 注意：Azure DevOps 全局 PAT 将于 2026-12-01 退休；届时如需 CLI/CI 自动化发布，改用 Entra ID（`vsce publish --azure-credential`，vsce ≥ 2.26.1）。
- 切勿使用"移除（Remove）"：扩展名移除后**永久保留不可复用**；下架请用"Unpublish"。
### 更新发布（新版本）清单 / Publishing an update (new version)
1. **新版本号强制**：Marketplace 的版本**不可覆盖、删除后不可复用**——每次发布必须用**递增的新版本号**（同版本号网页上传会被拒绝）。
2. **CHANGELOG**：把 `Unreleased` 内容转为新版本段 `## [x.y.z] - 日期`，段内**链接本批已合并的 PR**（release-consistency CI 强制每版本段含 PR 链接或 direct-push 标记）。
3. **五处一致**：`package.json` version = README 徽章（中/英）= CHANGELOG 首个版本段（中/英），CI 验证。
4. `npm run package` → 在 manage 页面**上传新 vsix**（自动成为该扩展的新版本，保留安装统计）。
5. 打 `v*` tag + 创建 GitHub Release（附 vsix 附件），与商店版本保持一致。
6. 发布后：`Unreleased` 重置为空段；如版本同步中改了 README/CHANGELOG，随 tag 一起推送。