1# Contribution Guidelines for GitHub 2 3## General Contributions to FreeBSD 4 5Please read the guidelines in [Contributing to FreeBSD](https://docs.freebsd.org/en/articles/contributing/) 6for all the ways you can contribute to the project, how the project is organized, 7how to build different parts of the project, etc. The 8[developer's handbook](https://docs.freebsd.org/en/books/developers-handbook/) 9is another useful resource. 10 11FreeBSD accepts source code contributions using one of several methods: 12- A GitHub [pull request](https://github.com/freebsd/freebsd-src/pulls) 13- A code review in [Phabricator](https://reviews.freebsd.org/differential) 14- An attachment on a [Bugzilla ticket](https://bugs.freebsd.org) 15- Direct access to the [Git repository](https://cgit.freebsd.org/src/) 16 17The preferred method depends on a few factors including the size or scope of 18the change. GitHub pull requests are preferred for relatively straightforward 19changes where the contributor already has a GitHub account. 20 21A change should be submitted by only one method. For example, please do not 22open a GitHub pull request and create a Phabricator review for the same change 23(unless explicitly requested to do so by a FreeBSD committer). 24 25## GitHub Pull Requests 26 27Presently, GitHub 'freebsd-src' repository is one of the publish-only services 28for the FreeBSD 'src' repository the project uses to promote collaboration and 29contribution. Pull requests that need little developer time, are generally 30small, and have limited scope should be submitted. Do not submit pull requests 31that are security-related, problem reports, works in progress, changes that are controversial 32and need discussion, or changes that require specialized review. 33 34A pull request will be considered if: 35 36* 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. 37* 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. 38* It passes all the GitHub CI jobs. 39* You can respond to feedback quickly. If feedback is requested and one month passes without a response we may close the pull request. 40* 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. 41* 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). 42* 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. But see [Author Name and Email][#author-name-and-email] for details. 43* 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. 44* Fixup commits should be squashed with the commit they are fixing. Each commit in your branch should be suitable for FreeBSD's repository. 45* Commits should include one or more `Signed-off-by:` 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. 46* The commits follow FreeBSD's style guide. See [Style](#Style). 47* Run tools/build/checkstyle9.pl on your Git branch and eliminate all errors, or provide an explanation for exceptions. 48* The commits do not introduce trailing white space. 49* If the commit fixes a bug, please add 'PR: \<bugnumber\>' to the commit message to document the Bugzilla Problem Report number. 50* 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. 51* 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. 52* 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. 53* Submissions using generative AI will be rejected. 54* Submissions from AI chatbots will result in the account being banned. 55 56When revising your pull request after feedback, please rebase with a forced push 57rather than a merge commit. 58 59More complex changes may be submitted as pull requests, but they may be closed 60if they are too large, too unwieldy, become inactive, need further discussion in 61the community, or need extensive revision. 62 63Please avoid creating large, wide-ranging cleanup patches: they often lack the 64focus needed for a good review and can be hard to test. Misdirected patches may 65be redirected to a more appropriate forum for the patch to be resolved. 66 67Please make sure that your submissions compile and work before submitting. If 68you need feedback, a pull request might not be the right place. A pull request 69may be closed if there are too many obvious mistakes, or when a time-consuming 70rework is needed. 71 72If you want to cleanup style or older coding conventions in preparation for some 73other commit, please go ahead and prepare those patches. However, please avoid 74just cleaning up to make it cleaner, unless there's a clear advantage to doing 75so. While the project strives to have a uniform coding style, our style offers a 76range of choices making some 'cleanups' ambiguous at best. Also, some files have 77their own consistent style that deviates from style(9). Style changes take time 78to process, but our volunteers have limited time, so please be respectful of 79their time. Trivial spelling changes take this valuable time, but rerturn little 80benefit relative to other changes. 81 82The current theory for pull requests on GitHub is to facilitate inclusion in the 83project. The guidelines are streamlined for quick decisions about each pull 84request. Unless explicitly stated, rejection here as "not ready" or "too large" 85does not mean the project is uninterested in the work, it just means the 86submission does not meet the limited scope for pull requests accepted 87here. Sometimes it is easier to review a GitHub pull request than to do the 88review in Phabricator, so that's also allowed. 89 90Finally, if we close a pull request because it's not ready yet, or stalled out, 91please don't give up. You can resubmit them later once you have time to finish 92the work, or to have them reconsidered if you think we've made an error in 93closing it. 94 95### Author Name and Email 96 97Please use a name and email address in the `Signed-off-by` trailer and as the 98author of the git commits, since we cannot accept anonymous contributions. It is 99common, but not required, to use some form of your full name. We realize that 100some contributors are not comfortable doing so or prefer to contribute under a 101pseudonym, preferred name, chosen name or similar moniker that might not match 102relevant government records. We can accept your patch, as long as the name and 103email you use are distinctive, identifying, and not misleading. Please note that 104if your patch is accepted, the name and email address will become a permanent 105and immutable part of the public history of the FreeBSD source tree. 106 107The goal of this policy is to allow us to have sufficient information to contact 108you if questions arise about your contribution. Addresses of the form 109something@users.noreply.github.com do not meet this standard since we cannot use 110it to contact you. We can use `.mailmap` for name or email changes and mistakes, 111but is imperfect. 112 113Core (core@freebsd.org) may request authors of significant changes using an 114obvious pseudonym to document their identity more concretely should there be 115issues in the future. The author may request this documentation be kept 116confidential unless needed for legal issues arising from their contributions. 117 118## Style 119 120Avoid adding trailing newlines and whitespace. These slow down the integration 121process and are a distraction. `git diff` will highlight them in red, as will 122the Files Changed tab in the pull request. 123 124For C programs, see [style(9)](https://man.freebsd.org/cgi/man.cgi?query=style&sektion=9) 125for details. You can use [Clang format](https://clang.llvm.org/docs/ClangFormat.html) 126with the top level .clang-format file if you are unsure. The 127[git clang-format](https://github.com/llvm-mirror/clang/blob/master/tools/clang-format/git-clang-format) 128command can help minimize churn by only formatting the areas nearby the changes. While 129not perfect, using these tools will maximize your chances of not having style 130comments on your pull requests. 131 132For [Lua](https://www.lua.org), see 133[style.lua(9)](https://man.freebsd.org/cgi/man.cgi?query=style.lua&sektion=9) 134for details. Lua is used for the boot loader and a few scripts in the base system. 135 136For Makefiles changes, see 137[style.Makefile(5)](https://man.freebsd.org/cgi/man.cgi?query=style.Makefile&sektion=5) 138for details. FreeBSD's base system uses the in-tree make, not GNU Make, so 139[make(1)](https://man.freebsd.org/cgi/man.cgi?query=make&sektion=1) is another useful 140resource. 141 142For manual page changes, see 143[style.mdoc(5)](https://man.freebsd.org/cgi/man.cgi?query=style.mdoc&sektion=5) 144for details. Changes should pass `mandoc -Tlint` and igor (install the latter with `pkg install igor`). 145Please be sure to observe the one-sentence-per-line rule so manual pages properly render. 146Proposed changes to manual pages should not bump the document date until merged. 147 148For shell scripts, avoid using bash. The system shell (/bin/sh) is preferred. 149Shell scripts in the base system cannot use bash or bash extensions 150not present in FreeBSD's [shell](https://man.freebsd.org/cgi/man.cgi?query=sh&sektion=1). 151 152## Signed-off-by 153 154Other projects mandate Signed-off-by to create a paper trail for contributions they 155receive. The Developer Certificate of Origin is an attestation that the person 156making the contribution can do it under the current license of the file. Other 157projects that have 'delegated' hierarchies also use it when maintainers 158integrate these patches and submit them upstream. 159 160Right now, pull requests on GitHub are an experimental feature. We strongly 161suggest that people add this line. It creates a paper trail for infrequent 162contributors. Also, developers that are landing a pull request will use a 163Signed-off-by line to set the author for the commit. 164 165These lines are easy to add with `git commit -s`. 166 167## Submitting as part of class work 168 169If you are a professor or teacher that wishes to have your students submit fixes 170as part of their class work, please contact imp@FreeBSD.org before the semester 171to ensure we allocate the proper resources to process them quickly. We'll give 172you more details when you contact us and thanks for including FreeBSD in your 173class work. It also helps us keep track. 174 175## FreeBSD's Upstreams 176 177Anything that's in the directory `contrib`, `crypto`, `sys/contrib`, 178`sys/crypto/` or `sys/cddl` likely has an upstream we pull from. Please do a 179`git log --merges` in any subdirectory of these you are submitting patches for 180to find out the last time we merged from upstream. If it is in the last 5 years, 181upstream is "active" and you should submit your patches there and let the last 182few people to commit to this file (especially merge commits) know. If it's been 183more than 5 years, upstream is likely inactive so please submit the patch. We 184can sort out if it should go into FreeBSD or upstream. 185