PR Best Practices

PR Title

We recommend using conventional commit message for PR titles. It will make reviewing change logs more visually friendly.

PR Description

With a clear PR title, you might think you don't need any PR description. This could be true, especially for the immediate reviewers who have context about your PR. But we still recommend having PR descriptions for the following reasons:

• Even for reviewers with the right context, it might be good to remind them what your changes are about.
• Provide the context for non-immediate reviewers, such as readability reviewers or people reviewing your promo packet.
• A place to highlight the challenges/complexity you're facing or the impact of your PR. The summary will help yourself and others to easily reference what kind of contributions you have done.

Small Coherent PRs

Be mindful about your PR size. The smaller and more coherent a PR is, the easier it is for people to review and get approval.

Long PR Comments

If you find yourself stuck in a long PR comment thread, it probably means there is some alignment that should have happened before the PR. Please take time to make that happen first. Sometimes it means you need to close your current PR and start anew. The sooner you can take action, the less time you would feel wasted. Often insisting on closing a long PR thread will end up costing more time and a bitter taste in people's mouth.

Readability

Readability review is opt-in based at the moment, and probably will stay that way in the foreseeable future. But we recommend always adding the proper readability review group for your PRs unless you have that already. See existing readability groups in https://github.com/abcxyz/readability.