The branch main has been updated by emaste: URL: https://cgit.FreeBSD.org/src/commit/?id=97beb0c9116f312c1820adb94455dc3b9a157135
commit 97beb0c9116f312c1820adb94455dc3b9a157135 Author: Ed Maste <[email protected]> AuthorDate: 2026-02-09 15:44:15 +0000 Commit: Ed Maste <[email protected]> CommitDate: 2026-02-09 15:47:08 +0000 CONTRIBUTING.md: Clarify GitHub pull requests Make the guidelines more prescriptive (while remaining clear that Pull Requests are merely one, not-preferred method for submitting changes). Reviewed by: imp Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D55089 --- CONTRIBUTING.md | 155 +++++++++++++++++++++++++++++++++----------------------- 1 file changed, 93 insertions(+), 62 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3dd764a64c7e..4d33ec6612cf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,68 +24,99 @@ open a GitHub pull request and create a Phabricator review for the same change ## GitHub Pull Requests -Presently, GitHub 'freebsd-src' repository is one of the publish-only services -for the FreeBSD 'src' repository the project uses to promote collaboration and -contribution. Pull requests that need little developer time, are generally -small, and have limited scope should be submitted. Do not submit pull requests -that are security-related, problem reports, works in progress, changes that are controversial -and need discussion, or changes that require specialized review. - -A pull request will be considered if: - -* The request is substantive in nature. We generally don't accept minor or cosmetic changes unless they are part of larger work in that area. Pull requests should solve a real, actual problem. -* It is ready or nearly ready to be committed. A committer should be able to land the pull request with less than 10 minutes of additional work. -* It passes all the GitHub CI jobs. -* You can respond to feedback quickly. If feedback is requested and one month passes without a response we may close the pull request. -* It touches fewer than about 10 files and the changes are less than about 200 lines. Changes larger than this may be OK, or you may be asked to submit multiple pull requests of a more manageable size. -* Each logical change is a separate commit within the pull request. Commit messages for each change should follow the [commit log message guide](https://docs.freebsd.org/en/articles/committers-guide/#commit-log-message). -* All commits have, as the git author, your name and valid email address as you would like to see them in the FreeBSD repository. Fake github.com addresses cannot be used. But see [Author Name and Email](#author-name-and-email) for details. -* The scope of the pull request should not change during review. If the review suggests changes that expand the scope, please create an independent pull request. -* Fixup commits should be squashed with the commit they are fixing. Each commit in your branch should be suitable for FreeBSD's repository. -* Commit messages should include one or more `Signed-off-by:` trailer lines with name and email address certifying [Developer Certificate of Origin](https://developercertificate.org/). But see [Author Name and Email](#author-name-and-email) for details. -* The commits follow FreeBSD's style guide. See [Style](#Style). -* Run tools/build/checkstyle9.pl on your Git branch and eliminate all errors, or provide an explanation for exceptions. The tool sometimes makes mistakes, and providing an explanation shows you have examined the output. -* The commits do not introduce trailing white space. -* If the commit fixes a bug, please add 'PR: \<bugnumber\>' to the commit message to document the Bugzilla Problem Report number. -* If there's a code review related to this change, please include its URL in the commit message. However, where possible, please do not open both a differential review and a GitHub pull request. -* If you have run FreeBSD's sources through a static analysis tool, please don't submit the raw results. Please also see the chunking up guidelines. Also, please make sure that kyua tests are the same before / after your change. Ideally, you'd also create a test case that shows an actual bug that's being fixed by these changes. -* FreeBSD committers submitting pull requests are responsible for pushing them into the tree (possibly with approval if cross-repo commit bit policy needs it). Pull requests by FreeBSD committers will be closed after a month unless there's a very good reason not to. -* Low quality submimssions will be rejected, especially if they were generated by AI with little to no refinement. -* Submissions by AI chatbots will result in the account being banned. Do not use pull requests interaction to train your LLM or similar AI model. - -When revising your pull request after feedback, please rebase with a forced push -rather than a merge commit. - -More complex changes may be submitted as pull requests, but they may be closed -if they are too large, too unwieldy, become inactive, need further discussion in -the community, or need extensive revision. - -Please avoid creating large, wide-ranging cleanup patches: they often lack the -focus needed for a good review and can be hard to test. Misdirected patches may -be redirected to a more appropriate forum for the patch to be resolved. - -Please make sure that your submissions compile and work before submitting. If -you need feedback, a pull request might not be the right place. A pull request -may be closed if there are too many obvious mistakes, or when a time-consuming -rework is needed. - -If you want to cleanup style or older coding conventions in preparation for some -other commit, please go ahead and prepare those patches. However, please avoid -just cleaning up to make it cleaner, unless there's a clear advantage to doing -so. While the project strives to have a uniform coding style, our style offers a -range of choices making some 'cleanups' ambiguous at best. Also, some files have -their own consistent style that deviates from style(9). Style changes take time -to process, but our volunteers have limited time, so please be respectful of -their time. Trivial spelling changes take this valuable time, but rerturn little -benefit relative to other changes. - -The current theory for pull requests on GitHub is to facilitate inclusion in the -project. The guidelines are streamlined for quick decisions about each pull -request. Unless explicitly stated, rejection here as "not ready" or "too large" -does not mean the project is uninterested in the work, it just means the -submission does not meet the limited scope for pull requests accepted -here. Sometimes it is easier to review a GitHub pull request than to do the -review in Phabricator, so that's also allowed. +The _freebsd-src_ GitHub repository is a **publish-only mirror** of the FreeBSD +_src_ repository. Pull Requests are accepted for **small, low-risk** changes +that require minimal review and integration effort. + +For complex, controversial, security-related, or discussion-heavy changes, use +the normal FreeBSD review and development process (described below) instead. + +Submit a Pull Request if your change: + +* Fixes a real, specific problem. +* Is small in scope and easy to review. +* Can be committed with **less than ~10 minutes** of additional work. +* Passes all GitHub CI jobs. +* Affects roughly **10 or fewer files** and **fewer than 200 lines of changes**. + +### When Not to use a Pull Request + +Do NOT submit a Pull Request for: + +* Security-related changes. +* Works in progress. +* Changes that require design discussion, or are likely to be controversial. + (Start a mailing list thread to discuss the change first.) +* Changes needing specialized or cross-subsystem review. +* Large refactors or mechanical tree-wide changes. +* Changes generated by AI tools without substantial human review and validation. + +### Preparing your Pull Request + +Before submitting, ensure: + +#### Code Quality + +* The changes follow FreeBSD's style guide. See [Style](#Style). +* _tools/build/checkstyle9.pl_ is run and: + * All errors are fixed, **or** + * Exceptions are documented in the PR. +* No trailing whitespace is introduced. +* Changes compile and work before submitting. +* Test results (including Kyua tests) are unchanged, unless intentionally + modified. +* Bug fixes include new test cases, when possible. + +#### Commit Structure + +* Each logical change is a **separate commit**. +* Fixup commits are squashed into the commit they correct. +* Each commit is suitable for direct inclusion in the FreeBSD's repository. +* Pull Request scope must remain stable during review. If feedback expands + scope, create a new Pull Request. +* Rebase your chages (and update with a forced push) when incorporating review + feedback, rather than using a merge commit. + +#### Commit Messages + +Each commit must: + +* Follow the [commit log message guide](https://docs.freebsd.org/en/articles/committers-guide/#commit-log-message). +* Include one ore more `Signed-off-by:` trailers certifying [Developer Certificate of Origin](https://developercertificate.org/). +* Include `PR: \<bugnumber\>` if fixing a Bugzilla Problem Report. +* Include the URL of a related code review, if applicable. + (Avoid opening both Phabricator/Differential reviews and GitHub Pull Requests + for the same change.) + +#### Author Information + +* Commits use your name and valid email address. +* GitHub-generated `users.noreply.github.com` addresses cannot be used. +* See [Author Name and Email](#author-name-and-email) for details. + +### Contributor Responsibilities + +* Monitor your Pull Request and respond to review feedback promptly. +* Pull Requests may be closed if there is no response for **one month**. + +### Additional Requirements for FreeBSD Committers + +* Committers submitting Pull Requests are for pushing their changes to the tree + (including obtaining any required approvals). +* Pull Requests opened by FreeBSD committers may be closed after one month + unless there is a strong reason to keep them open. + +### Quality Expectations + +Low quality submimssions will be rejected. This includes submissions generated +by AI tools that lack sufficient validation, testing, or understanding by the +submitter. + +A pull request may be closed if there are too many obvious mistakes, or when a +time-consuming rework is needed. + +Automated accounts or chatbots must not submit pull requests or use pull +request interactions to train AI or LLM systems. Finally, if we close a pull request because it's not ready yet, or stalled out, please don't give up. You can resubmit them later once you have time to finish
