docs: improve contributor guidance (#3097)

2026-08-27 16:31:38 +00:00
parent e0f921e20d
commit 6cc2837f64
8 changed files with 100 additions and 3 deletions
@@ -15,6 +15,13 @@ Review the current changes in the codebase (Go backend + Vite/React SPA monorepo

 Start from intent and evidence: read the spec/task first when available, then changed tests before production code. Tests reveal the expected behavior and whether the change is actually verified.

+### Architecture discussion gate
+
+For a large architectural change, require a linked issue with maintainer
+discussion before the PR opens. If the issue or discussion is missing, report a
+blocker. Prefer one logical change and a small diff because this limits risk and
+maintainer burden.
+
 ## Available skills

 - **`/tdd`** — Recommend when flagging untested logic. The author can use this to add tests.
@@ -71,6 +71,12 @@ explicitly requests task tracking.
   when the user explicitly requests separate PRs. Use `--draft` if requested,
   otherwise create as ready-for-review.

+   **Architecture and scope gate:** Before running any PR creation command, check
+   large changes for a linked issue with maintainer discussion. If it is missing,
+   stop and report the blocker. Do not open a PR to start the discussion. Prefer
+   one logical change and the smallest practical diff; split unrelated cleanup,
+   refactoring, and feature work into separate PRs.
+
   **PR title** must follow Conventional Commits format (see `/commit` for full rules). CI validates via `pr-title.yml` — the PR title becomes the squash-merge commit used for release notes.

   **PR body** must be built from `.github/pull_request_template.md`; fail fast if it is missing. Read the whole template before writing the body. Treat HTML comments as authoring instructions for the agent, not as output:
@@ -8,6 +8,19 @@ SUMMARY (required)
  Lead with the problem or goal, end with the outcome.
  Say WHY, not what. No filler phrases ("This PR...", "In order to...", "As part of...").

+LANGUAGE
+  Write the PR title, body, captions, and review-facing prose in English.
+  Translate non-English task text before recording it. Do not include the original wording in the PR body.
+  Keep non-English text only for intentional product localization or exact product data required by the diff.
+  Keep the surrounding explanation in English.
+
+ARCHITECTURE AND SCOPE
+  If the change is large or architectural, require a linked issue with maintainer discussion before opening the PR.
+  Large changes include new subsystems, public API or protocol changes, persistence changes, new execution boundaries,
+  authentication or permission-model changes, and cross-cutting changes across subsystems.
+  If the issue or discussion is missing, stop and report the blocker. Do not open a PR to start the discussion.
+  Prefer one logical change and the smallest practical diff. Split unrelated cleanup, refactoring, and feature work.
+
 IMPORTANT CHANGES (optional)
  Include only for significant architectural changes. Skip for small or straightforward changes.
  Very short bullet list. Each bullet says WHAT changed and why (very short).
@@ -52,6 +65,8 @@ RULES

 ## Checklist

+- [ ] If this is a large architectural change, I discussed the direction in a linked issue before opening this PR.
+- [ ] This PR contains one logical change; unrelated work is split into separate PRs.
 - [ ] I have performed a self-review of my code.
 - [ ] I have manually tested my changes and they work as expected.
 - [ ] My changes have tests that cover the new functionality and edge cases.
@@ -58,6 +58,12 @@ Architecture notes and per-area conventions live alongside the code they describ
 - Lean on the dependencies already in the project before writing your own implementation or adding packages. Do not assume a library lacks a capability without checking its documentation and types.
 - Make architectural decisions for the long term. Do not accept a stopgap that only works for now and is meant to be replaced later.

+### Engineering language
+
+Use English for all engineering text, including specs, plans, PRs, docs,
+comments, and docstrings. Translate non-English input before recording it.
+Only required product localization and product data can use another language.
+
 ### Commit Conventions (enforced by CI)

 Commits to `main` **must** follow [Conventional Commits](https://www.conventionalcommits.org/) (`type: description`). PRs are squash-merged - the PR title becomes the commit, validated by CI. Changelog is auto-generated from these via git-cliff (`cliff.toml`). See `.agents/skills/commit/SKILL.md` for allowed types and examples.
@@ -10,10 +10,32 @@ Join our [Discord](https://discord.gg/gWdCPGcFCD) to ask questions, discuss idea

 You must understand the code you submit. You're welcome to use AI tools to help write code, but every PR will be reviewed by a human maintainer and the feature you're contributing should be manually tested. If you can't explain what your code does and why, it's not ready to submit.

+## Contribution language
+
+Use English for issues, PRs, documentation, specifications, plans, code
+comments, and review discussion. Product localization values can use their
+target language. Keep the surrounding explanation in English.
+
+## Before opening a PR
+
+Discuss a large architectural change in an issue before implementation or PR
+creation. A large change includes a new subsystem, a public API or protocol
+change, a persistence or data-model change, a new execution boundary, an
+authentication or permission-model change, or a cross-cutting change across
+subsystems.
+
+Describe the problem, proposed direction, affected boundaries, alternatives,
+and migration or compatibility risks in the issue. Wait until maintainers have
+discussed the direction before opening the PR. Link the issue from the PR. If
+an agent is preparing the change, it must stop and report missing discussion
+instead of opening the PR.
+
 ## How to Contribute

 1. **Fork and branch.** Create a feature branch from `main`.
-2. **Keep PRs focused.** One logical change per PR. Small PRs get reviewed faster.
+2. **Keep PRs small and focused.** Keep one logical change per PR. Split
+   unrelated cleanup, refactoring, and feature work. Smaller PRs reduce the
+   risk surface, make review easier, and reduce maintainer burden.
 3. **Update public docs when behavior changes.** User-facing docs live in `docs/public/**`. If your change affects CLI commands, config keys, install/deploy flows, workflows, executors, APIs, screenshots, or user-facing terminology, update the relevant public docs in the same PR. See the [public docs contribution guide](docs/public/README.md) when editing navigation or adding a page.
 4. **Test your changes.** Run `make fmt` first, then `make typecheck test lint` before submitting. Manually verify that your feature works end-to-end, and add screenshots or recordings to the PR if it has a UI component. **If your change touches any UI files (anything under `apps/web/`), you must add or update Playwright e2e tests in `apps/web/e2e/` to prevent regressions.** Run them with `make test-e2e`. See [docs/test_e2e_web.md](docs/test_e2e_web.md) for patterns and fixtures.

@@ -32,6 +32,8 @@ Please create and open a Pull Request for the current branch using the GitHub CL
   - Related Issues section with issue links

 5. **Create the PR:**
+   - Before creating the PR, read and follow the target repository's contribution
+     guide and agent instructions
   - Use 'gh pr create' command with appropriate flags
   - Set the title and body based on the generated description
   - Set appropriate labels if needed
@@ -47,4 +49,4 @@ Please create and open a Pull Request for the current branch using the GitHub CL
 - Ensure you're on the correct branch before creating the PR
 - Make sure all commits are pushed to the remote
 - Verify the base branch is correct (usually 'main' or 'develop')
- Check that CI/CD checks are configured to run
+- Check that CI/CD checks are configured to run
@@ -12,7 +12,35 @@ Kandev combines a Go server and native launcher, a Vite/React web client, a Type
 1. Run `make bootstrap` once in a fresh checkout.
 2. Use `make dev` for normal full-stack work.
 3. Find the owning backend, web, CLI, desktop, or runtime boundary before editing.
-4. Run focused checks, update public docs, and leave a small reviewable diff.
+4. Open an issue before a large architectural change and discuss its direction
+   with maintainers before opening a PR.
+5. Keep one logical change in a small PR. Split unrelated work.
+6. Run focused checks, update public docs, and leave a small reviewable diff.
+
+## Contribution language
+
+Use English for issues, PRs, documentation, specifications, plans, code
+comments, and review discussion. Product localization values can use their
+target language. Keep the surrounding explanation in English.
+
+## Discuss large architectural changes first
+
+Open an issue before you implement or submit a large architectural change. This
+includes a new subsystem, a public API or protocol change, a persistence or
+data-model change, a new execution boundary, an authentication or
+permission-model change, or a cross-cutting change across subsystems.
+
+Describe the problem, proposed direction, affected boundaries, alternatives,
+and migration or compatibility risks in the issue. Wait until maintainers have
+discussed the direction before opening the PR. Link the issue from the PR.
+An agent must stop and report missing discussion instead of opening the PR.
+
+## Keep PRs small
+
+Prefer one logical change and the smallest practical diff. Split unrelated
+cleanup, refactoring, documentation, and feature work into separate PRs.
+Smaller PRs reduce the risk surface, make review easier, and reduce maintainer
+burden.

 ## Set up the repository

@@ -99,6 +127,9 @@ The complete source and Landing build contract is in the [public docs contributi
 ## Review checklist

 - The change has one clear user impact and owning subsystem.
+- Large architectural changes have a linked issue with maintainer discussion
+  before the PR opens.
+- The PR contains one logical change and the smallest practical diff.
 - Wire changes update Go DTOs, TypeScript types/clients, compatibility behavior, and protocol docs together.
 - Persistence changes include fresh-schema and upgrade-path tests.
 - Credentials, external text, shell arguments, URLs, paths, and logs respect their trust boundary.
@@ -18,3 +18,11 @@ The [system README](../templates/system-readme.md),
 [system-design](../templates/system-design.md) templates provide the required
 document shapes.

+## Authoring language
+
+Write all specification, system-design, plan, and work-order files in English.
+Use English for filenames, frontmatter, IDs, titles, headings, prose, examples,
+comments, and results. Translate non-English task input before recording it.
+Do not copy the original wording into an engineering artifact. Keep non-English
+text only for intentional product localization or exact product data required
+by the contract. Keep the surrounding explanation in English.