Code Review Guidelines in CONTRIBUTING.md

Writing Code Review Guidelines

Clear code review expectations benefit both reviewers and contributors. They reduce friction, speed up the review process, and maintain consistent quality.

For Contributors (PR Authors)

Before requesting review:

• Self-review your own PR first
• Ensure all CI checks pass
• Write a clear PR description explaining what and why
• Keep PRs focused: one feature or fix per PR
• Add screenshots for UI changes

During review:

• Respond to all feedback, even if just to acknowledge
• Ask for clarification if feedback is unclear
• Do not take feedback personally -- it is about the code
• Push fixes as new commits during review (squash at merge)

For Reviewers

Review priorities:

1. Correctness -- Does the code do what it claims?
2. Security -- Are there vulnerabilities?
3. Performance -- Are there unnecessary inefficiencies?
4. Readability -- Can the next developer understand this?
5. Style -- Does it follow project conventions?

Feedback etiquette:

# Good feedback
"Consider using a Map here instead of an Object for O(1) lookups
since the keys are dynamic user IDs."

# Poor feedback
"This is wrong. Use a Map."

Approval Criteria

• All CI checks pass
• At least one maintainer approval (two for breaking changes)
• No unresolved conversations
• Documentation updated if behavior changes
• Test coverage maintained or improved

Turnaround Time

Set expectations: "Maintainers aim to provide initial review within 3 business days. Complex PRs may take longer."

Stale PRs

Define when a PR is considered stale and what happens: "PRs with no activity for 30 days will be marked stale. After 14 more days, they will be closed. You can always reopen or submit a new PR."