Contributing

设计文档编写与维护

存放范围

功能、优化、缺陷修复的背景、方案、取舍、验收记录及配套截图/附件统一保存在 Wiki。代码仓库保留 README、贡献与发布指南、现行配置说明、源代码、测试与测试必需的 fixtures。设计文档不再以完整副本回存代码仓库。

页面与附件命名

• 设计主页面使用 Issue-<编号>，例如 Issue-25；验收记录可拆为 Issue-25-Validation。URL 使用稳定的英文名称，页面正文标题写中文。
• 尚无 Issue 的新设计先创建 Issue；迁移的历史资料可用 Archive-<主题>，历史 PR 验收可用 PR-<编号>-Validation。
• 图片及附件放在 Wiki Git 仓库的 assets/issue-<编号>/ 中，文件名简短且可辨认。只保留有助于理解或复验的脱敏资料，大型安装包和构建产物使用 Release。
• 页面之间使用 [设计](Issue-25)；代码引用使用包含提交 SHA 的 GitHub URL。图片和 JSON 等附件使用 Wiki 原始文件 URL，例如 https://raw.githubusercontent.com/wiki/ShaoClean/remote-git/assets/issue-21/providers-wide.png。不得引用本机绝对路径或已删除的主仓库附件路径。

新建与更新流程

1. 复制设计模板，填写 Issue、状态、背景、目标、方案、验收标准和关联 PR。缺陷还需记录复现、根因和回归范围，未确认内容明确写“待确认”。
2. 将页面加入功能与优化或缺陷修复索引；必要时同时收录。
3. 在 Issue 正文的“设计文档（Wiki）”和 PR 模板的同名章节放入页面完整 URL；Wiki 页面反向链接到 Issue 和 PR。
4. 实现变更时同步更新设计和验收，记录代码提交、系统/架构、命令、实际结果、未验证项与日期。历史失败或未验证项不可直接改为通过；补充新记录说明验证依据。
5. 保存并检查索引、页面、图片和附件可访问。PR 审阅时提供 Wiki 页面的修订链接或 Wiki commit SHA，确保审阅者能定位当时版本。代码 PR 不会自动包含或回滚 Wiki 修改。

无维护权限的贡献者可先在 Issue / PR 中提供设计草案和附件，由维护者整理进入 Wiki，再补上双向链接。无需为小改动制造空白设计文档；没有独立设计时在 PR 中注明“不适用”及原因。

本地维护与回退

Wiki 与代码仓库是独立的 Git 仓库。可直接编辑页面；带附件的更新推荐在代码仓库之外克隆 Wiki：

git clone https://github.com/ShaoClean/remote-git.wiki.git remote-git-wiki
cd remote-git-wiki
git pull --ff-only
# 编辑 Issue-<编号>.md、索引及 assets/issue-<编号>/ 下的文件
git add Issue-25.md Feature-Designs.md
git commit -m "docs: update issue 25 design"
git push origin HEAD

命令中的文件名仅为示例，按实际改动添加页面、验收记录和附件。推送前检查 git diff --check 及链接/图片。需要回退时在 Wiki 历史页恢复对应修订，或用 git revert <commit> 再推送；不要重写协作者的历史。

从代码仓库删除旧文件只减少当前检出和未来增长，不会缩小已有 Git 历史。历史清理另行评估，不属于 Issue #25。