PR Guidelines

1. Keep them small

It's very tempting to rewrite, refactor, reformat, or tackle multiple things in a single PR. The best developers resist this temptation.

Keep PRs small and focused. Actively look for ways to split work into smaller, incremental PRs.

2. Fulfill only one responsibility

One Pull Request should aim to fulfill one single responsibility.

If the responsibility or feature is big, try breaking it down into smaller components so they can be reviewed easily.

It's ok to include unrelated smaller fixes like typos, but mention them in description.

3. Perform a self-review & Claude Code review

When you create a PR, Claude Code should automatically run and leave comments. Make sure you go through them, resolve or reply to them before you add a human reviewer.

P.S. we will improve Claude Code review prompt as we go along.

4. Meaningful title and description (with Linear Issue ID)

Include Linear issue ID e.g. PEA-951 in the title to automatically link to Linear.

Example: PEA-951: Add validation for checkout email field

Title and description is the first place where you can inform your teammates about the changes. PR titles can be traced via searching so adding some key information on the title would be useful.

Description of a PR should always be prepared with the same attention, whether the PR has a small or huge change. Reviewing the pull request requires changing the context for the reviewer.

Screenshots, videos, or demos (when applicable) can be added.

5. Linting & testing

Make sure the code is formatted and linted according to the repository requirements.

If your changes can be covered by unit tests, ensure they are added and run before submitting the PR.

6. Language & attitude

Both reviewers and the author should be polite in the comments.

7. Merge process

If the repo has a staging branch, create PR to merge to staging branch. We have a GitHub Action to enforce this.

If the merge is a hotfix to fix a bug in production, merge it to main and staging.