Page MenuHomeFreeBSD
Files F160808187

D43298.diff
No OneTemporary
Actions

D43298.diff
View Options

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,29 +24,43 @@
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.
+that are security-related, problem reports, works in progress, changes that are
+controversial and need discussion, or changes that require specialized review.
+
+Also, it takes time to process these requests, and our volunteer time is quite
+limited. Please respect our volunteers' time by double checking your work,
+reading these guidelines and making sure you've fixed the common problems we
+outline here. Make sure the CI jobs all pass: we may close pull requests that
+introduce new CI failures.
A pull request will be considered if:
-* 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 is ready or nearly ready to be committed. A FreeBSD 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.
* 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).
+* 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). Please pay special attention that the second line of the commit message is blank.
* All commits have, as the 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.
* 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.
* Commits should include one or more `Signed-off-by:` lines with full name and email address certifying [Developer Certificate of Origin](https://developercertificate.org/).
* The commits follow FreeBSD's style guide. See [Style](#Style).
-* Run tools/build/checkstyle9.pl on your Git branch and eliminate all errors.
+* Run tools/build/checkstyle9.pl on your Git branch and eliminate all errors, or provide an explanation of why you think this tool produced a false positive.
* The commits do not introduce trailing white space.
* If the commit fixes a bug, please add 'PR: \<bugnumber\>' to the commit message.
* If there's a code review in Phabricator, please include a link as a 'Differential Revision: ' line.
-* 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.
+* 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. Also create a test case that shows an actual bug that's being fixed by these changes. In general, these changes will be rejected unless there's a demonstrable bug that's fixed. Historically, such commits have given little value to the project, and also must be weighed against the risk of introducing bugs and the volunteer time needed to review and test the change.
+* Typo and other trivial fixes should be limited. If you find it while doing something else, then including it as a separate commit in the pull request is fine. If it's just a typo, then please limit your submissions to one or two to practice the process, but no more. These commits, when done standalone are a significant tax on our limited resources.
+* If the commit violates these rules, isn't ready or if the submitter can't process requests for changes and/or other feedback quickly, then PRs may be closed.
When updating your pull request, please rebase with a forced push rather than a
-merge commit.
+merge commit. This produces a cleaner base and will reduce the amount of time
+volunteers need to spend on the commit.
+
+If a PR is closed and then you fix the problems with it, please open a new
+PR. If the original PR is still relevant, please reference it in the description
+of the pull request so we can track it. Too many open, stalled pull requests
+make it difficult to find actionable pull requests and waste volunteers' time.
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
@@ -57,16 +71,18 @@
Please make sure that your submissions compile and work before submitting. If
you need feedback, a pull request might not be the right place (it may just be
-summarily closed if there are too many obvious mistakes).
+summarily closed if there are too many obvious mistakes). Pull requests that are
+not ready waste a lot of volunteer time, sometimes at the expense of other pull
+requests.
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
-volunteer time to process, but that time can be quite limited, so please be
-respectful.
+other commit, please go ahead and prepare those patches. However, please avoid
+just cleaning up to make it cleaner, unless there's a clear and compelling
+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 volunteer time to process, but that time can be
+quite limited, so please be respectful.
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
@@ -74,7 +90,9 @@
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.
+review in Phabricator, so that's also allowed. Some classes of changes, as
+outlined above, provide little value for the time spent vetting and landing
+them, so please take that into consideration.
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
@@ -140,8 +158,9 @@
If you are a professor or teacher that wishes to have your students submit fixes
as part of their class work, please contact imp@FreeBSD.org before the semester
to ensure we allocate the proper resources to process them quickly. We'll give
-you more details when you contact us and thanks for including FreeBSD in your
-class work. It also helps us keep track.
+you more details about the tradeoffs we consider for pull requests when you
+contact us and thank you for including FreeBSD in your class work. It also helps
+us keep track of where otherwise odd-looking requests are coming from.
## FreeBSD's Upstreams

File Metadata

Mime Type
text/plain
Expires
Mon, Jun 29, 2:39 AM (12 h, 17 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
34418931
Default Alt Text
D43298.diff (8 KB)

Event Timeline