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). If asked to move 24from Github to Phabricator, please close the Github pull request adding the URL 25of the Phabricator review as a comment. 26 27## GitHub Pull Requests 28 29The _freebsd-src_ GitHub repository is a **publish-only mirror** of the FreeBSD 30_src_ repository. Pull Requests are accepted for **small, low-risk** changes 31that require minimal review and integration effort. 32 33For complex, controversial, security-related, or discussion-heavy changes, use 34the normal FreeBSD review and development process (described below) instead. 35 36Submit a Pull Request if your change: 37 38* Fixes a real, specific problem. 39* Is small in scope and easy to review. 40* Can be committed with **less than ~10 minutes** of additional work. 41* Passes all GitHub CI jobs. 42* Affects roughly **10 or fewer files** and **fewer than 200 lines of changes**. 43 44### When Not to use a Pull Request 45 46Do NOT submit a Pull Request for: 47 48* Security-related changes. 49* Works in progress. 50* Changes that require design discussion, or are likely to be controversial. 51 (Start a mailing list thread to discuss the change first.) 52* Changes needing specialized or cross-subsystem review. 53* Large refactors or mechanical tree-wide changes. 54* Changes generated by AI tools without substantial human review and validation. 55 56### Preparing your Pull Request 57 58Before submitting, ensure: 59 60#### Code Quality 61 62* The changes follow FreeBSD's style guide. See [Style](#Style). 63* _tools/build/checkstyle9.pl_ is run and: 64 * All errors are fixed, **or** 65 * Exceptions are documented in the PR. 66* No trailing whitespace is introduced. 67* Changes compile and work before submitting. 68* Test results (including Kyua tests) are unchanged, unless intentionally 69 modified. 70* Bug fixes include new test cases, when possible. 71 72#### Commit Structure 73 74* Each logical change is a **separate commit**. 75* Fixup commits are squashed into the commit they correct. 76* Each commit is suitable for direct inclusion in the FreeBSD's repository. 77* Pull Request scope must remain stable during review. If feedback expands 78 scope, create a new Pull Request. 79* Rebase your chages (and update with a forced push) when incorporating review 80 feedback, rather than using a merge commit. 81 82#### Commit Messages 83 84Each commit must: 85 86* Follow the [commit log message guide](https://docs.freebsd.org/en/articles/committers-guide/#commit-log-message). 87* Include one ore more `Signed-off-by:` trailers certifying [Developer Certificate of Origin](https://developercertificate.org/). 88* Include `PR: \<bugnumber\>` if fixing a Bugzilla Problem Report. 89* Include the URL of a related code review, if applicable. 90 (Avoid opening both Phabricator/Differential reviews and GitHub Pull Requests 91 for the same change.) 92 93#### Author Information 94 95* Commits use your name and valid email address. 96* GitHub-generated `users.noreply.github.com` addresses cannot be used. 97* See [Author Name and Email](#author-name-and-email) for details. 98 99### Contributor Responsibilities 100 101* Monitor your Pull Request and respond to review feedback promptly. 102* Pull Requests may be closed if there is no response for **one month**. 103 104### Additional Requirements for FreeBSD Committers 105 106* Committers submitting Pull Requests are for pushing their changes to the tree 107 (including obtaining any required approvals). 108* Pull Requests opened by FreeBSD committers may be closed after one month 109 unless there is a strong reason to keep them open. 110 111### Quality Expectations 112 113Low quality submimssions will be rejected. This includes submissions generated 114by AI tools that lack sufficient validation, testing, or understanding by the 115submitter. 116 117A pull request may be closed if there are too many obvious mistakes, or when a 118time-consuming rework is needed. 119 120Automated accounts or chatbots must not submit pull requests or use pull 121request interactions to train AI or LLM systems. 122 123Finally, if we close a pull request because it's not ready yet, or stalled out, 124please don't give up. You can resubmit them later once you have time to finish 125the work, or to have them reconsidered if you think we've made an error in 126closing it. 127 128### Author Name and Email 129 130Please use a name and email address in the `Signed-off-by` trailer and as the 131author of the git commits, since we cannot accept anonymous contributions. It is 132common, but not required, to use some form of your full name. We realize that 133some contributors are not comfortable doing so or prefer to contribute under a 134pseudonym, preferred name, chosen name or similar moniker that might not match 135relevant government records. We can accept your patch, as long as the name and 136email you use are distinctive, identifying, and not misleading. Please note that 137if your patch is accepted, the name and email address will become a permanent 138and immutable part of the public history of the FreeBSD source tree. 139 140The goal of this policy is to allow us to have sufficient information to contact 141you if questions arise about your contribution. Addresses of the form 142something@users.noreply.github.com do not meet this standard since we cannot use 143it to contact you. We can use `.mailmap` for name or email changes and mistakes, 144but is imperfect. 145 146Core (core@freebsd.org) may request authors of significant changes using an 147obvious pseudonym to document their identity more concretely should there be 148issues in the future. The author may request this documentation be kept 149confidential unless needed for legal issues arising from their contributions. 150 151## Style 152 153Avoid adding trailing newlines and whitespace. These slow down the integration 154process and are a distraction. `git diff` will highlight them in red, as will 155the Files Changed tab in the pull request. 156 157For C programs, see [style(9)](https://man.freebsd.org/cgi/man.cgi?query=style&sektion=9) 158for details. You can use [Clang format](https://clang.llvm.org/docs/ClangFormat.html) 159with the top level .clang-format file if you are unsure. The 160[git clang-format](https://github.com/llvm-mirror/clang/blob/master/tools/clang-format/git-clang-format) 161command can help minimize churn by only formatting the areas nearby the changes. While 162not perfect, using these tools will maximize your chances of not having style 163comments on your pull requests. 164 165For [Lua](https://www.lua.org), see 166[style.lua(9)](https://man.freebsd.org/cgi/man.cgi?query=style.lua&sektion=9) 167for details. Lua is used for the boot loader and a few scripts in the base system. 168 169For Makefiles changes, see 170[style.Makefile(5)](https://man.freebsd.org/cgi/man.cgi?query=style.Makefile&sektion=5) 171for details. FreeBSD's base system uses the in-tree make, not GNU Make, so 172[make(1)](https://man.freebsd.org/cgi/man.cgi?query=make&sektion=1) is another useful 173resource. 174 175For manual page changes, see 176[style.mdoc(5)](https://man.freebsd.org/cgi/man.cgi?query=style.mdoc&sektion=5) 177for details. Changes should pass `mandoc -Tlint` and igor (install the latter with `pkg install igor`). 178Please be sure to observe the one-sentence-per-line rule so manual pages properly render. 179Proposed changes to manual pages should not bump the document date until merged. 180 181For shell scripts, avoid using bash. The system shell (/bin/sh) is preferred. 182Shell scripts in the base system cannot use bash or bash extensions 183not present in FreeBSD's [shell](https://man.freebsd.org/cgi/man.cgi?query=sh&sektion=1). 184 185## Signed-off-by 186 187Other projects mandate Signed-off-by to create a paper trail for contributions they 188receive. The Developer Certificate of Origin is an attestation that the person 189making the contribution can do it under the current license of the file. Other 190projects that have 'delegated' hierarchies also use it when maintainers 191integrate these patches and submit them upstream. 192 193Right now, pull requests on GitHub are an experimental feature. We strongly 194suggest that people add this line. It creates a paper trail for infrequent 195contributors. Also, developers that are landing a pull request will use a 196Signed-off-by line to set the author for the commit. 197 198These lines are easy to add with `git commit -s`. 199 200## Submitting as part of class work 201 202If you are a professor or teacher that wishes to have your students submit fixes 203as part of their class work, please contact imp@FreeBSD.org before the semester 204to ensure we allocate the proper resources to process them quickly. We'll give 205you more details when you contact us and thanks for including FreeBSD in your 206class work. It also helps us keep track. 207 208## FreeBSD's Upstreams 209 210Anything that's in the directory `contrib`, `crypto`, `sys/contrib`, 211`sys/crypto/` or `sys/cddl` likely has an upstream we pull from. Please do a 212`git log --merges` in any subdirectory of these you are submitting patches for 213to find out the last time we merged from upstream. If it is in the last 5 years, 214upstream is "active" and you should submit your patches there and let the last 215few people to commit to this file (especially merge commits) know. If it's been 216more than 5 years, upstream is likely inactive so please submit the patch. We 217can sort out if it should go into FreeBSD or upstream. 218