From ecec55aca416bc0fe3e6d104e2cac865b0c12f6a Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Sat, 28 Mar 2026 10:44:02 -0700
Subject: [PATCH] docs: add contribution guide and PR template (#163)

---
 .github/pull_request_template.md | 29 +++++++++++++++
 CONTRIBUTING.md                  | 62 ++++++++++++++++++++++++++++++++
 README.md                        |  2 ++
 3 files changed, 93 insertions(+)
 create mode 100644 .github/pull_request_template.md
 create mode 100644 CONTRIBUTING.md

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 00000000..b69e2dcc
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,29 @@
+## Summary
+
+Describe the user-visible change.
+
+## Screenshots
+
+- Add screenshots or a screen recording for any new or changed UI behavior.
+- If there is no visual change, say `No visual change`.
+
+## Testing
+
+- [ ] `pnpm lint`
+- [ ] `pnpm typecheck`
+- [ ] `pnpm test`
+- [ ] `pnpm build`
+- [ ] Added or updated high-quality tests that would catch regressions, or explained why tests were not needed
+
+## AI Review Report
+
+Summarize the code review you ran with your AI coding agent. Include the main risks it checked, what it flagged, and what you changed or verified as a result.
+Confirm that the review explicitly checked cross-platform compatibility for macOS, Linux, and Windows, including shortcuts, labels, paths, shell behavior, and any Electron-specific platform differences touched by this PR.
+
+## Security Audit
+
+Provide a basic security audit summary from your AI coding agent. Call out any input handling, command execution, path handling, auth, secrets, dependency, or IPC risks that were reviewed, plus any follow-up needed.
+
+## Notes
+
+Call out any platform-specific behavior, risks, or follow-up work.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..f9fa8de7
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,62 @@
+# Contributing to Orca
+
+Thanks for contributing to Orca.
+
+## Before You Start
+
+- Keep changes scoped to a clear user-facing improvement, bug fix, or refactor.
+- Orca targets macOS, Linux, and Windows. Avoid platform-specific assumptions in shortcuts, labels, and file paths.
+- For keyboard shortcuts, use runtime platform checks in renderer code and `CmdOrCtrl` in Electron menu accelerators.
+- For shortcut labels, show `⌘` and `⇧` on macOS, and `Ctrl+` and `Shift+` on Linux and Windows.
+- For file paths, use Node or Electron path utilities such as `path.join`.
+
+## Local Setup
+
+```bash
+pnpm install
+pnpm dev
+```
+
+## Branch Naming
+
+Use a clear, descriptive branch name that reflects the change.
+
+Good examples:
+
+- `fix/ctrl-backspace-delete-word`
+- `feat/shift-enter-newline`
+- `chore/update-contributor-guide`
+
+Avoid vague names like `test`, `misc`, or `changes`.
+
+## Before Opening a PR
+
+Run the same checks that CI runs:
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+Add high-quality tests for behavior changes and bug fixes. Prefer tests that would actually catch a regression, not shallow coverage that only exercises the happy path.
+
+If your change affects UI or interaction behavior, verify it on the platforms it could impact.
+
+## Pull Requests
+
+Each pull request should:
+
+- explain the user-visible change
+- stay focused on a single topic when possible
+- include screenshots or screen recordings for new UI or behavior changes
+- include high-quality tests when behavior changes or bug fixes warrant them
+- include a brief code review summary from your AI coding agent that explicitly checks cross-platform compatibility, plus a basic security audit summary
+- mention any platform-specific behavior or testing notes
+
+If there is no visual change, say that explicitly in the PR description.
+
+## Release Process
+
+Version bumps, tags, and releases are maintainer-managed. Do not include release version changes in a normal contribution unless a maintainer asks for them.
diff --git a/README.md b/README.md
index e0d7d4bb..bcfafb69 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,8 @@ Grab a release from https://www.orcabuild.ai/ or download from the GH release pa
 
 ## Developing
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for branch naming, PR expectations, and required checks.
+
 ### Install
 
 ```bash