Helping Committers Assess PRs and Get Them Reviewed

For the code quality assessment, you cannot do anything yourself as only the committer can do this and they already have your code to look at. In order to minimise the need for back and forth though, do take a look over your code changes yourself and try to put yourself into the shoes of someone who didn't just write that code. Would you immediately know what the code does or why it is needed by glancing at it? If not, reviewers will notice this and will ask you to clarify the code by refactoring it and/or adding a few explanations in code comments. Doing this preemptively can save you and the committer a lot of time. To better convey the "story" of your change, consider dividing your change into multiple atomic commits. There is a balance to strike however: over-fragmentation causes friction. The code artefacts are the hardest for committers to assess because PRs touch all sorts of components: applications, libraries, NixOS modules, editor plugins and many many other things. Any individual committer can only really assess components that they themselves know how to use however and yet they must still be convinced somehow. There isn't a good generic solution to this but there are some ways easing the committer's job here: - Provide smoke tests that the committer can run without much research or setup. Committers usually don't have the time or interest to learn how your component works and how they could test its functionality. If you can provide a quick guide on how to use the component in a meaningful way or a ready-made command that demonstrates that the component works as expected, the committer can easily convince themselves that your change is good. If it can be automated, you could even turn this smoke test into an automated NixOS test which reviewers could simply run via Nix. - Invite other users of the component to try it out and report their findings. If a committer sees the testimonials of other users trying your change and it works as expected for them, that too can convince the committer of your PR's quality. - Describe what you have done to test your PR. If you can convince the committer that you have done sufficient quality assurance on your changes and they trust your report, this too can convince them of your PR's quality, albeit not as strongly as the methods above. - Become a maintainer of the component. This isn't something you can do on your first few PRs touching a component but listed maintainers generally receive more trust when it comes to changes to their maintained components and committers may opt to merge changes without deeper review when they see they're done by their respective maintainer. Even if you adhere to all of these recommendations, it is still quite possible for your PR to be forgotten or abandoned by any given committer. Please remain mindful of the fact that they are doing this on their own volition and unpaid in their free time and therefore [owe you nothing](https://mikemcquaid.com/open-source-maintainers-owe-you-nothing/). Causing a stink in such a situation is a surefire way to get any other potential committer to not want to look at your PR either. Ask them nicely whether they still intend to review your PR and find yourself another committer to look at your PR if not. ### How can I get a committer to look at my PR? - Improve skimmability: use a simple descriptive PR title (details go in commit titles) outlining _what_ is done and _why_. - Improve discoverability: apply all relevant labels, tick all relevant PR body checkboxes. - Wait. Reviewers frequently browse open PRs and may happen to run across yours and take a look. - Get non-committers to review/approve. Many committers filter open PRs for low-hanging fruit that are already been reviewed. - [@-mention](https://github.blog/news-insights/mention-somebody-they-re-notified/) someone and ask them nicely - Post in one of the channels made for this purpose if there has been no activity for at least one week - The current "PRs ready for review" or "PRs already reviewed" threads in the [NixOS Discourse](https://discourse.nixos.org/c/dev/14) (of course choose the one that applies to your situation)

This section discusses how to help committers assess code quality and artifacts in pull requests (PRs) and how to get committers to review them. It suggests providing smoke tests, inviting other users to test the changes, describing testing efforts, and becoming a maintainer of the component. The section also advises patience and respect for committers' time, emphasizing that they are unpaid volunteers. To improve PR visibility, it recommends using descriptive titles, applying relevant labels, and seeking reviews from non-committers before requesting a committer's attention. Mentioning someone and asking nicely or posting in designated channels after a week of inactivity are also suggested.