docs: 将 CONTRIBUTING.md 和 SECURITY.md 翻译为中文
Some checks failed
CI / build-check-test (push) Has been cancelled
Some checks failed
CI / build-check-test (push) Has been cancelled
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
103
CONTRIBUTING.md
103
CONTRIBUTING.md
@@ -1,102 +1,97 @@
|
||||
# Contributing to pi
|
||||
# 贡献指南
|
||||
|
||||
This guide exists to save both sides time.
|
||||
本指南旨在为双方节省时间。
|
||||
|
||||
## Philosophy
|
||||
## 设计理念
|
||||
|
||||
First things first: **pi's core is minimal**.
|
||||
首先明确一点：**SproutClaw 的核心保持精简**。
|
||||
|
||||
If your feature does not belong in the core, it should be an extension. PRs that bloat the core will likely be rejected.
|
||||
如果你的功能不属于核心，它应该以扩展的形式实现。会让核心臃肿的 PR 大概率会被拒绝。
|
||||
|
||||
Pi's core exists to be minimal and to be extensible so that it can be influenced and manipulated by extensions. Even hook points for extensions however should be well considered and discussed to avoid adding unmaintainable bloat and complex interactions.
|
||||
SproutClaw 的核心存在的意义在于精简且可扩展，以便扩展能够影响和定制其行为。即便是扩展的 hook 点也需要经过充分考量和讨论，避免引入难以维护的冗余代码和复杂交互。
|
||||
|
||||
## The One Rule
|
||||
## 唯一准则
|
||||
|
||||
**You must understand your code.** If you cannot explain what your changes do and how they interact with the rest of the system, your PR will be closed.
|
||||
**你必须理解自己提交的代码。** 如果你无法解释你的改动做了什么、以及它与系统其他部分如何交互，你的 PR 将被关闭。
|
||||
|
||||
Using AI to write code is fine. Submitting AI-generated slop without understanding it is not.
|
||||
使用 AI 辅助编写代码没有问题，但在不理解代码的情况下直接提交 AI 生成的内容是不被接受的。
|
||||
|
||||
If you use an agent, run it from the `pi` root directory so it picks up `AGENTS.md` automatically. Your agent must follow the rules and guidelines in that file.
|
||||
如果你使用 Agent，请在 `sproutclaw` 根目录运行，这样它会自动读取 `AGENTS.md`。你的 Agent 必须遵循该文件中的规则和指南。
|
||||
|
||||
## Contribution Gate
|
||||
## 贡献门槛
|
||||
|
||||
All issues and PRs from new contributors are auto-closed by default.
|
||||
来自新贡献者的 issue 和 PR 默认会被自动关闭。
|
||||
|
||||
Issues submitted Friday through Sunday are not guaranteed to be reviewed. If something is urgent, ask on Discord: https://discord.com/invite/3cU7Bz4UPx
|
||||
周五至周日提交的 issue 不保证会被审查。如有紧急问题，请在内部联系维护者。
|
||||
|
||||
Maintainers review auto-closed issues daily and reopen worthwhile ones. Issues that do not meet the quality bar below will not be reopened or receive a reply.
|
||||
维护者会每日审查被自动关闭的 issue，并重新开放值得处理的内容。不符合以下质量标准的 issue 将不会被重新开放或收到回复。
|
||||
|
||||
Approval happens through maintainer replies on issues:
|
||||
审批通过由维护者在 issue 中回复：
|
||||
|
||||
- `lgtmi`: your future issues will not be auto-closed
|
||||
- `lgtm`: your future issues and PRs will not be auto-closed
|
||||
- `lgtmi`：你未来提交的 issue 将不再被自动关闭
|
||||
- `lgtm`：你未来提交的 issue 和 PR 将不再被自动关闭
|
||||
|
||||
`lgtmi` does not grant rights to submit PRs. Only `lgtm` grants rights to submit PRs.
|
||||
`lgtmi` 不授予提交 PR 的权限，只有 `lgtm` 才授予该权限。
|
||||
|
||||
## Quality Bar For Issues
|
||||
## Issue 质量标准
|
||||
|
||||
If you open an issue, you must use one of the two GitHub issue templates.
|
||||
提交 issue 时，必须使用两个 GitHub issue 模板之一。
|
||||
|
||||
If you open an issue, keep it short, concrete, and worth reading.
|
||||
提交的 issue 应简洁、具体、有阅读价值：
|
||||
|
||||
- Keep it concise. If it does not fit on one screen, it is too long.
|
||||
- Write in your own voice (do not use an LLM to generate text, if you must, follow up with a clearly AI labeled comment).
|
||||
- State the bug or request clearly.
|
||||
- Explain why it matters.
|
||||
- If you want to implement the change yourself, say so.
|
||||
- 保持简短。如果超过一屏，就太长了。
|
||||
- 用自己的语言表达（不要用 LLM 生成文本；如果必须，请在后续评论中明确标注为 AI 生成）。
|
||||
- 清晰说明 bug 或需求。
|
||||
- 解释其重要性。
|
||||
- 如果你希望自己来实现，请说明。
|
||||
|
||||
If the issue is real and written well, a maintainer may reopen it, reply `lgtmi`, or reply `lgtm`.
|
||||
如果 issue 真实且表述良好，维护者可能会重新开放、回复 `lgtmi` 或回复 `lgtm`。
|
||||
|
||||
## Blocking
|
||||
## 封禁规则
|
||||
|
||||
If you ignore this document twice, or if you spam the tracker with agent-generated issues, your GitHub account will be permanently blocked.
|
||||
如果你两次无视本文档，或通过 Agent 批量刷 issue，你的账号将被永久封禁。
|
||||
|
||||
If you send a large volume of issues through automation, your GitHub account will be permanently blocked. No taksies backsies.
|
||||
如果你通过自动化手段大量提交 issue，你的账号将被永久封禁，且不可申诉。
|
||||
|
||||
## Before Submitting a PR
|
||||
## 提交 PR 前
|
||||
|
||||
Do not open a PR unless you have already been approved with `lgtm`.
|
||||
未获得 `lgtm` 批准前，请勿提交 PR。
|
||||
|
||||
Before submitting a PR:
|
||||
提交 PR 前，请先执行：
|
||||
|
||||
```bash
|
||||
npm run check
|
||||
./test.sh
|
||||
```
|
||||
|
||||
Both must pass.
|
||||
两项均须通过。
|
||||
|
||||
Do not edit `CHANGELOG.md`. Changelog entries are added by maintainers.
|
||||
不要修改 `CHANGELOG.md`，更新日志条目由维护者添加。
|
||||
|
||||
If you are adding a new provider to `packages/ai`, see `AGENTS.md` for required tests.
|
||||
如果你要在 `packages/ai` 中添加新的 provider，请参阅 `AGENTS.md` 中关于必要测试的说明。
|
||||
|
||||
## Questions?
|
||||
## 有疑问？
|
||||
|
||||
Ask on [Discord](https://discord.com/invite/nKXTsAcmbT).
|
||||
请联系项目维护者。
|
||||
|
||||
## FAQ
|
||||
## 常见问题
|
||||
|
||||
### Why are new issues and PRs auto-closed?
|
||||
### 为什么新 issue 和 PR 会被自动关闭？
|
||||
|
||||
pi receives more issues than the maintainers can responsibly review in real time. Many reports do not meet the quality bar in this guide or do not follow CONTRIBUTING.md. Some are slung at the repository mindlessly via an agent instead of being reviewed and shaped by the person submitting them. Auto-closing creates a buffer so maintainers can review the tracker on their own schedule and reopen the issues that meet the quality bar.
|
||||
SproutClaw 收到的 issue 数量超过维护者能够实时处理的上限。许多报告不符合本指南的质量标准，或者是通过 Agent 随意提交而未经本人审查和整理的。自动关闭机制让维护者可以按自己的节奏审查，并重新开放符合质量要求的 issue。
|
||||
|
||||
### Why are weekend issues lower priority?
|
||||
### 为什么周末的 issue 优先级较低？
|
||||
|
||||
We triage the tracker during working hours. That means more issues can accumulate over the weekend. Anything submitted Friday through Sunday may be missed or given lower priority in the Monday review queue. If a problem is urgent, ask on Discord and include the short version, a repro, and the relevant logs.
|
||||
维护者在工作时间处理 issue。周末可能积累更多未处理内容，周五至周日提交的 issue 可能在周一审查时被遗漏或优先级降低。如有紧急问题，请直接联系维护者并附上简要描述、复现步骤和相关日志。
|
||||
|
||||
### Why do some issues get no reply?
|
||||
### 为什么有些 issue 没有收到回复？
|
||||
|
||||
A reply is maintenance work too. Low-signal issues, unclear reports, duplicates, and issues that do not follow this guide may be closed without discussion. This keeps time available for reproducible bugs, thoughtful requests, and contributors who have done the work to make their report actionable.
|
||||
回复本身也是一种维护成本。低质量 issue、表述不清的报告、重复 issue 以及不遵循本指南的 issue 可能被直接关闭而不作说明。这样可以将时间留给可复现的 bug、深思熟虑的需求，以及真正用心整理报告的贡献者。
|
||||
|
||||
### Why not let AI triage everything?
|
||||
### 为什么不用 AI 来做所有分类工作？
|
||||
|
||||
AI can help group duplicates, summarize reports, and spot missing information. It is not trusted to make final maintainer decisions. Polished AI-generated issues can still be wrong, misleading, or expensive to investigate. Human review remains the final gate.
|
||||
AI 可以帮助归纳重复内容、汇总报告、发现缺失信息，但不被信任来做最终的维护决策。经过润色的 AI 生成 issue 仍然可能是错误的、有误导性的，或需要大量时间排查。人工审查始终是最终把关环节。
|
||||
|
||||
### Is this hostile to contributors?
|
||||
### 这对贡献者是否过于苛刻？
|
||||
|
||||
No. It is a guardrail against burnout and tracker spam. Short, concrete, reproducible issues are welcome. Thoughtful contributions are welcome. Automated slop, entitlement, and large volumes of low-effort reports are not.
|
||||
|
||||
## Where can I learn about plans?
|
||||
|
||||
Earendil uses RFCs to discuss larger changes. Not all of them are public, but
|
||||
quite a few are. They can be found at [rfc.earendil.com](https://rfc.earendil.com/keyword/pi/).
|
||||
不是。这是防止维护者精力耗尽和 issue 刷屏的保护机制。简洁、具体、可复现的 issue 是受欢迎的，有深度的贡献同样受欢迎。自动化生成的低质量内容、无理取闹以及大量低价值报告则不被接受。
|
||||
|
||||
Reference in New Issue
Block a user