From 6d93b1f671caa93f2209100da643b7a5662b785c Mon Sep 17 00:00:00 2001 From: Davanum Srinivas Date: Thu, 13 Aug 2026 11:31:23 -0400 Subject: [PATCH] docs: add pull request guidelines to CONTRIBUTING.md Add a new section covering how to structure PRs well: - group cross-distro fixes for the same root cause into one PR - open an issue before sending bulk fixes - avoid opening many PRs in a single session to protect shared CI - check for existing open PRs on the same file to prevent conflicts - separate cosmetic changes from correctness fixes - write tests that execute code, not just grep for old patterns - link every PR to an issue Signed-off-by: Davanum Srinivas --- CONTRIBUTING.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dfeb8209c..d892c346f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,3 +58,57 @@ Use your real name (sorry, no pseudonyms or anonymous contributions.) If you set your `user.name` and `user.email` git configs, you can sign your commit automatically with `git commit -s`. +## Pull Request Guidelines + +### One PR per root cause, not per file + +If the same bug appears in multiple OS-specific directories +(ubuntu22.04, ubuntu24.04, rhel8, rhel9, rhel10), fix all instances +in a single PR. Title the PR around the root cause: + +- Good: `fix: set -e suppresses command-substitution exit codes` +- Avoid: one PR per distro for the same one-liner change + +### Open an issue before bulk fixes + +If you find five or more instances of the same pattern, open one +GitHub issue first. Describe the pattern and your proposed fix. +Wait for a maintainer response before opening any PR. This avoids +flooding CI with work the team may not want. + +### Do not open more than three PRs per day + +Each PR triggers a CI run that uses shared compute. Submitting many +PRs in a single session blocks CI for every other contributor. +If you have many fixes, batch them or stagger them across days. + +### Check for conflicts before opening + +Search for open PRs that touch the same file before opening a new one: + +``` +is:open is:pr +``` + +A PR that conflicts with an already-open PR will stall on review. + +### Separate cosmetic from correctness changes + +Put style fixes (variable naming, deprecated test syntax) in their +own PR, separate from behavioral bug fixes. Reviewers triage +correctness issues first; cosmetic changes buried inside bug fixes +slow the queue. + +### Write tests that execute the code + +A test that greps for absence of old text is a linter check, not a +regression test. Tests should invoke the function being fixed (even +via a stub harness) and verify the correct behavior. A test that +passes on the unchanged code is not useful. + +### Link every PR to an issue + +Every PR must include a `Fixes #NNN` or `Related to #NNN` reference. +If no issue exists, open one first (see above). PRs without an issue +link are harder to triage and may be closed without review. +