Reviewing and Merging Pull Requests in Nixpkgs: Best Practices

The Nixpkgs project receives a fairly high number of contributions via GitHub pull requests. Reviewing and approving these is an important task and a way to contribute to the project. The high change rate of Nixpkgs makes any pull request that remains open for too long subject to conflicts that will require extra work from the submitter or the merger. Reviewing pull requests in a timely manner and being responsive to the comments is the key to avoid this issue. GitHub provides sort filters that can be used to see the [most recently](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc) and the [least recently](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-asc) updated pull requests. We highly encourage looking at [this list of ready to merge, unreviewed pull requests](https://github.com/NixOS/nixpkgs/pulls?q=is%3Apr+is%3Aopen+review%3Anone+status%3Asuccess+-label%3A%222.status%3A+work-in-progress%22+no%3Aproject+no%3Aassignee+no%3Amilestone). When reviewing a pull request, please always be nice and polite. Controversial changes can lead to controversial opinions, but it is important to respect every community member and their work. GitHub provides reactions as a simple and quick way to provide feedback to pull requests or any comments. The thumb-down reaction should be used with care and if possible accompanied with some explanation so the submitter has directions to improve their contribution. When doing a review: - Aim to drive the proposal to a timely conclusion. - Focus on the proposed changes to keep the scope of the discussion narrow. - Help the contributor prioritise their efforts towards getting their change merged. If you find anything related that could be improved but is not immediately required for acceptance, consider - Implementing the changes yourself in a follow-up pull request (and request review from the person who inspired you) - Tracking your idea in an issue - Offering the original contributor to review a follow-up pull request - Making concrete [suggestions](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request) in the same pull request. For example, follow-up changes could involve refactoring code in the affected files. But please remember not to make such additional considerations a blocker, and communicate that to the contributor, for example by following the [conventional comments](https://conventionalcomments.org/) pattern. If the related change is essential for the contribution at hand, make clear why you think it is important to address that first. Pull request reviews should include a list of what has been reviewed in a comment, so other reviewers and mergers can know the state of the review. All the review template samples provided in this section are generic and meant as examples. Their usage is optional and the reviewer is free to adapt them to their liking. To get more information about how to review specific parts of Nixpkgs, refer to the documents linked to in the [overview section][overview]. If a pull request contains documentation changes that might require feedback from the documentation team, ping [@NixOS/documentation-team](https://github.com/orgs/nixos/teams/documentation-team) on the pull request. If you consider having enough knowledge and experience in a topic and would like to be a long-term reviewer for related submissions, please contact the current reviewers for that topic. They will give you information about the reviewing process. The main reviewers for a topic can be hard to find as there is no list, but checking past pull requests to see who reviewed or git-blaming the code to see who committed to that topic can give some hints. Container system, boot system and library changes are some examples of the pull requests fitting this category. ## How to merge pull requests yourself To streamline automated updates, leverage the nixpkgs-merge-bot by simply commenting `@NixOS/nixpkgs-merge-bot merge`. The bot will verify if the following conditions are met, refusing to merge otherwise:

This section outlines the best practices for reviewing and merging pull requests in Nixpkgs, emphasizing politeness, respect, and timely conclusions. It advises reviewers to focus on the proposed changes, help contributors prioritize efforts, and consider non-blocking improvements separately. The importance of providing clear explanations for feedback, including negative reactions, is highlighted. The section also touches on using GitHub reactions effectively, suggesting follow-up actions for improvements not immediately required, and indicating what has been reviewed in a comment. It then explains how to use nixpkgs-merge-bot to merge pull requests automatically by commenting `@NixOS/nixpkgs-merge-bot merge`.