Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
61 lines (41 loc) · 3.75 KB

CONTRIBUTING.md

File metadata and controls

61 lines (41 loc) · 3.75 KB
Raw

Contributing / 贡献指南

Thanks for helping improve Agent Skill Doctor. Bug fixes, rule ideas, tests, documentation, and compatibility improvements are welcome.

感谢你参与改进 Agent Skill Doctor。我们欢迎 Bug 修复、规则建议、测试、文档和兼容性改进。

Before you start / 开始之前

  • Search existing issues and pull requests to avoid duplicate work. / 请先搜索已有 Issue 和 PR，避免重复工作。
  • Use the bug or rule-proposal issue form when applicable. / Bug 或新规则建议请使用对应模板。
  • For broad or behavior-changing work, open an issue before implementation. / 大范围或会改变现有行为的改动，请先开 Issue 讨论。
  • Do not disclose vulnerabilities in a public issue; follow SECURITY.md. / 请勿在公开 Issue 中披露漏洞，参见 SECURITY.md。

Development setup / 开发环境

Agent Skill Doctor supports Python 3.10 and newer.

Agent Skill Doctor 支持 Python 3.10 及以上版本。

python -m venv .venv
python -m pip install --upgrade --editable ".[dev]"
python -m pytest
python -m build
skill-doctor skills/skill-doctor --fail-on never

Activate .venv using the command for your shell before installing. Please run the tests and smoke check before submitting a pull request.

安装前请使用当前 Shell 对应的命令激活 .venv。提交 PR 前请运行测试和冒烟检查。

Contribution guidelines / 改动要求

  • Keep changes focused and avoid unrelated formatting or refactors. / 保持改动聚焦，避免无关格式化或重构。
  • Preserve deterministic, offline static analysis: scanning a target Skill must not execute or import its code. / 保持确定性、离线的静态分析；扫描目标 Skill 时不得执行或导入其代码。
  • Maintain Python 3.10 compatibility and avoid new runtime dependencies unless they provide clear value. / 保持 Python 3.10 兼容；除非收益明确，否则不要增加运行时依赖。
  • Add or update tests for behavior changes, including regression tests for bug fixes. / 行为变化必须补充测试，Bug 修复应包含回归测试。
  • Keep user-facing output actionable and avoid exposing secrets in findings or fixtures. / 面向用户的输出应可操作，finding 和 fixture 中不得泄露敏感信息。

Adding or changing a rule / 新增或修改规则

A rule contribution should include:

规则贡献应包含：

  • A stable rule ID, documented scope, and severity. / 稳定的规则 ID、明确的检测范围和严重级别。
  • A concise message and practical remediation. / 简洁的提示和可执行的修复建议。
  • Positive and negative test cases, including likely false-positive boundaries. / 正反测试用例，并覆盖常见误报边界。
  • Updated rule documentation and examples where relevant. / 按需更新规则文档与示例。
  • No execution of target files, shell commands, or network requests. / 不执行目标文件、Shell 命令或网络请求。

Pull requests / 提交 PR

  1. Create a focused branch and make the smallest complete change. / 创建独立分支，并完成最小且完整的改动。
  2. Run the checks above and record relevant results in the PR. / 运行上述检查，并在 PR 中填写相关结果。
  3. Complete the PR template, link related issues, and explain any compatibility impact. / 填写 PR 模板、关联 Issue，并说明兼容性影响。
  4. Address review feedback with additional commits; maintainers may squash when merging. / 使用后续提交处理评审意见；维护者合并时可能进行 squash。

By contributing, you agree that your contribution is licensed under the repository's MIT License.

提交贡献即表示你同意按本仓库的 MIT License 授权该贡献。