diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..3eb47f9ce --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,42 @@ +# Contributing + +This is a curated teaching repository. Each chapter (`sNN_topic/`) builds one idea on top of the last, and the code is deliberately minimal. The simplifications are intentional, so the lesson stays legible. Contributions are welcome when they serve that goal. + +## Before opening a PR + +1. Tie it to a specific issue. Say what is wrong and why your change is the right fix. One PR addresses one issue. +2. Keep teaching code minimal. Do not add production hardening, defensive parsing, error handling layers, abstractions, or a test framework unless the chapter is specifically about that. A simplification that looks like a bug is often deliberate, so ask in an issue first. +3. Keep the three languages in sync. Any change to a chapter's `code.py` or a README must be reflected in all three language READMEs in that chapter folder, with the code blocks identical across them. +4. Target the current course files (`sNN_topic/`), not legacy mirrors. +5. Disclose AI assistance. Using an agent is fine. Say so, and make sure you have read and stand behind the change. + +## What gets closed without detailed review + +To keep the review queue useful, we close: + +1. Bulk PRs generated by an agent and opened across many unrelated repositories at once. We cannot responsibly review code the author has not engaged with. +2. Changes that expand a chapter's scope or structure against the teaching design. +3. PRs not tied to an issue, or that restate a deliberate simplification as a bug. + +Focused, clearly explained contributions from people who have actually worked with the material are always welcome. + + +# 贡献指南 + +这是一个**教学仓库**。每一章(`sNN_topic/`)在上一章的基础上只讲清一个点,代码刻意保持最简。简化是有意为之,为的是让讲解保持清晰。欢迎服务于这个目标的贡献。 + +## 提 PR 之前 + +1. 对应一个具体 issue。说清问题是什么、为什么你的改法是对的。一个 PR 只解决一个问题。 +2. 教学代码保持最简。不要加生产级的防御解析、错误处理层、抽象或测试框架,除非这一章本身就在讲这些。某处"像 bug"的简化往往是刻意的,先在 issue 里问一声。 +3. 三语保持同步。对某章 `code.py` 或 README 的改动,必须同步到该章目录下三种语言的 README,且其中代码块完全一致。 +4. 改现行课程文件(`sNN_topic/`),不要改旧的镜像目录。 +5. 声明 AI 协助。用 agent 没问题,但请说明,并确保你读过、也认可这份改动。 + +## 哪些会被直接关闭(不做详细评审) + +1. 在大量互不相关的仓库里一次性批量提交、由 agent 生成的 PR。作者自己都没参与的代码,我们无法负责任地评审。 +2. 让某章范围或结构超出教学设计的改动。 +3. 没有对应 issue、或把刻意的简化当成 bug 来"修"的 PR。 + +真正用过这份材料、聚焦且讲清理由的贡献,我们始终欢迎。