Skip to content

Conversation

@jamiesun
Copy link
Contributor

📋 变更说明

问题

项目文档比代码还多,造成严重的上下文负担。很多文档只是重复了代码和配置文件中已有的信息,维护成本高且容易过时。

解决方案

删除 10 个冗余文档,共减少 25,000+ 行,只保留核心必需文档。


🗑️ 删除的文档

根目录 (5个文件)

  • MAKEFILE_GUIDE.md - Makefile 本身已有清晰注释和 make help
  • SETUP_AUTO_FORMAT.md - 配置文件(.pre-commit-config.yamlpyproject.toml)本身就是文档
  • EXAMPLES.md (14,339 行!) - 超长示例文档,工具的 docstring 是更好的文档
  • COMPLETION_REPORT.md - 开发过程文档,Git 历史已经记录了所有改动
  • TASK.md - 任务计划,应该使用 GitHub Issues/Projects 管理

.github 目录 (5个文件)

  • WORKFLOWS.md - workflow 配置文件(.github/workflows/*.yml)本身就是文档
  • CODE_QUALITY.md - 工具配置文件本身就是文档
  • BRANCH_PROTECTION.md - GitHub 设置说明,一次性文档,用完即丢
  • CHECKLIST.md - 开发过程检查清单
  • SETUP_SUMMARY.md - 安装总结,一次性文档

文件重组

  • 📁 移动 verify_completion.pytest_scripts/verify_completion.py(更合理的位置)

✅ 保留的核心文档

根目录

  • README.md - 项目主文档(必需)
  • CONTRIBUTING.md - 贡献指南(开源项目必需)
  • LICENSE - 法律文件(必需)

.github 目录

  • .github/copilot-instructions.md - AI 编程指南(对 AI 辅助开发有实际价值)
  • .github/pull_request_template.md - GitHub PR 模板(GitHub 功能必需)
  • .github/ISSUE_TEMPLATE/*.md - GitHub Issue 模板(GitHub 功能必需)

💡 核心理念

代码和配置本身就是最好的文档

  • Makefile 有注释和 make help → 不需要 MAKEFILE_GUIDE.md
  • Workflow 文件有完整配置 → 不需要 WORKFLOWS.md
  • 工具有 docstring → 不需要超长的 EXAMPLES.md
  • Git 历史记录了一切 → 不需要 COMPLETION_REPORT.md
  • GitHub Issues 管理任务 → 不需要 TASK.md

好处:

  1. ✅ 减少维护负担(文档永远是最容易过时的)
  2. ✅ 降低上下文复杂度(开发者不用在海量文档中找信息)
  3. ✅ 单一信息源(代码即文档,避免不一致)
  4. ✅ 更容易导航(只看核心文档即可)

📊 统计

  • 删除文件数: 11 个(10 个文档 + 1 个移动)
  • 删除行数: ~25,000+ 行
  • 保留文档: 6 个核心文档
  • 代码行数: 约 2,000 行

清理后: 文档与代码比例从 12:1 降低到 ~1:1(合理)


✅ 检查清单

  • 删除所有冗余文档
  • 保留核心必需文档
  • 重组文件到合理位置
  • 提交信息清晰描述变更
  • 无破坏性更改(只删除文档,不影响代码功能)

wangjuntao added 2 commits October 27, 2025 21:05
删除根目录冗余文档:
- MAKEFILE_GUIDE.md (Makefile 本身已有清晰注释和 help)
- SETUP_AUTO_FORMAT.md (配置文件本身就是文档)
- EXAMPLES.md (14K+ 行,工具 docstring 是更好的文档)
- COMPLETION_REPORT.md (开发过程文档,Git 历史已记录)
- TASK.md (任务计划,应使用 GitHub Issues 管理)

删除 .github 冗余文档:
- WORKFLOWS.md (workflow 配置文件本身就是文档)
- CODE_QUALITY.md (工具配置文件本身就是文档)
- BRANCH_PROTECTION.md (GitHub 设置说明,一次性文档)
- CHECKLIST.md (开发过程文档)
- SETUP_SUMMARY.md (安装总结,一次性文档)

文件重组:
- 移动 verify_completion.py 到 test_scripts/ 目录

保留核心文档:
- README.md (项目主文档)
- CONTRIBUTING.md (贡献指南)
- LICENSE (法律文件)
- .github/copilot-instructions.md (AI 编程指南)
- .github/pull_request_template.md (GitHub 模板)
- .github/ISSUE_TEMPLATE/*.md (GitHub Issue 模板)

理由: 代码和配置本身就是最好的文档,过多的额外文档反而增加维护负担和上下文复杂度。
- 自动分析 Git 提交历史判断版本类型
- 支持自动计算版本号(major/minor/patch)
- 支持三种发布模式:
  1. /release - 自动判断版本号(推荐)
  2. /release x.y.z - 指定版本号
  3. /release --auto - 完全自动化无确认
@jamiesun jamiesun marked this pull request as draft October 27, 2025 13:35
@jamiesun jamiesun marked this pull request as ready for review October 27, 2025 13:41
@jamiesun jamiesun merged commit 91f93b0 into main Oct 27, 2025
7 checks passed
@jamiesun jamiesun deleted the chore/cleanup-redundant-docs branch October 27, 2025 15:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants