From d92872e107a07b826bc84ad0aa921396e1144cd2 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 20:43:59 +0000 Subject: [PATCH 01/18] chore: add pull request template Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- .github/pull_request_template.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..62497fc7 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,16 @@ + + +## Motivation + + + +## Solution + + + +## Changes and impact + + + +- [ ] User-visible behavior changed: docs under `crates/maa-cli/docs/` are updated for every language +- [ ] Breaking change: this PR targets `dev-0.8`, not `main` From 1b15247a09b1516d86cca756f2649627727d945a Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 20:44:41 +0000 Subject: [PATCH 02/18] chore: make pull request template bilingual Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- .github/pull_request_template.md | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 62497fc7..f8388e1f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,16 +1,25 @@ -## Motivation +## 动机 / Motivation - + -## Solution +## 方案 / Solution - + -## Changes and impact +## 变更与影响 / Changes and impact - + -- [ ] User-visible behavior changed: docs under `crates/maa-cli/docs/` are updated for every language -- [ ] Breaking change: this PR targets `dev-0.8`, not `main` +- [ ] 改了用户可见行为的话，已同步更新 `crates/maa-cli/docs/` 下所有语言的文档 / User-visible behavior changed: docs under `crates/maa-cli/docs/` are updated for every language +- [ ] 如果是 breaking change，目标分支是 `dev-0.8` 而不是 `main` / Breaking change: this PR targets `dev-0.8`, not `main` From e9af90d94bdec1c2a3d42e00af1963e945835066 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 20:46:11 +0000 Subject: [PATCH 03/18] chore: ask for AI assistance disclosure in PR template Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- .github/pull_request_template.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index f8388e1f..ae16ee35 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -23,3 +23,15 @@ What will users notice: CLI behavior, config format, platform support? Call out - [ ] 改了用户可见行为的话，已同步更新 `crates/maa-cli/docs/` 下所有语言的文档 / User-visible behavior changed: docs under `crates/maa-cli/docs/` are updated for every language - [ ] 如果是 breaking change，目标分支是 `dev-0.8` 而不是 `main` / Breaking change: this PR targets `dev-0.8`, not `main` + +## AI 辅助 / AI assistance + + + +- 工具 / Harness: +- 模型 / Model: +- 参与程度 / Extent: From 87b50f605bb49eb4ed4ff021ca68133328a40455 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 20:47:59 +0000 Subject: [PATCH 04/18] chore: require self-review of AI-assisted changes in PR template Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- .github/pull_request_template.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index ae16ee35..d337e29a 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -30,8 +30,11 @@ What will users notice: CLI behavior, config format, platform support? Call out 如果用了 AI，请写明工具（harness）、模型和参与程度；没用就写“无”。 If AI was used, name the tool (harness), the model, and how much it contributed. Write "None" otherwise. 参与程度 / Extent: 大部分由 AI 生成 / mostly generated; 部分辅助 / partly assisted; 仅用于审查 / review only +未经作者本人审阅和整理的 AI 生成 PR 可能会被直接关闭。 +AI-generated PRs that the author has not reviewed and cleaned up may be closed without review. --> - 工具 / Harness: - 模型 / Model: - 参与程度 / Extent: +- [ ] 如果用了 AI，我已亲自审阅并整理全部改动，能解释每一处修改 / If AI was used, I have personally reviewed and cleaned up all changes and can explain each of them From 66f09d444e8f40dca9b7f1b62d4bee601b658465 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 20:58:28 +0000 Subject: [PATCH 05/18] docs: add CONTRIBUTING.md with scope and AI contribution guidelines Link it from the PR template and DEVELOPMENT.md. The template also gains a Testing section and a scope checkbox. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- .github/pull_request_template.md | 16 ++++++++++++++-- CONTRIBUTING.md | 33 ++++++++++++++++++++++++++++++++ DEVELOPMENT.md | 3 ++- 3 files changed, 49 insertions(+), 3 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index d337e29a..4bd7776a 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,10 +1,14 @@ + ## 动机 / Motivation ## 方案 / Solution @@ -21,6 +25,14 @@ How does this PR solve it? Focus on design choices that are not obvious from the What will users notice: CLI behavior, config format, platform support? Call out breaking changes explicitly. Write "None" for internal-only changes. --> +## 验证 / Testing + + + +- [ ] 本 PR 只包含实现上述目的所需的改动，无关的修复或重构已拆出 / This PR only contains changes needed for the purpose above; unrelated fixes and refactors are split out - [ ] 改了用户可见行为的话，已同步更新 `crates/maa-cli/docs/` 下所有语言的文档 / User-visible behavior changed: docs under `crates/maa-cli/docs/` are updated for every language - [ ] 如果是 breaking change，目标分支是 `dev-0.8` 而不是 `main` / Breaking change: this PR targets `dev-0.8`, not `main` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..5e336a66 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,33 @@ +# 贡献指南 / Contributing + +开发环境、代码规范和提交流程见 [开发文档](DEVELOPMENT.md)。本文只写 PR 的基本要求，尤其是使用 AI 工具时的要求。 + +## 先讨论，再写代码 + +- 新功能、新命令、新配置项或配置格式的改动，请先开 issue 讨论方案，达成一致后再写代码。没有讨论过的大型 PR 很可能需要推倒重来。 +- 提交前先搜一下有没有相同主题的 issue 或 PR，避免重复工作。 + +## 一个 PR 只做一件事 + +- PR 只包含实现目的所需的改动。顺手发现的问题、无关的重构请单独提 PR。 +- 改动较大时，拆成能独立 review 的几个提交，或者拆成多个 PR。 +- PR 描述保持简短，写清楚为什么改、怎么改、实际怎么验证的。不要粘贴工具生成的长篇摘要。 + +## 使用 AI 工具 + +欢迎使用 AI 工具，但作者要对提交的每一行负责。 + +- 让你的 agent 先读 [AGENTS.md](AGENTS.md)，它包含本仓库的代码规范和检查步骤。 +- 提交前亲自审阅并整理全部改动：删掉没有被要求的功能、多余的注释和防御性代码，确保你能解释每一处修改。 +- 在 PR 模板的「AI 辅助」一节写明使用的工具、模型和参与程度。 +- 回复 review 时请用自己的话，不要直接转贴 AI 的输出。 +- 明显没有经过作者审阅的大型 AI 生成 PR，维护者可能会直接关闭。长时间不回应 review 的 PR 也可能会被关闭。 + +## English + +See [DEVELOPMENT.md](DEVELOPMENT.md) for the development setup, code conventions and workflow. This file covers what we expect from a PR, especially when AI tools are involved. + +- **Discuss first.** Open an issue to agree on the design before implementing a new feature, command, config option or config format change. Large PRs without prior discussion will likely need to be redone. Search existing issues and PRs to avoid duplicate work. +- **One PR, one purpose.** Include only the changes needed for that purpose; send unrelated fixes and refactors separately. Keep the description short: why, how, and how you actually verified it. Do not paste long tool-generated summaries. +- **AI tools are welcome, but you own every line.** Have your agent read [AGENTS.md](AGENTS.md) first. Review and clean up all changes yourself before submitting: remove features nobody asked for, excessive comments and unnecessary defensive code, and make sure you can explain every change. Fill in the "AI assistance" section of the PR template. Reply to reviews in your own words instead of pasting AI output. +- Maintainers may close large AI-generated PRs that were clearly not reviewed by their author, as well as PRs that stay unresponsive to review for a long time. diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index c879502d..fd12d83d 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -24,7 +24,8 @@ - 避免直接向主分支提交代码，始终通过 PR 进行贡献。 - 提交 PR 前，确保自己的分支已经与主分支同步，避免合并冲突。 -- 对于较大或影响范围广的变更，建议先在 Issue 中充分讨论方案。 +- 新功能、新命令、新配置项或影响范围广的变更，请先在 Issue 中讨论方案。 +- PR 的范围和使用 AI 工具的要求见 [贡献指南](CONTRIBUTING.md)。 - 如对现有代码有任何疑问，可以在 Issue 中提出，以获得帮助和反馈。 - 欢迎任何形式的贡献，包括文档、测试、CI 配置等。 From 1379329a1f1a962ed64dda53f60bdd3b86e57131 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 22:40:39 +0000 Subject: [PATCH 06/18] docs: make contributing rules citable and slim down AI section of PR template Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- .github/pull_request_template.md | 15 ++++------- CONTRIBUTING.md | 46 +++++++++++++++++--------------- 2 files changed, 30 insertions(+), 31 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 4bd7776a..584557fe 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -14,8 +14,8 @@ Why is this change needed? What problem does it solve? Link the issue if there i ## 方案 / Solution ## 变更与影响 / Changes and impact @@ -39,14 +39,9 @@ Which commands did you actually run, on which platforms? Did you test against a ## AI 辅助 / AI assistance -- 工具 / Harness: -- 模型 / Model: -- 参与程度 / Extent: +- AI 写的部分 / AI-written parts: - [ ] 如果用了 AI，我已亲自审阅并整理全部改动，能解释每一处修改 / If AI was used, I have personally reviewed and cleaned up all changes and can explain each of them diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e336a66..6ffc11e9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,33 +1,37 @@ # 贡献指南 / Contributing -开发环境、代码规范和提交流程见 [开发文档](DEVELOPMENT.md)。本文只写 PR 的基本要求，尤其是使用 AI 工具时的要求。 +开发环境、代码规范和提交流程见 [开发文档](DEVELOPMENT.md)。本文是提交 PR 的规则，无论是否使用 AI 工具都适用。 -## 先讨论，再写代码 +## 规则 -- 新功能、新命令、新配置项或配置格式的改动，请先开 issue 讨论方案，达成一致后再写代码。没有讨论过的大型 PR 很可能需要推倒重来。 -- 提交前先搜一下有没有相同主题的 issue 或 PR，避免重复工作。 +1. **先讨论，再写代码。** 新功能、新命令、新配置项、配置格式变更，以及预计超过约 500 行的改动，请先开 issue 讨论方案，得到维护者认可后再写代码。bug 修复、文档和小改进可以直接提 PR。动手前先搜一下有没有相同主题的 issue 或 PR。 +2. **一个 PR 只做一件事。** 只包含实现目的所需的改动。顺手发现的问题、无关的重构请单独提。 +3. **作者对每一行负责。** 欢迎使用 AI 工具，但提交前请亲自审阅并整理全部改动，确保能解释每一处修改。删掉没有被要求的功能、多余的注释和不必要的防御性代码。使用 agent 时请让它先读 [AGENTS.md](AGENTS.md)。 +4. **描述简短具体。** 按 PR 模板写清楚为什么改、怎么改、实际怎么验证的，以及哪里你不确定。不要粘贴工具生成的长篇摘要。 +5. **用自己的话回复 review。** 不要直接转贴 AI 的输出。 -## 一个 PR 只做一件事 +## 维护者会怎么处理 -- PR 只包含实现目的所需的改动。顺手发现的问题、无关的重构请单独提 PR。 -- 改动较大时，拆成能独立 review 的几个提交，或者拆成多个 PR。 -- PR 描述保持简短，写清楚为什么改、怎么改、实际怎么验证的。不要粘贴工具生成的长篇摘要。 +- 违反第 1 条：请你先开 issue 讨论，PR 可能会先关闭，方案确定后再重新提交。 +- 违反第 2 条或改动过大：请你拆分，不拆分的 PR 可能会被关闭。 +- 明显没有经过作者审阅的 AI 生成 PR：可能会被直接关闭，不做逐行 review。 +- review 后 30 天没有回应：可能会被关闭，之后随时可以重新打开。 -## 使用 AI 工具 +这些处理不针对个人，只是为了让 review 的精力用在能合并的改动上。 -欢迎使用 AI 工具，但作者要对提交的每一行负责。 +## English -- 让你的 agent 先读 [AGENTS.md](AGENTS.md)，它包含本仓库的代码规范和检查步骤。 -- 提交前亲自审阅并整理全部改动：删掉没有被要求的功能、多余的注释和防御性代码，确保你能解释每一处修改。 -- 在 PR 模板的「AI 辅助」一节写明使用的工具、模型和参与程度。 -- 回复 review 时请用自己的话，不要直接转贴 AI 的输出。 -- 明显没有经过作者审阅的大型 AI 生成 PR，维护者可能会直接关闭。长时间不回应 review 的 PR 也可能会被关闭。 +See [DEVELOPMENT.md](DEVELOPMENT.md) for the development setup, code conventions and workflow. The rules below apply to every PR, whether or not AI tools were used. -## English +1. **Discuss first.** Open an issue and get the maintainers' agreement on the design before implementing a new feature, command, config option, config format change, or anything expected to exceed roughly 500 lines. Bug fixes, docs and small improvements can go straight to a PR. Search existing issues and PRs before starting. +2. **One PR, one purpose.** Include only the changes needed for that purpose. Send unrelated fixes and refactors separately. +3. **You own every line.** AI tools are welcome, but review and clean up all changes yourself before submitting, and make sure you can explain each of them. Remove features nobody asked for, excessive comments and unnecessary defensive code. If you use an agent, have it read [AGENTS.md](AGENTS.md) first. +4. **Keep the description short and concrete.** Follow the PR template: why, how, how you actually verified it, and what you are unsure about. Do not paste long tool-generated summaries. +5. **Reply to reviews in your own words.** Do not paste AI output. -See [DEVELOPMENT.md](DEVELOPMENT.md) for the development setup, code conventions and workflow. This file covers what we expect from a PR, especially when AI tools are involved. +What maintainers will do: -- **Discuss first.** Open an issue to agree on the design before implementing a new feature, command, config option or config format change. Large PRs without prior discussion will likely need to be redone. Search existing issues and PRs to avoid duplicate work. -- **One PR, one purpose.** Include only the changes needed for that purpose; send unrelated fixes and refactors separately. Keep the description short: why, how, and how you actually verified it. Do not paste long tool-generated summaries. -- **AI tools are welcome, but you own every line.** Have your agent read [AGENTS.md](AGENTS.md) first. Review and clean up all changes yourself before submitting: remove features nobody asked for, excessive comments and unnecessary defensive code, and make sure you can explain every change. Fill in the "AI assistance" section of the PR template. Reply to reviews in your own words instead of pasting AI output. -- Maintainers may close large AI-generated PRs that were clearly not reviewed by their author, as well as PRs that stay unresponsive to review for a long time. +- Rule 1 not followed: we will ask you to open an issue first, and the PR may be closed until the design is agreed. +- Rule 2 not followed, or the PR is too large: we will ask you to split it; PRs that are not split may be closed. +- AI-generated PRs that were clearly not reviewed by their author may be closed without a line-by-line review. +- No response for 30 days after a review: the PR may be closed; you can reopen it at any time. From 736bb74701efa1c2ad277d87a6e36003a550ebae Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 22:40:50 +0000 Subject: [PATCH 07/18] docs: add contribution rules for agents to AGENTS.md Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- AGENTS.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index ac9cd339..ff6b5ff3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -129,6 +129,18 @@ graph TD - One paragraph per line; use `
` for line breaks only when needed; no trailing spaces. - Markdown is linted by `markdownlint-cli2`. +## Contributing on Behalf of a Human (Follow This) + +If you are an agent helping someone prepare a PR, follow [CONTRIBUTING.md](CONTRIBUTING.md). In particular: + +- **Check for an agreed design first.** For a new feature, command, config option, config format change, or anything likely to exceed about 500 lines, confirm there is an issue where a maintainer agreed on the approach. If there is none, stop and tell your human to open one instead of implementing. +- **Stay in scope.** Implement only what the task needs. Do not add unrequested flags, subcommands, options or refactors. Report unrelated problems to your human instead of fixing them in the same PR. +- **Keep the diff lean.** No explanatory comment blocks, no speculative defensive code, no design notes or conversation summaries committed to the repo. Use `maa-types` enums or cite upstream definitions instead of magic numbers. +- **Follow existing patterns.** Look for how the codebase already solves a problem (tests included) before inventing a new mechanism. +- **Your human reviews before anything is published.** Do not open or push a PR until your human has read the whole diff. Never tick the self-review checkbox in the PR template for them. +- **Write the PR description from the template.** Keep it short, fill in the AI assistance section honestly, and do not paste long generated summaries. +- **Do not ghost-write review replies.** Help your human understand review feedback; the reply on GitHub should be in their own words. + ## MISC - Use conventional commits: `feat: ...`, `fix: ...`, `refactor: ...`, `perf: ...`, `docs: ...`, `test: ...`, etc. From ea9b6361cb6470e11f8f7ad97be4308fef8b5f49 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 22:45:50 +0000 Subject: [PATCH 08/18] docs: soften tone of CONTRIBUTING.md Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- CONTRIBUTING.md | 50 +++++++++++++++++++++++++------------------------ 1 file changed, 26 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6ffc11e9..62dcc5c1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,37 +1,39 @@ # 贡献指南 / Contributing -开发环境、代码规范和提交流程见 [开发文档](DEVELOPMENT.md)。本文是提交 PR 的规则，无论是否使用 AI 工具都适用。 +感谢你愿意为 maa-cli 贡献代码！开发环境、代码规范和提交流程请看 [开发文档](DEVELOPMENT.md)。这里说的是提交 PR 时我们希望你注意的几件事，不管有没有用 AI 工具都一样。 -## 规则 +maa-cli 的维护者人手很少，review 的时间往往比写代码的时间更紧张。下面这些约定，都是为了让你的改动能更快、更顺利地合并。 -1. **先讨论，再写代码。** 新功能、新命令、新配置项、配置格式变更，以及预计超过约 500 行的改动，请先开 issue 讨论方案，得到维护者认可后再写代码。bug 修复、文档和小改进可以直接提 PR。动手前先搜一下有没有相同主题的 issue 或 PR。 -2. **一个 PR 只做一件事。** 只包含实现目的所需的改动。顺手发现的问题、无关的重构请单独提。 -3. **作者对每一行负责。** 欢迎使用 AI 工具，但提交前请亲自审阅并整理全部改动，确保能解释每一处修改。删掉没有被要求的功能、多余的注释和不必要的防御性代码。使用 agent 时请让它先读 [AGENTS.md](AGENTS.md)。 -4. **描述简短具体。** 按 PR 模板写清楚为什么改、怎么改、实际怎么验证的，以及哪里你不确定。不要粘贴工具生成的长篇摘要。 -5. **用自己的话回复 review。** 不要直接转贴 AI 的输出。 +## 提交 PR 前 -## 维护者会怎么处理 +1. **先在 issue 里聊聊方案。** 如果要加新功能、新命令、新配置项，或者改配置格式，或者改动预计会超过 500 行左右，请先开一个 issue，和维护者对一下思路再动手，免得写完才发现方向不对，白费功夫。修 bug、改文档和小改进可以直接提 PR。开始之前也可以搜一下，看看有没有人已经在做同样的事。 +2. **一个 PR 只做一件事。** 顺手发现的其他问题或者想做的重构，欢迎另开 PR。小而专注的 PR 更容易 review，也更快能合并。 +3. **用 AI 没问题，但请自己先看一遍。** 提交之前，请亲自读一遍所有改动，确认每一处都是需要的，并且你能说清楚为什么这么改。AI 常常会多加一些没人要的功能、大段注释或者用不上的防御性代码，请顺手删掉。如果用 agent 写代码，记得让它先读 [AGENTS.md](AGENTS.md)。 +4. **PR 描述简短就好。** 按 PR 模板写清楚为什么改、怎么改、实际是怎么验证的，有不确定的地方也请写出来。不需要粘贴工具生成的长篇总结。 +5. **review 时请用自己的话回复。** 直接转贴 AI 的回答，我们很难判断你是不是同意、哪里有疑问。 -- 违反第 1 条：请你先开 issue 讨论，PR 可能会先关闭，方案确定后再重新提交。 -- 违反第 2 条或改动过大：请你拆分，不拆分的 PR 可能会被关闭。 -- 明显没有经过作者审阅的 AI 生成 PR：可能会被直接关闭，不做逐行 review。 -- review 后 30 天没有回应：可能会被关闭，之后随时可以重新打开。 +## 如果 PR 不太符合上面的约定 -这些处理不针对个人，只是为了让 review 的精力用在能合并的改动上。 +我们会在 PR 里说明原因，一般会这样处理： + +- 需要先讨论方案的：请你先开 issue，PR 可能会暂时关闭，方案确定后欢迎重新提交。 +- 改动太多、混了不相关内容的：请你拆分成几个 PR。 +- 明显没有经过作者本人检查的 AI 生成 PR：我们可能会直接关闭，不再逐行 review。 +- review 之后 30 天没有回应的：可能会关闭，你之后随时可以重新打开。 ## English -See [DEVELOPMENT.md](DEVELOPMENT.md) for the development setup, code conventions and workflow. The rules below apply to every PR, whether or not AI tools were used. +Thanks for contributing to maa-cli! See [DEVELOPMENT.md](DEVELOPMENT.md) for the development setup, code conventions and workflow. Below is what we ask of every PR, whether or not you used AI tools. We have very few maintainers and review time is usually the bottleneck, so these help your change get merged faster. -1. **Discuss first.** Open an issue and get the maintainers' agreement on the design before implementing a new feature, command, config option, config format change, or anything expected to exceed roughly 500 lines. Bug fixes, docs and small improvements can go straight to a PR. Search existing issues and PRs before starting. -2. **One PR, one purpose.** Include only the changes needed for that purpose. Send unrelated fixes and refactors separately. -3. **You own every line.** AI tools are welcome, but review and clean up all changes yourself before submitting, and make sure you can explain each of them. Remove features nobody asked for, excessive comments and unnecessary defensive code. If you use an agent, have it read [AGENTS.md](AGENTS.md) first. -4. **Keep the description short and concrete.** Follow the PR template: why, how, how you actually verified it, and what you are unsure about. Do not paste long tool-generated summaries. -5. **Reply to reviews in your own words.** Do not paste AI output. +1. **Talk about the design in an issue first.** For a new feature, command, config option, config format change, or anything likely to exceed roughly 500 lines, please open an issue and agree on the approach with a maintainer before writing code, so you don't spend effort in the wrong direction. Bug fixes, docs and small improvements can go straight to a PR. It's also worth searching for existing issues and PRs on the same topic. +2. **One PR, one purpose.** Other problems you notice or refactors you'd like to do are welcome as separate PRs. Small, focused PRs are easier to review and get merged sooner. +3. **AI is fine, but please review it yourself.** Before submitting, read through every change, make sure each one is needed, and that you can explain why it is there. AI tends to add features nobody asked for, long comments and unneeded defensive code; please remove them. If you use an agent, have it read [AGENTS.md](AGENTS.md) first. +4. **Keep the description short.** Follow the PR template: why, how, how you actually verified it, and anything you are unsure about. No need to paste long generated summaries. +5. **Reply to reviews in your own words.** When AI output is pasted as a reply, it is hard for us to tell whether you agree or what you are unsure about. -What maintainers will do: +If a PR doesn't follow these, we will explain why in the PR. Usually: -- Rule 1 not followed: we will ask you to open an issue first, and the PR may be closed until the design is agreed. -- Rule 2 not followed, or the PR is too large: we will ask you to split it; PRs that are not split may be closed. -- AI-generated PRs that were clearly not reviewed by their author may be closed without a line-by-line review. -- No response for 30 days after a review: the PR may be closed; you can reopen it at any time. +- Needs design discussion first: we will ask you to open an issue; the PR may be closed for now and you are welcome to resubmit once the design is agreed. +- Too large or mixes unrelated changes: we will ask you to split it. +- AI-generated PRs clearly not reviewed by their author: may be closed without a line-by-line review. +- No response for 30 days after a review: may be closed; you can reopen it at any time. From f961ed8751f810a46492e6a2b29c82fa1b6fdfc6 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 22:46:26 +0000 Subject: [PATCH 09/18] chore: drop dev-0.8 checkbox from PR template Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- .github/pull_request_template.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 584557fe..92a07f05 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -34,7 +34,6 @@ Which commands did you actually run, on which platforms? Did you test against a - [ ] 本 PR 只包含实现上述目的所需的改动，无关的修复或重构已拆出 / This PR only contains changes needed for the purpose above; unrelated fixes and refactors are split out - [ ] 改了用户可见行为的话，已同步更新 `crates/maa-cli/docs/` 下所有语言的文档 / User-visible behavior changed: docs under `crates/maa-cli/docs/` are updated for every language -- [ ] 如果是 breaking change，目标分支是 `dev-0.8` 而不是 `main` / Breaking change: this PR targets `dev-0.8`, not `main` ## AI 辅助 / AI assistance From 0fab10fbf25123d68cad0ae13138a62beb531639 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 22:48:13 +0000 Subject: [PATCH 10/18] docs: use a more formal tone in CONTRIBUTING.md Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- CONTRIBUTING.md | 46 +++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 62dcc5c1..e0459dc6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,39 +1,39 @@ # 贡献指南 / Contributing -感谢你愿意为 maa-cli 贡献代码！开发环境、代码规范和提交流程请看 [开发文档](DEVELOPMENT.md)。这里说的是提交 PR 时我们希望你注意的几件事，不管有没有用 AI 工具都一样。 +感谢你对 maa-cli 的贡献。开发环境、代码规范和提交流程见 [开发文档](DEVELOPMENT.md)，本文说明提交 PR 时需要注意的事项，无论是否使用 AI 工具均适用。 -maa-cli 的维护者人手很少，review 的时间往往比写代码的时间更紧张。下面这些约定，都是为了让你的改动能更快、更顺利地合并。 +本项目维护者人手有限，review 往往是合并的瓶颈。以下约定的目的是让改动能够更快地被审阅和合并。 ## 提交 PR 前 -1. **先在 issue 里聊聊方案。** 如果要加新功能、新命令、新配置项，或者改配置格式，或者改动预计会超过 500 行左右，请先开一个 issue，和维护者对一下思路再动手，免得写完才发现方向不对，白费功夫。修 bug、改文档和小改进可以直接提 PR。开始之前也可以搜一下，看看有没有人已经在做同样的事。 -2. **一个 PR 只做一件事。** 顺手发现的其他问题或者想做的重构，欢迎另开 PR。小而专注的 PR 更容易 review，也更快能合并。 -3. **用 AI 没问题，但请自己先看一遍。** 提交之前，请亲自读一遍所有改动，确认每一处都是需要的，并且你能说清楚为什么这么改。AI 常常会多加一些没人要的功能、大段注释或者用不上的防御性代码，请顺手删掉。如果用 agent 写代码，记得让它先读 [AGENTS.md](AGENTS.md)。 -4. **PR 描述简短就好。** 按 PR 模板写清楚为什么改、怎么改、实际是怎么验证的，有不确定的地方也请写出来。不需要粘贴工具生成的长篇总结。 -5. **review 时请用自己的话回复。** 直接转贴 AI 的回答，我们很难判断你是不是同意、哪里有疑问。 +1. **先在 issue 中讨论方案。** 新功能、新命令、新配置项、配置格式的变更，以及预计超过约 500 行的改动，请先开 issue 与维护者确认方案，再开始实现，以免方向不一致导致返工。bug 修复、文档和小幅改进可以直接提交 PR。开始之前，请先搜索是否已有相同主题的 issue 或 PR。 +2. **每个 PR 只解决一个问题。** 开发过程中发现的其他问题或希望进行的重构，请另开 PR。范围集中的 PR 更容易审阅，也能更快合并。 +3. **使用 AI 生成的改动需要经过作者本人审阅。** 提交前请完整阅读所有改动，确认每一处都是必要的，并能说明修改的理由。AI 生成的代码常包含未被要求的功能、冗长的注释或不必要的防御性代码，请在提交前删除。使用 agent 开发时，请让它先阅读 [AGENTS.md](AGENTS.md)。 +4. **PR 描述应简洁。** 请按照 PR 模板说明修改的原因、实现方式和实际的验证方法，如有不确定之处也请注明。不需要附上工具生成的长篇摘要。 +5. **请用自己的语言回复 review。** 直接转贴 AI 的输出，会让维护者难以判断你是否认同修改意见，以及有哪些疑问。 -## 如果 PR 不太符合上面的约定 +## 不符合约定的 PR -我们会在 PR 里说明原因，一般会这样处理： +维护者会在 PR 中说明原因，并视情况处理： -- 需要先讨论方案的：请你先开 issue，PR 可能会暂时关闭，方案确定后欢迎重新提交。 -- 改动太多、混了不相关内容的：请你拆分成几个 PR。 -- 明显没有经过作者本人检查的 AI 生成 PR：我们可能会直接关闭，不再逐行 review。 -- review 之后 30 天没有回应的：可能会关闭，你之后随时可以重新打开。 +- 需要先讨论方案的：请先开 issue，PR 可能会暂时关闭，方案确定后可以重新提交。 +- 改动过大或包含无关内容的：请拆分为多个 PR。 +- 明显未经作者本人审阅的 AI 生成 PR：可能会直接关闭，不进行逐行 review。 +- review 后 30 天内没有回应的：可能会关闭，之后可以随时重新打开。 ## English -Thanks for contributing to maa-cli! See [DEVELOPMENT.md](DEVELOPMENT.md) for the development setup, code conventions and workflow. Below is what we ask of every PR, whether or not you used AI tools. We have very few maintainers and review time is usually the bottleneck, so these help your change get merged faster. +Thank you for contributing to maa-cli. See [DEVELOPMENT.md](DEVELOPMENT.md) for the development setup, code conventions and workflow. This document describes what we expect from a PR, whether or not AI tools were used. The project has few maintainers and review is often the bottleneck; these conventions help changes get reviewed and merged sooner. -1. **Talk about the design in an issue first.** For a new feature, command, config option, config format change, or anything likely to exceed roughly 500 lines, please open an issue and agree on the approach with a maintainer before writing code, so you don't spend effort in the wrong direction. Bug fixes, docs and small improvements can go straight to a PR. It's also worth searching for existing issues and PRs on the same topic. -2. **One PR, one purpose.** Other problems you notice or refactors you'd like to do are welcome as separate PRs. Small, focused PRs are easier to review and get merged sooner. -3. **AI is fine, but please review it yourself.** Before submitting, read through every change, make sure each one is needed, and that you can explain why it is there. AI tends to add features nobody asked for, long comments and unneeded defensive code; please remove them. If you use an agent, have it read [AGENTS.md](AGENTS.md) first. -4. **Keep the description short.** Follow the PR template: why, how, how you actually verified it, and anything you are unsure about. No need to paste long generated summaries. -5. **Reply to reviews in your own words.** When AI output is pasted as a reply, it is hard for us to tell whether you agree or what you are unsure about. +1. **Discuss the design in an issue first.** For a new feature, command, config option, config format change, or a change expected to exceed roughly 500 lines, open an issue and agree on the approach with a maintainer before implementing it, to avoid rework. Bug fixes, docs and small improvements can be submitted as a PR directly. Search for existing issues and PRs on the same topic before starting. +2. **One PR, one purpose.** Submit other problems you find or refactors you want to make as separate PRs. Focused PRs are easier to review and merge. +3. **AI-generated changes must be reviewed by the author.** Before submitting, read every change, make sure each one is necessary, and be able to explain it. AI-generated code often includes features nobody asked for, verbose comments and unnecessary defensive code; remove them before submitting. If you use an agent, have it read [AGENTS.md](AGENTS.md) first. +4. **Keep the description concise.** Follow the PR template: why, how, how you actually verified it, and anything you are unsure about. Do not include long tool-generated summaries. +5. **Reply to reviews in your own words.** Pasted AI output makes it hard for maintainers to tell whether you agree with the feedback and what questions you have. -If a PR doesn't follow these, we will explain why in the PR. Usually: +PRs that do not follow these conventions: maintainers will explain why in the PR and, depending on the case: -- Needs design discussion first: we will ask you to open an issue; the PR may be closed for now and you are welcome to resubmit once the design is agreed. -- Too large or mixes unrelated changes: we will ask you to split it. +- Needs design discussion first: you will be asked to open an issue; the PR may be closed for now and can be resubmitted once the design is agreed. +- Too large or contains unrelated changes: you will be asked to split it into several PRs. - AI-generated PRs clearly not reviewed by their author: may be closed without a line-by-line review. -- No response for 30 days after a review: may be closed; you can reopen it at any time. +- No response within 30 days after a review: may be closed; it can be reopened at any time. From e5e5484b6e2818ce2b695f76153150d4ae7aee6c Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 22:49:48 +0000 Subject: [PATCH 11/18] docs: interleave Chinese and English in CONTRIBUTING.md by section Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- CONTRIBUTING.md | 44 ++++++++++++++++++++++++++++---------------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e0459dc6..cf1d5c5e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,36 +4,48 @@ 本项目维护者人手有限，review 往往是合并的瓶颈。以下约定的目的是让改动能够更快地被审阅和合并。 -## 提交 PR 前 +Thank you for contributing to maa-cli. See [DEVELOPMENT.md](DEVELOPMENT.md) for the development setup, code conventions and workflow. This document describes what we expect from a PR, whether or not AI tools were used. The project has few maintainers and review is often the bottleneck; these conventions help changes get reviewed and merged sooner. + +## 提交 PR 前 / Before submitting a PR 1. **先在 issue 中讨论方案。** 新功能、新命令、新配置项、配置格式的变更，以及预计超过约 500 行的改动，请先开 issue 与维护者确认方案，再开始实现，以免方向不一致导致返工。bug 修复、文档和小幅改进可以直接提交 PR。开始之前，请先搜索是否已有相同主题的 issue 或 PR。 + + **Discuss the design in an issue first.** For a new feature, command, config option, config format change, or a change expected to exceed roughly 500 lines, open an issue and agree on the approach with a maintainer before implementing it, to avoid rework. Bug fixes, docs and small improvements can be submitted as a PR directly. Search for existing issues and PRs on the same topic before starting. + 2. **每个 PR 只解决一个问题。** 开发过程中发现的其他问题或希望进行的重构，请另开 PR。范围集中的 PR 更容易审阅，也能更快合并。 + + **One PR, one purpose.** Submit other problems you find or refactors you want to make as separate PRs. Focused PRs are easier to review and merge. + 3. **使用 AI 生成的改动需要经过作者本人审阅。** 提交前请完整阅读所有改动，确认每一处都是必要的，并能说明修改的理由。AI 生成的代码常包含未被要求的功能、冗长的注释或不必要的防御性代码，请在提交前删除。使用 agent 开发时，请让它先阅读 [AGENTS.md](AGENTS.md)。 + + **AI-generated changes must be reviewed by the author.** Before submitting, read every change, make sure each one is necessary, and be able to explain it. AI-generated code often includes features nobody asked for, verbose comments and unnecessary defensive code; remove them before submitting. If you use an agent, have it read [AGENTS.md](AGENTS.md) first. + 4. **PR 描述应简洁。** 请按照 PR 模板说明修改的原因、实现方式和实际的验证方法，如有不确定之处也请注明。不需要附上工具生成的长篇摘要。 + + **Keep the description concise.** Follow the PR template: why, how, how you actually verified it, and anything you are unsure about. Do not include long tool-generated summaries. + 5. **请用自己的语言回复 review。** 直接转贴 AI 的输出，会让维护者难以判断你是否认同修改意见，以及有哪些疑问。 -## 不符合约定的 PR + **Reply to reviews in your own words.** Pasted AI output makes it hard for maintainers to tell whether you agree with the feedback and what questions you have. + +## 不符合约定的 PR / PRs that do not follow these conventions 维护者会在 PR 中说明原因，并视情况处理： +Maintainers will explain why in the PR and, depending on the case: + - 需要先讨论方案的：请先开 issue，PR 可能会暂时关闭，方案确定后可以重新提交。 + + Needs design discussion first: you will be asked to open an issue; the PR may be closed for now and can be resubmitted once the design is agreed. + - 改动过大或包含无关内容的：请拆分为多个 PR。 -- 明显未经作者本人审阅的 AI 生成 PR：可能会直接关闭，不进行逐行 review。 -- review 后 30 天内没有回应的：可能会关闭，之后可以随时重新打开。 -## English + Too large or contains unrelated changes: you will be asked to split it into several PRs. -Thank you for contributing to maa-cli. See [DEVELOPMENT.md](DEVELOPMENT.md) for the development setup, code conventions and workflow. This document describes what we expect from a PR, whether or not AI tools were used. The project has few maintainers and review is often the bottleneck; these conventions help changes get reviewed and merged sooner. +- 明显未经作者本人审阅的 AI 生成 PR：可能会直接关闭，不进行逐行 review。 -1. **Discuss the design in an issue first.** For a new feature, command, config option, config format change, or a change expected to exceed roughly 500 lines, open an issue and agree on the approach with a maintainer before implementing it, to avoid rework. Bug fixes, docs and small improvements can be submitted as a PR directly. Search for existing issues and PRs on the same topic before starting. -2. **One PR, one purpose.** Submit other problems you find or refactors you want to make as separate PRs. Focused PRs are easier to review and merge. -3. **AI-generated changes must be reviewed by the author.** Before submitting, read every change, make sure each one is necessary, and be able to explain it. AI-generated code often includes features nobody asked for, verbose comments and unnecessary defensive code; remove them before submitting. If you use an agent, have it read [AGENTS.md](AGENTS.md) first. -4. **Keep the description concise.** Follow the PR template: why, how, how you actually verified it, and anything you are unsure about. Do not include long tool-generated summaries. -5. **Reply to reviews in your own words.** Pasted AI output makes it hard for maintainers to tell whether you agree with the feedback and what questions you have. + AI-generated PRs clearly not reviewed by their author: may be closed without a line-by-line review. -PRs that do not follow these conventions: maintainers will explain why in the PR and, depending on the case: +- review 后 30 天内没有回应的：可能会关闭，之后可以随时重新打开。 -- Needs design discussion first: you will be asked to open an issue; the PR may be closed for now and can be resubmitted once the design is agreed. -- Too large or contains unrelated changes: you will be asked to split it into several PRs. -- AI-generated PRs clearly not reviewed by their author: may be closed without a line-by-line review. -- No response within 30 days after a review: may be closed; it can be reopened at any time. + No response within 30 days after a review: may be closed; it can be reopened at any time. From abb892341133b6c140d859b823a55de27a92d4dc Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 22:53:01 +0000 Subject: [PATCH 12/18] docs: split CONTRIBUTING.md into Chinese and English sections Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- CONTRIBUTING.md | 50 +++++++++++++++++++++++-------------------------- 1 file changed, 23 insertions(+), 27 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cf1d5c5e..4121135f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,51 +1,47 @@ # 贡献指南 / Contributing +[中文](#中文) | [English](#english) + +## 中文 + 感谢你对 maa-cli 的贡献。开发环境、代码规范和提交流程见 [开发文档](DEVELOPMENT.md)，本文说明提交 PR 时需要注意的事项，无论是否使用 AI 工具均适用。 本项目维护者人手有限，review 往往是合并的瓶颈。以下约定的目的是让改动能够更快地被审阅和合并。 -Thank you for contributing to maa-cli. See [DEVELOPMENT.md](DEVELOPMENT.md) for the development setup, code conventions and workflow. This document describes what we expect from a PR, whether or not AI tools were used. The project has few maintainers and review is often the bottleneck; these conventions help changes get reviewed and merged sooner. - -## 提交 PR 前 / Before submitting a PR +### 提交 PR 前 1. **先在 issue 中讨论方案。** 新功能、新命令、新配置项、配置格式的变更，以及预计超过约 500 行的改动，请先开 issue 与维护者确认方案，再开始实现，以免方向不一致导致返工。bug 修复、文档和小幅改进可以直接提交 PR。开始之前，请先搜索是否已有相同主题的 issue 或 PR。 - - **Discuss the design in an issue first.** For a new feature, command, config option, config format change, or a change expected to exceed roughly 500 lines, open an issue and agree on the approach with a maintainer before implementing it, to avoid rework. Bug fixes, docs and small improvements can be submitted as a PR directly. Search for existing issues and PRs on the same topic before starting. - 2. **每个 PR 只解决一个问题。** 开发过程中发现的其他问题或希望进行的重构，请另开 PR。范围集中的 PR 更容易审阅，也能更快合并。 - - **One PR, one purpose.** Submit other problems you find or refactors you want to make as separate PRs. Focused PRs are easier to review and merge. - 3. **使用 AI 生成的改动需要经过作者本人审阅。** 提交前请完整阅读所有改动，确认每一处都是必要的，并能说明修改的理由。AI 生成的代码常包含未被要求的功能、冗长的注释或不必要的防御性代码，请在提交前删除。使用 agent 开发时，请让它先阅读 [AGENTS.md](AGENTS.md)。 - - **AI-generated changes must be reviewed by the author.** Before submitting, read every change, make sure each one is necessary, and be able to explain it. AI-generated code often includes features nobody asked for, verbose comments and unnecessary defensive code; remove them before submitting. If you use an agent, have it read [AGENTS.md](AGENTS.md) first. - 4. **PR 描述应简洁。** 请按照 PR 模板说明修改的原因、实现方式和实际的验证方法，如有不确定之处也请注明。不需要附上工具生成的长篇摘要。 - - **Keep the description concise.** Follow the PR template: why, how, how you actually verified it, and anything you are unsure about. Do not include long tool-generated summaries. - 5. **请用自己的语言回复 review。** 直接转贴 AI 的输出，会让维护者难以判断你是否认同修改意见，以及有哪些疑问。 - **Reply to reviews in your own words.** Pasted AI output makes it hard for maintainers to tell whether you agree with the feedback and what questions you have. - -## 不符合约定的 PR / PRs that do not follow these conventions +### 不符合约定的 PR 维护者会在 PR 中说明原因，并视情况处理： -Maintainers will explain why in the PR and, depending on the case: - - 需要先讨论方案的：请先开 issue，PR 可能会暂时关闭，方案确定后可以重新提交。 +- 改动过大或包含无关内容的：请拆分为多个 PR。 +- 明显未经作者本人审阅的 AI 生成 PR：可能会直接关闭，不进行逐行 review。 +- review 后 30 天内没有回应的：可能会关闭，之后可以随时重新打开。 - Needs design discussion first: you will be asked to open an issue; the PR may be closed for now and can be resubmitted once the design is agreed. +## English -- 改动过大或包含无关内容的：请拆分为多个 PR。 +Thank you for contributing to maa-cli. See [DEVELOPMENT.md](DEVELOPMENT.md) for the development setup, code conventions and workflow. This document describes what we expect from a PR, whether or not AI tools were used. The project has few maintainers and review is often the bottleneck; these conventions help changes get reviewed and merged sooner. - Too large or contains unrelated changes: you will be asked to split it into several PRs. +### Before submitting a PR -- 明显未经作者本人审阅的 AI 生成 PR：可能会直接关闭，不进行逐行 review。 +1. **Discuss the design in an issue first.** For a new feature, command, config option, config format change, or a change expected to exceed roughly 500 lines, open an issue and agree on the approach with a maintainer before implementing it, to avoid rework. Bug fixes, docs and small improvements can be submitted as a PR directly. Search for existing issues and PRs on the same topic before starting. +2. **One PR, one purpose.** Submit other problems you find or refactors you want to make as separate PRs. Focused PRs are easier to review and merge. +3. **AI-generated changes must be reviewed by the author.** Before submitting, read every change, make sure each one is necessary, and be able to explain it. AI-generated code often includes features nobody asked for, verbose comments and unnecessary defensive code; remove them before submitting. If you use an agent, have it read [AGENTS.md](AGENTS.md) first. +4. **Keep the description concise.** Follow the PR template: why, how, how you actually verified it, and anything you are unsure about. Do not include long tool-generated summaries. +5. **Reply to reviews in your own words.** Pasted AI output makes it hard for maintainers to tell whether you agree with the feedback and what questions you have. - AI-generated PRs clearly not reviewed by their author: may be closed without a line-by-line review. +### PRs that do not follow these conventions -- review 后 30 天内没有回应的：可能会关闭，之后可以随时重新打开。 +Maintainers will explain why in the PR and, depending on the case: - No response within 30 days after a review: may be closed; it can be reopened at any time. +- Needs design discussion first: you will be asked to open an issue; the PR may be closed for now and can be resubmitted once the design is agreed. +- Too large or contains unrelated changes: you will be asked to split it into several PRs. +- AI-generated PRs clearly not reviewed by their author: may be closed without a line-by-line review. +- No response within 30 days after a review: may be closed; it can be reopened at any time. From 6ebd5f23f7f1379eb24769b9a1333f429550a1b8 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 22:56:01 +0000 Subject: [PATCH 13/18] docs: welcome all contributions and allow minimal PR descriptions for small changes Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- .github/pull_request_template.md | 2 ++ CONTRIBUTING.md | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 92a07f05..a70ed21c 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,6 +2,8 @@ ## 动机 / Motivation diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4121135f..de5f2625 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ ## 中文 -感谢你对 maa-cli 的贡献。开发环境、代码规范和提交流程见 [开发文档](DEVELOPMENT.md)，本文说明提交 PR 时需要注意的事项，无论是否使用 AI 工具均适用。 +感谢你对 maa-cli 的关注。我们欢迎任何形式的贡献，包括 bug 报告、功能建议、文档改进和代码。开发环境、代码规范和提交流程见 [开发文档](DEVELOPMENT.md)，本文说明提交 PR 时需要注意的事项，无论是否使用 AI 工具均适用。 本项目维护者人手有限，review 往往是合并的瓶颈。以下约定的目的是让改动能够更快地被审阅和合并。 @@ -27,7 +27,7 @@ ## English -Thank you for contributing to maa-cli. See [DEVELOPMENT.md](DEVELOPMENT.md) for the development setup, code conventions and workflow. This document describes what we expect from a PR, whether or not AI tools were used. The project has few maintainers and review is often the bottleneck; these conventions help changes get reviewed and merged sooner. +Thank you for your interest in maa-cli. Contributions of all kinds are welcome, including bug reports, feature suggestions, documentation improvements and code. See [DEVELOPMENT.md](DEVELOPMENT.md) for the development setup, code conventions and workflow. This document describes what we expect from a PR, whether or not AI tools were used. The project has few maintainers and review is often the bottleneck; these conventions help changes get reviewed and merged sooner. ### Before submitting a PR From 60fe1940f91e1664bc399e5aafa3eb2568586dd0 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 22:58:00 +0000 Subject: [PATCH 14/18] docs: welcome AI tools explicitly in CONTRIBUTING.md Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index de5f2625..c5471384 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,7 @@ 1. **先在 issue 中讨论方案。** 新功能、新命令、新配置项、配置格式的变更，以及预计超过约 500 行的改动，请先开 issue 与维护者确认方案，再开始实现，以免方向不一致导致返工。bug 修复、文档和小幅改进可以直接提交 PR。开始之前，请先搜索是否已有相同主题的 issue 或 PR。 2. **每个 PR 只解决一个问题。** 开发过程中发现的其他问题或希望进行的重构，请另开 PR。范围集中的 PR 更容易审阅，也能更快合并。 -3. **使用 AI 生成的改动需要经过作者本人审阅。** 提交前请完整阅读所有改动，确认每一处都是必要的，并能说明修改的理由。AI 生成的代码常包含未被要求的功能、冗长的注释或不必要的防御性代码，请在提交前删除。使用 agent 开发时，请让它先阅读 [AGENTS.md](AGENTS.md)。 +3. **欢迎使用 AI 工具，但改动需要经过作者本人审阅。** 提交前请完整阅读所有改动，确认每一处都是必要的，并能说明修改的理由。AI 生成的代码常包含未被要求的功能、冗长的注释或不必要的防御性代码，请在提交前删除。使用 agent 开发时，请让它先阅读 [AGENTS.md](AGENTS.md)。 4. **PR 描述应简洁。** 请按照 PR 模板说明修改的原因、实现方式和实际的验证方法，如有不确定之处也请注明。不需要附上工具生成的长篇摘要。 5. **请用自己的语言回复 review。** 直接转贴 AI 的输出，会让维护者难以判断你是否认同修改意见，以及有哪些疑问。 @@ -33,7 +33,7 @@ Thank you for your interest in maa-cli. Contributions of all kinds are welcome, 1. **Discuss the design in an issue first.** For a new feature, command, config option, config format change, or a change expected to exceed roughly 500 lines, open an issue and agree on the approach with a maintainer before implementing it, to avoid rework. Bug fixes, docs and small improvements can be submitted as a PR directly. Search for existing issues and PRs on the same topic before starting. 2. **One PR, one purpose.** Submit other problems you find or refactors you want to make as separate PRs. Focused PRs are easier to review and merge. -3. **AI-generated changes must be reviewed by the author.** Before submitting, read every change, make sure each one is necessary, and be able to explain it. AI-generated code often includes features nobody asked for, verbose comments and unnecessary defensive code; remove them before submitting. If you use an agent, have it read [AGENTS.md](AGENTS.md) first. +3. **AI tools are welcome, but changes must be reviewed by the author.** Before submitting, read every change, make sure each one is necessary, and be able to explain it. AI-generated code often includes features nobody asked for, verbose comments and unnecessary defensive code; remove them before submitting. If you use an agent, have it read [AGENTS.md](AGENTS.md) first. 4. **Keep the description concise.** Follow the PR template: why, how, how you actually verified it, and anything you are unsure about. Do not include long tool-generated summaries. 5. **Reply to reviews in your own words.** Pasted AI output makes it hard for maintainers to tell whether you agree with the feedback and what questions you have. From 387264bfd579351b60d981ca27a7d87f75483d95 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 22:59:37 +0000 Subject: [PATCH 15/18] chore: add explicit no-AI option to PR template Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- .github/pull_request_template.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index a70ed21c..06ee7c68 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -40,9 +40,10 @@ Which commands did you actually run, on which platforms? Did you test against a ## AI 辅助 / AI assistance -- AI 写的部分 / AI-written parts: -- [ ] 如果用了 AI，我已亲自审阅并整理全部改动，能解释每一处修改 / If AI was used, I have personally reviewed and cleaned up all changes and can explain each of them +- [ ] 未使用 AI / No AI used +- [ ] 使用了 AI，我已亲自审阅并整理全部改动，能解释每一处修改 / AI was used, and I have personally reviewed and cleaned up all changes and can explain each of them + - AI 编写的部分 / AI-written parts: From 83ed8babe3dd3ab7af6b6c7a21ab214429f867a9 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 23:06:22 +0000 Subject: [PATCH 16/18] chore: move MD041 exemption for PR template into .github lint config Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- .github/.markdownlint.yaml | 3 +++ .github/pull_request_template.md | 1 - 2 files changed, 3 insertions(+), 1 deletion(-) create mode 100644 .github/.markdownlint.yaml diff --git a/.github/.markdownlint.yaml b/.github/.markdownlint.yaml new file mode 100644 index 00000000..e4996298 --- /dev/null +++ b/.github/.markdownlint.yaml @@ -0,0 +1,3 @@ +# PR/issue templates do not start with a top-level heading +extends: ../.markdownlint.yaml +MD041: false diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 06ee7c68..1cae1284 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,4 +1,3 @@ - -## 验证 / Testing - - +## 检查项 / Checklist - [ ] 本 PR 只包含实现上述目的所需的改动，无关的修复或重构已拆出 / This PR only contains changes needed for the purpose above; unrelated fixes and refactors are split out - [ ] 改了用户可见行为的话，已同步更新 `crates/maa-cli/docs/` 下所有语言的文档 / User-visible behavior changed: docs under `crates/maa-cli/docs/` are updated for every language diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c5471384..b1ec87e1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,7 +13,7 @@ 1. **先在 issue 中讨论方案。** 新功能、新命令、新配置项、配置格式的变更，以及预计超过约 500 行的改动，请先开 issue 与维护者确认方案，再开始实现，以免方向不一致导致返工。bug 修复、文档和小幅改进可以直接提交 PR。开始之前，请先搜索是否已有相同主题的 issue 或 PR。 2. **每个 PR 只解决一个问题。** 开发过程中发现的其他问题或希望进行的重构，请另开 PR。范围集中的 PR 更容易审阅，也能更快合并。 3. **欢迎使用 AI 工具，但改动需要经过作者本人审阅。** 提交前请完整阅读所有改动，确认每一处都是必要的，并能说明修改的理由。AI 生成的代码常包含未被要求的功能、冗长的注释或不必要的防御性代码，请在提交前删除。使用 agent 开发时，请让它先阅读 [AGENTS.md](AGENTS.md)。 -4. **PR 描述应简洁。** 请按照 PR 模板说明修改的原因、实现方式和实际的验证方法，如有不确定之处也请注明。不需要附上工具生成的长篇摘要。 +4. **PR 描述应简洁。** 请按照 PR 模板说明修改的原因和实现方式，如有不确定之处也请注明。不需要附上工具生成的长篇摘要。 5. **请用自己的语言回复 review。** 直接转贴 AI 的输出，会让维护者难以判断你是否认同修改意见，以及有哪些疑问。 ### 不符合约定的 PR @@ -34,7 +34,7 @@ Thank you for your interest in maa-cli. Contributions of all kinds are welcome, 1. **Discuss the design in an issue first.** For a new feature, command, config option, config format change, or a change expected to exceed roughly 500 lines, open an issue and agree on the approach with a maintainer before implementing it, to avoid rework. Bug fixes, docs and small improvements can be submitted as a PR directly. Search for existing issues and PRs on the same topic before starting. 2. **One PR, one purpose.** Submit other problems you find or refactors you want to make as separate PRs. Focused PRs are easier to review and merge. 3. **AI tools are welcome, but changes must be reviewed by the author.** Before submitting, read every change, make sure each one is necessary, and be able to explain it. AI-generated code often includes features nobody asked for, verbose comments and unnecessary defensive code; remove them before submitting. If you use an agent, have it read [AGENTS.md](AGENTS.md) first. -4. **Keep the description concise.** Follow the PR template: why, how, how you actually verified it, and anything you are unsure about. Do not include long tool-generated summaries. +4. **Keep the description concise.** Follow the PR template: why, how, and anything you are unsure about. Do not include long tool-generated summaries. 5. **Reply to reviews in your own words.** Pasted AI output makes it hard for maintainers to tell whether you agree with the feedback and what questions you have. ### PRs that do not follow these conventions From 1b759258677da569ea284e63247af0cd1afda254 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 14 Oct 2026 23:14:03 +0000 Subject: [PATCH 18/18] docs: drop overly specific magic-number rule from AGENTS.md Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01Qi8EYMmsuJP5a8dihMu6rA --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index ff6b5ff3..65df2337 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -135,7 +135,7 @@ If you are an agent helping someone prepare a PR, follow [CONTRIBUTING.md](CONTR - **Check for an agreed design first.** For a new feature, command, config option, config format change, or anything likely to exceed about 500 lines, confirm there is an issue where a maintainer agreed on the approach. If there is none, stop and tell your human to open one instead of implementing. - **Stay in scope.** Implement only what the task needs. Do not add unrequested flags, subcommands, options or refactors. Report unrelated problems to your human instead of fixing them in the same PR. -- **Keep the diff lean.** No explanatory comment blocks, no speculative defensive code, no design notes or conversation summaries committed to the repo. Use `maa-types` enums or cite upstream definitions instead of magic numbers. +- **Keep the diff lean.** No explanatory comment blocks, no speculative defensive code, no design notes or conversation summaries committed to the repo. - **Follow existing patterns.** Look for how the codebase already solves a problem (tests included) before inventing a new mechanism. - **Your human reviews before anything is published.** Do not open or push a PR until your human has read the whole diff. Never tick the self-review checkbox in the PR template for them. - **Write the PR description from the template.** Keep it short, fill in the AI assistance section honestly, and do not paste long generated summaries.