Pull request review process

Pull requests submitted to Zulip go through a rigorous review process, which is designed to ensure that we are building a high-quality product with a maintainable codebase. This page describes the stages of review your pull request may go through, and offers guidance on how you can help keep your pull request moving along.

Labels for managing the stages of pull request review

In the Zulip server/web app repository (zulip/zulip), we use GitHub labels to help everyone understand where a pull request is in the review process. These labels are noted below, alongside their corresponding pull-request stage. Each label is removed by the reviewer for that stage when they have no more feedback on the PR and consider it ready for the next stage of review.

Sometimes, a label may also be removed because significant changes by the contributor are required before the PR ready to be reviewed again. In that case, the contributor should post a comment mentioning the reviewer when the changes have been completed, unless the reviewer requested some other action.

Stages of a pull request review

This section describes the stages of the pull request review process. Each stage may require several rounds of iteration. Don't feel daunted! Not every PR will require all the stages described, and the process often goes quite quickly for smaller changes that are clearly explained.

Product review. Oftentimes, seeing an initial implementation will make it clear that the product design for a feature needs to be revised, or that additional changes are needed. The reviewer may therefore ask you to amend or change the implementation. Some changes may be blockers for getting the PR merged, while others may be improvements that can happen afterwards. Feel free to ask if it's unclear which type of feedback you're getting. (Follow-ups can be a great next issue to work on!)

Your PR might be assigned the product review label at this stage, or later in the review process as questions come up. You can also add this label yourself if appropriate. If doing so, be sure to clearly outline the product questions that need to be addressed.
QA. If your PR makes user-facing changes, it may get a round of testing without reference to the code. You will get feedback on any user-facing bugs in the implementation. To minimize the number of review round-trips, make sure to thoroughly test your own PR prior to asking for review.

Your PR might be assigned the QA needed label at this stage, or later on if re-testing is required.
Initial code review. All PRs will go through one or more rounds of code review. Your code may initially be reviewed by other contributors. This helps us make good use of project maintainers' time, and helps you make progress on the PR by getting quick feedback. A project maintainer may leave a comment asking someone with expertise in the area you're working on to review your work.
Maintainer code review. In this phase, a Zulip maintainer will do a thorough review of your proposed code changes. Your PR may be assigned the maintainer review label at this stage.
Documentation review. If your PR includes documentation changes, those changes will require review. This generally happens fairly late in the review process, once the UI and the code are unlikely to undergo major changes. Maintainers may indicate that a PR is ready for documentation review by adding a help center review and/or api docs review label, and mentioning a documentation maintainer in the comments.
Integration review. This is the final round of the review process, generally done by @timabbott for server and web app PRs. A maintainer will usually assign the integration review label when the PR is ready for this phase.

How to help move the review process forward

If there are no comments on your PR for a week after you submit it, you can check again to make sure that it's ready for review, and then post a quick comment to remind Zulip's maintainers to take a look at your work. Consider also asking for a review in the Zulip development community.

After that, the key to keeping your review moving through the review process is to:

Address all the feedback to the best of your ability.
Make it clear when the requested changes have been made and you believe it's time for another look.
Make it as easy as possible to review the changes you made.

In order to do this, when you believe you have addressed the previous round of feedback on your PR as best you can, post a comment asking reviewers to take another look. Your comment should make it easy to understand what has been done and what remains by:

Summarizing the changes made since the last review you received. Be clear about which issues you've resolved (and how!).
Highlighting remaining questions or decisions, with links to any relevant threads in the Zulip development community. It should be clear which feedback you haven't addressed yet.
Providing updated screenshots and information on manual testing if appropriate.

The easier it is to review your work, the more likely you are to receive quick feedback.

Follow-ups

Sometimes reviewers will comment on "follow-ups" to your pull request. A follow-up is something that can be done separately from the changes in the current pull request, because it's tangential to the current changes, or would be the next task to do once the current changes are completed.

You should prioritize completing the current pull request over working on follow-ups. However, you are expected to manage follow-ups to your work:

If possible, it's best to complete follow-ups as soon as you are done with the current pull request. That way, both you and reviewers have the context for the changes fresh in mind.
If you don't expect to have time to complete a follow-up soon (or aren't sure if you will), please file an issue to track it. Include a description of the required changes, and a link to the comment where the follow-up was discussed. You can copy-paste the issue description from the prior discussion, but be sure that what you write makes sense without needing to refer to the original thread.