Strategies for Responding to Pull Request Reviews: Clarifying Intentions, Streamlining Feedback, and Handling Preference-Based Changes

They might also be waiting on input from other users or maintainers on whether the intention and direction of your PR makes sense. If you know of people who could help clarify any of this, please bring the PR to their attention. The current state of the PR is frequently not clearly communicated, so please don't hesitate to ask about it if it's unclear to you. It's also possible for the reviewer to not be convinced that your PR is necessary or that the method you've chosen is the right one. Please explain your intentions and reasoning to the committer in such a case. There may be constraints you had to work with which they're not aware of or qualities of your approach that they didn't immediately notice. If these weren't clear to the reviewer, that's a good sign you should explain them in your commit message or code comments! There are some further pitfalls and realities to be aware of: ### Aim to reduce cycles Be prepared for it to take a while for the reviewer to get back to you after you respond. This is simply the reality of projects at the scale of Nixpkgs. As such, make sure to respond to _all_ feedback at once. It wastes everyone's time to wait for a couple of days just to have the reviewer need to remind you to address something they asked for. ### A reviewer requested a bunch of insubstantial changes The people involved in Nixpkgs care about code quality. Once in Nixpkgs, the code needs to be maintained for many years to come. Therefore, you will likely be asked to do something different or adhere to a standard. Sometimes however, they also care a bit too much and may ask you to adhere to a personal preference of theirs. It's not always easy to tell whether or not the requested changes must be addressed. Sometimes, another reviewer may even have a _conflicting_ opinion on some points. It is convention to mark review comments that are not required to merge as nitpicks, but this is not always followed. As the author, you should still take a look at these, as they will often reveal best practices and unwritten rules. Those usually have good reasons behind them and you may want to pick them up as well. Please keep in mind that reviewers always mean well. Their intent is not to denounce your code, they want your code to be as good as it can be. Through their experience, they may also take notice of a seemingly insignificant issue that has caused problems before. Sometimes however, they can also get a bit carried away and become too perfectionistic. If you feel some of the requests are unreasonable, out of scope, or merely a matter of personal preference, try to nicely ask the reviewers whether these requests are *critical* to the PR's success. While we do have a set of [official standards for the Nix community](https://github.com/NixOS/rfcs), we don't have standards for everything and there are often multiple valid ways to achieve the same goal. Unless there are standards forbidding the patterns used in your code or there are serious technical, maintainability or readability issues with your code, you can disregard these requests. Please communicate this clearly though; a simple "I prefer it this way and see no major issue maintaining it" can save a lot of arguing.

This text provides guidance on effectively responding to Pull Request (PR) reviews. It advises authors to thoroughly explain their intentions and reasoning, especially when reviewers are unconvinced or require further input, and to involve other relevant users or maintainers if their expertise is needed. To streamline the review process, it stresses the importance of responding to all feedback simultaneously to minimize review cycles, acknowledging the inherently slow pace of large projects. The document also addresses how to manage reviewer requests that may appear insubstantial or based on personal preference. While acknowledging reviewers' focus on long-term code quality, it suggests politely questioning the criticality of such requests and, in the absence of official standards or major technical issues, respectfully declining preference-based changes while clearly communicating the rationale.