# Contributing to Pebrel / 贡献指南

Pebrel 1.6 uses the `pebrel` command, Pebrel installation directories, and
`PEBREL_*` environment variables. Legacy configuration and integration identifiers
remain compatibility inputs; follow the [identity migration decision](docs/architecture-decisions.md#adr-0003---pebrel-16-identity-migration)
when changing them. Internal Rust crate and source-directory names remain stable.

## Required reading

- [Architecture and module ownership](docs/architecture.md)
- [Enforced contracts and review rules](docs/project-constraints.md)
- UI changes must also satisfy the **UI 设计约束 / UI design constraints** chapter
  in that document: interaction states, result feedback, hit targets and visual acceptance.
- [Causal note policy](architecture/notes/AGENTS.md) for new non-trivial decisions
- [Legacy decision archive](docs/architecture-decisions.md) for accepted historical context
- [Evidence behind the rules](docs/engineering-evidence.md)
- [Internationalization](docs/internationalization.md) when changing UI text

These rules apply equally to maintainers, outside contributors and coding agents.
They constrain responsibilities and behavior, not personal taste. A demonstrated
problem in a rule is a reason to review the rule, not to conceal or ignore a failure.

## Ways to contribute

- **Report a bug:** use the existing issue form. Include the version/build, OS,
  display scale, relevant settings, minimal steps, expected result and actual result.
  Search existing issues first. Remove tokens, credentials, private paths and command
  history from logs or recordings before sharing them.
- **Propose a feature:** describe the workflow and user need before prescribing an
  implementation. For broad changes, agree on scope before writing a large PR.
- **Translate or improve docs:** follow the language registry/catalog contract;
  preserve named placeholders and review terminology, clipping and fallback. Do not
  mark a language complete merely because English placeholders were copied into it.
- **Fix or test code:** start with a focused regression and an existing module's
  tests. Add fixtures or improve coverage when that is the actual contribution.

No programming contribution is required to be useful. Clear reproduction steps,
native-language review and accessibility feedback also help the project.

## First code contribution

1. Fork the existing `Kuddev/pebrel` repository and create your work branch from the
   PR target branch. See [INSTALL.md](INSTALL.md) for environment prerequisites.
2. Use the pinned Rust toolchain in `rust-toolchain.toml`. Build the actual GPUI
   product, not an accidentally substituted legacy executable:

   ```sh
   cargo build --locked -p nebula --bin pebrel --features gpui-shell
   ```

3. Make the focused change, run the checks below, and open a PR against the agreed
   target. Draft PRs are useful for early design feedback; describe remaining work.
4. Respond to review and rerun affected checks after changes. Maintainers decide
   readiness from the actual evidence, not from checked boxes alone.

Do not include build outputs, local probes, screenshots containing secrets or
unrelated generated files. Preserve third-party license/attribution notices and
identify the source of any externally copied code or assets for license review.

Keep one-off test scripts and probe outputs under `tmp/`; external project checkouts
and investigation notes belong in the reserved `research/`, `reference-projects/`
or `external-probes/` local directories. These are not vendored build dependencies:
do not blanket-ignore `third_party/` or maintained test/diagnostic sources. `docs/`
is private by default; public documentation needs an exact reviewed allowlist entry
in `.gitignore`. Do not publish competitor studies or HTML prototypes by opening a
whole documentation subtree. Ignore rules do not untrack files already in Git;
raise any existing tracked private artifact for an explicit maintainer decision.

## Small, reviewable changes

1. State the user-visible problem and the behavior to preserve. Discuss a new
   cross-layer dependency, persisted format, core abstraction or threading model
   before implementing it. Record significant decisions under the owning path in
   `architecture/notes/`; ordinary fixes do not create a note.
2. Keep one conceptual change per PR. A necessary extraction and its behavior
   tests may accompany the feature; unrelated rewrites and formatting may not.
   The `pr-size` check fails above 1500 changed source lines (docs, lockfiles
   and assets excluded); split instead of asking for an exemption.
3. Put shared rules in their existing authority. UI modules adapt those rules;
   they must not fork persistence, state transitions or domain behavior.
4. Add regression tests that fail for the defect, and test error/cancellation
   paths where relevant. Explain what was actually run and what was not.
5. Fill in the PR template. A green build is necessary, not sufficient: a
   maintainer must also review cohesion, public interfaces, compatibility and cost.

## Local checks

The fast checker requires Python 3.11+ and no third-party Python packages. Use
`python` instead of `python3` on Windows if that is your configured interpreter.
Use the actual target branch commit, not the feature branch's own HEAD, for PR
ratcheting. Run without `--base` for current-tree checks during development.

```sh
python3 scripts/check_architecture.py --base <PR-base-commit>
python3 -m unittest scripts.tests.test_architecture_budgets scripts.tests.test_architecture_dependencies scripts.tests.test_architecture_governance
cargo test --manifest-path tools/i18n-contract/Cargo.toml --locked
cargo test -p nebula-settings
cargo test -p nebula --test file_line_budget
cargo fmt --all -- --check
```

Run affected behavior tests and the appropriate real product checks as well:

```sh
cargo check -p nebula --bin pebrel --features gpui-shell --tests --locked
```

`Full native tests` runs on every PR and merge-group update, and on `main` pushes.
It tests the full workspace on Linux, Windows x64 / ARM64 and both macOS
architectures. New commits cancel obsolete PR runs. Pull requests run tests and
compile checks without building distribution packages. Package validation runs
after matching changes reach `main`, or by explicit manual dispatch; a package
job does not replace the native test suite. These triggers do not configure
required status checks.

GitHub may show **Waiting for approval** for a first-time fork contributor. A
maintainer must inspect the submitted changes and approve that workflow run from
the Actions page before tests start. Pushing more commits does not remove this
GitHub approval requirement; do not run fork code through `pull_request_target`
or give it a write token to work around the wait.

The isolated i18n test compiles production files, not copied implementations. It
does not test real window layout, every OS integration, or the full application.
Existing platform build/package checks still apply. Never turn a metadata-only
compile check into a claim that UI tests or a packaged application were run.

## Review and enforcement

`architecture-contracts`, `lint`, `pr-size`, the five
`Tests (<os>)` jobs and both `Release workspace (<os>)` jobs are required checks
on `main`, together with Code Owner approval; see the
[activation checklist](docs/project-constraints.md#server-side-activation).
Draft and ready pull requests both run all five native platforms and both macOS
release-profile compile checks. The required lint job validates the event and
selects the matrix before requesting platform runners. Every required check must
succeed before merging. Marking a draft ready without changing its commits does
not repeat the matrix; source updates and reopen events run it again. Native CI
uses pinned `cargo-nextest` for unit and
integration tests, followed by `cargo test --doc` with the same workspace features;
the production feature graph and release workspace are still checked separately.
PRs restore Cargo caches without uploading merge-ref snapshots. The default branch
publishes reusable snapshots per dependency/toolchain configuration; a cache hit
never skips current-commit tests. Downloads are shared between architectures of
the same OS, while compiled targets remain isolated by architecture and SDK.
Local hooks are convenient, but bypassable; they are not the enforcement boundary.
Submitting a workflow or `CODEOWNERS` file does not configure server-side rules.

Do not silence a failing contract by increasing a budget, removing test coverage,
compressing code, adding `continue-on-error`, or broadening an exclusion. If the
contract is wrong, submit a focused policy fix with a reproducer and both positive
and negative tests. Review a justified policy change separately from unrelated
feature work; there is no routine `--skip-architecture` option.

## 中文摘要

- 先读架构图、工程合同和决策记录；按职责拆分，不按行号切片。
- 一个 PR 只做一件事；改动超过 1500 行源码（不计文档、lockfile、资源）`pr-size` 会失败，请拆分。
- Draft 和 Ready PR 都先运行必需的格式检查和矩阵规划，再执行五平台原生测试及两项 macOS release 编译检查；十项必需检查全绿才能合并。提速使用共享缓存与并行测试，不省略平台或 doctest。
- 2000 行是现有仓库的防灾上限，800 行只提示审查，不是“大厂标准”。
- 普通功能 PR 不得增加存量债务；有问题的规则可以修订，但要有反例、测试和维护者审批。
- 新增核心抽象、依赖方向、持久化或线程模型改变要先说明设计，不强迫每个小修复写 ADR。
- 修改热路径要给出成本证据；不能为了“可扩展”增加没有实际用途的框架。
- PR 要附实际测试结果；本地钩子和勾选框不代替服务端必需检查与人工评审。