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 11## GitHub Pull Requests 12 13Presently, GitHub 'freebsd-src' repository is one of the publish-only services 14for the FreeBSD 'src' repository the project uses to promote collaboration and 15contribution. Pull requests that need little developer time, are generally 16small, and have limited scope should be submitted. Do not submit pull request 17that are a problem reports, works in progress, changes that are controversial 18and need discussion, changes require specialize review, or are security related. 19 20A pull request will be considered if: 21 22* 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. 23* It passes all the GitHub CI jobs. 24* You can respond to feedback quickly. 25* 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. 26* 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). 27* All commits have your name and valid email address as you would like to see them in the FreeBSD repository as the author. Fake github.com addresses cannot be used. 28* 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. 29* Fixup commits should be squashed with the commit they are fixing. Each commit in your branch should be suitable for FreeBSD's repository. 30* Commits should include one or more `Signed-off-by:` lines with full name and email address certifying [Developer Certificate of Origin](https://developercertificate.org/). 31* The commits follow FreeBSD's style guide. See [Style](#Style). 32* Run tools/build/checkstyle9.pl on your git branch and eliminate all errors 33* The commits should not introduce trailing white space. 34* If the commmit fixes a bug, please add 'PR: <bugnumber>' to the comment message. 35* If there's a code review in phabricator, please include a link as a 'Differential Revision: ' line. 36 37When updating your pull request, please rebase with a forced push rather than a 38merge commit. 39 40More complex changes may be submitted as pull requests, but they may be closed 41if they are too large, too unwieldy, become inactive, need further discussion in 42the community, or need extensive revision. Please avoid creating large, 43wide-ranging cleanup patches: they are too large and lack the focus needed for a 44good review. Misdirected patches may be redirected to a more appropriate forum 45for the patch to be resolved. 46 47Please make sure that your submissions compile and work before submitting. If 48you need feedback, a pull request might not be the right place (it may just be 49summarily closed if there are too many obvious mistakes). 50 51If you want to cleanup style or older coding conventions in preparation for some 52other commit, please go ahead and prepare those patches. However, please avoid just 53cleaning up to make it cleaner, unless there's a clear advantage to doing 54so. While the project strives to have a uniform coding style, our style offers a 55range of choices making some 'cleanups' ambiguous at best. Also, some files have 56their own consistent style that deviates from style(9). Style changes take 57volunteer time to process, but that time can be quite limited, so please be 58respectful. 59 60The current theory for pull requests on GitHub is to facilitate inclusion in the 61project. The guidelines are streamlined for quick decisions about each pull 62request. Unless explicitly stated, rejection here as "not ready" or "too large" 63does not mean the project is uninterested in the work, it just means the 64submission does not meet the limited scope for pull requests accepted 65here. Sometimes it is easier to review a GihHub pull request than to do the 66review in Phabricator, so that's also allowed. 67 68## Style 69 70Avoid adding trailing newlines and whitespace. These slow down the integration 71process and are a distraction. `git diff` will highlight them in red, as will 72the Files Changed tab in the pull request. 73 74For C programs, see [style(9)](https://man.freebsd.org/cgi/man.cgi?query=style&sektion=9) 75for details. You can use [Clang format](https://clang.llvm.org/docs/ClangFormat.html) 76with the top level .clang-format file if you are unsure. The 77[git clang-format](https://github.com/llvm-mirror/clang/blob/master/tools/clang-format/git-clang-format) 78command can help minimize churn by only formatting the areas nearby the changes. While 79not perfect, using these tools will maximize your chances of not having style 80comments on your pull requests. 81 82For Makefiles changes, see 83[style.Makefile(5)](https://man.freebsd.org/cgi/man.cgi?query=style.Makefile&sektion=5) 84for details. FreeBSD's base system uses the in-tree make, not GNU Make, so 85[make(1)](https://man.freebsd.org/cgi/man.cgi?query=make&sektion=1) is another useful 86resource. 87 88The project uses mdoc for all its man pages. Changes should pass `mandoc -Tlint` and igor (install the latter with `pkg install igor`). 89Please be sure to observe the one-sentence-per-line rule so manual pages properly render. Any semantic changes to the manual pages should bump the date. 90[style.mdoc(5)](https://man.freebsd.org/cgi/man.cgi?query=style.mdoc&sektion=5) has the all details. 91 92For [Lua](https://www.lua.org), please see 93[style.lua(9)](https://man.freebsd.org/cgi/man.cgi?query=style.lua&sektion=9) 94for details. Lua is used for the boot loader and a few scripts in the base system. 95 96For shell scripts, avoid using bash. The system shell (/bin/sh) is preferred. 97Shell scripts in the base system cannot use bash or bash extensions 98not present in FreeBSD's [shell](https://man.freebsd.org/cgi/man.cgi?query=sh&sektion=1). 99 100## Signed-off-by 101 102Other projects use Signed-off-by to create a paper trail for contributions they 103receive. The Developer Certificate of Origin is an attestation that the person 104making the contribution can do it under the current license of the file. Other 105projects that have 'delegated' hierarchies also use it when maintainers 106integrate these patches and submit them upstream. 107 108Right now, pull requests on GitHub are an experimental feature. We strongly 109suggest that people add this line. It creates a paper trail for infrequent 110contributors. Also, developers that are landing a pull request will use a 111Signed-off-by line to set the author for the commit. 112 113These lines are easy to add with `git commit -s`. 114