Contributing

本仓库保存计算机协会的公开文档站点。提交内容时，请优先保持文档可读、路径稳定、导航可发现，并让 CI 能验证变更。

本地准备

1. 安装 Node.js 22。

2. 安装 pnpm 9。

3. 安装依赖：

   pnpm install

4. 启动本地预览：

   pnpm docs:dev

文档放置规则

教程

教程面向读者学习某个工具、服务或工作流。新增教程放在 tutorial/<year>/ 下，文件名优先使用小写英文短横线，例如 tutorial/2025/example-guide.md。

新增或调整公开教程后，同步更新 tutorial/sidebar.ts，让页面能从站点导航进入。教程需要有清晰的一级标题，并在适合时保留“维护信息”块。

流程

流程面向协会内部事务办理，例如借教室、报销、活动组织。新增流程放在 process/<year>/ 下。

新增或调整公开流程后，同步更新 process/sidebar.ts。流程文档应写清适用场景、前置材料、步骤、提交对象和常见问题。

维修

维修文档面向维修队和维修日场景。常驻维修说明放在 repair/ 下，相关图片或附件放在 repair/assets/ 下。

当前维修栏目导航在 repair/sidebar.ts 中维护；新增公开维修页面时，需要同步更新对应 sidebar 配置。

存档

存档保存历史会议纪要、年度材料和旧手册。按年份归档的内容放在 archived/<year>/ 下，长期手册放在 archived/manual/ 下。

存档 sidebar 会扫描 Markdown 文件并使用第一个一级标题作为显示名。新增存档页面通常不需要手工改导航；如果新增了具有特殊含义的子目录，需要确认 archived/sidebar.ts 是否需要显示名映射。

资产与附件

图片、表格、模板和压缩包应放在对应栏目的 assets/ 目录下，并使用相对路径引用。模板类资产需要在文档中说明用途、适用流程和更新时间。

如果新增资产与已有文件用途相同，优先替换或复用已有文件，不要新增重复副本。确实需要保留多个版本时，请在文件名或说明中标明版本差异。

导航与链接

新增公开页面必须能从对应栏目导航进入，除非它只是被其他页面引用的附件说明或临时草稿。内部链接优先使用站内相对路径或以 / 开头的站内路径。

重命名或移动页面时，请同步更新所有引用、sidebar 和相关说明。避免随意改变已经公开使用的 URL。

提交前验证

提交 PR 前至少运行：

pnpm run ci:lint
pnpm test -- --run
pnpm docs:build

如果只改了非站点说明文件，也建议运行 pnpm run ci:lint 和 pnpm docs:build，确认构建环境仍然健康。

PR 要求

PR 描述需要说明：

• 这次修改影响哪些栏目或文档。
• 是否新增、移动、删除页面。
• 是否更新了 sidebar、链接或资产引用。
• 已运行哪些验证命令。
• 还有哪些已知后续工作没有包含在本 PR 中。

PR 应保持范围集中。内容更新、导航重构、CI 规则和资产治理尽量拆成独立 PR，方便审阅和回滚。