CONTRIBUTING.md

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