snapshot of https://github.com/zulip/zulip.git @ 48c69911c7dd4e03b20552eb3bd77ad8151c1357 (2026-09-15)

docs/contributing/review-process.md

@@ -0,0 +1,135 @@
+# 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`](https://github.com/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.
+
+1. **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](https://github.com/zulip/zulip/pulls?q=is%3Aopen+is%3Apr+label%3A%22product+review%22)
+   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.
+
+2. **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](../contributing/code-reviewing.md#manual-testing)
+   your own PR prior to asking for review.
+
+   Your PR might be assigned the [QA
+   needed](https://github.com/zulip/zulip/pulls?q=is%3Aopen+is%3Apr+label%3A%22QA+needed%22)
+   label at this stage, or later on if re-testing is required.
+
+3. **Initial code review.** All PRs will go through one or more rounds of code
+   review. Your code may initially be [reviewed by other
+   contributors](../contributing/code-reviewing.md). 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.
+
+4. **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](https://github.com/zulip/zulip/pulls?q=is%3Aopen+is%3Apr+label%3A%22maintainer+review%22)
+   label at this stage.
+
+5. **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](https://github.com/zulip/zulip/pulls?q=is%3Aopen+is%3Apr+label%3A%22help+center+review%22)
+   and/or [api docs
+   review](https://github.com/zulip/zulip/pulls?q=is%3Aopen+is%3Apr+label%3A%22api+docs+review%22)
+   label, and mentioning a documentation maintainer in the comments.
+
+6. **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](https://github.com/zulip/zulip/pulls?q=is%3Aopen+is%3Apr+label%3A%22integration+review%22)
+   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](../contributing/code-reviewing.md#asking-for-a-code-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](https://zulip.com/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:
+
+1. 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.
+
+1. 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.