| 1 | .. _process_howto:
|
| 2 |
|
| 3 | HOWTO do Linux kernel development
|
| 4 | =================================
|
| 5 |
|
| 6 | This is the be-all, end-all document on this topic. It contains
|
| 7 | instructions on how to become a Linux kernel developer and how to learn
|
| 8 | to work with the Linux kernel development community. It tries to not
|
| 9 | contain anything related to the technical aspects of kernel programming,
|
| 10 | but will help point you in the right direction for that.
|
| 11 |
|
| 12 | If anything in this document becomes out of date, please send in patches
|
| 13 | to the maintainer of this file, who is listed at the bottom of the
|
| 14 | document.
|
| 15 |
|
| 16 |
|
| 17 | Introduction
|
| 18 | ------------
|
| 19 |
|
| 20 | So, you want to learn how to become a Linux kernel developer? Or you
|
| 21 | have been told by your manager, "Go write a Linux driver for this
|
| 22 | device." This document's goal is to teach you everything you need to
|
| 23 | know to achieve this by describing the process you need to go through,
|
| 24 | and hints on how to work with the community. It will also try to
|
| 25 | explain some of the reasons why the community works like it does.
|
| 26 |
|
| 27 | The kernel is written mostly in C, with some architecture-dependent
|
| 28 | parts written in assembly. A good understanding of C is required for
|
| 29 | kernel development. Assembly (any architecture) is not required unless
|
| 30 | you plan to do low-level development for that architecture. Though they
|
| 31 | are not a good substitute for a solid C education and/or years of
|
| 32 | experience, the following books are good for, if anything, reference:
|
| 33 |
|
| 34 | - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
|
| 35 | - "Practical C Programming" by Steve Oualline [O'Reilly]
|
| 36 | - "C: A Reference Manual" by Harbison and Steele [Prentice Hall]
|
| 37 |
|
| 38 | The kernel is written using GNU C and the GNU toolchain. While it
|
| 39 | adheres to the ISO C11 standard, it uses a number of extensions that are
|
| 40 | not featured in the standard. The kernel is a freestanding C
|
| 41 | environment, with no reliance on the standard C library, so some
|
| 42 | portions of the C standard are not supported. Arbitrary long long
|
| 43 | divisions and floating point are not allowed. It can sometimes be
|
| 44 | difficult to understand the assumptions the kernel has on the toolchain
|
| 45 | and the extensions that it uses, and unfortunately there is no
|
| 46 | definitive reference for them. Please check the gcc info pages (`info
|
| 47 | gcc`) for some information on them.
|
| 48 |
|
| 49 | Please remember that you are trying to learn how to work with the
|
| 50 | existing development community. It is a diverse group of people, with
|
| 51 | high standards for coding, style and procedure. These standards have
|
| 52 | been created over time based on what they have found to work best for
|
| 53 | such a large and geographically dispersed team. Try to learn as much as
|
| 54 | possible about these standards ahead of time, as they are well
|
| 55 | documented; do not expect people to adapt to you or your company's way
|
| 56 | of doing things.
|
| 57 |
|
| 58 |
|
| 59 | Legal Issues
|
| 60 | ------------
|
| 61 |
|
| 62 | The Linux kernel source code is released under the GPL. Please see the file
|
| 63 | COPYING in the main directory of the source tree. The Linux kernel licensing
|
| 64 | rules and how to use `SPDX <https://spdx.org/>`_ identifiers in source code are
|
| 65 | described in :ref:`Documentation/process/license-rules.rst <kernel_licensing>`.
|
| 66 | If you have further questions about the license, please contact a lawyer, and do
|
| 67 | not ask on the Linux kernel mailing list. The people on the mailing lists are
|
| 68 | not lawyers, and you should not rely on their statements on legal matters.
|
| 69 |
|
| 70 | For common questions and answers about the GPL, please see:
|
| 71 |
|
| 72 | https://www.gnu.org/licenses/gpl-faq.html
|
| 73 |
|
| 74 |
|
| 75 | Documentation
|
| 76 | -------------
|
| 77 |
|
| 78 | The Linux kernel source tree has a large range of documents that are
|
| 79 | invaluable for learning how to interact with the kernel community. When
|
| 80 | new features are added to the kernel, it is recommended that new
|
| 81 | documentation files are also added which explain how to use the feature.
|
| 82 | When a kernel change causes the interface that the kernel exposes to
|
| 83 | userspace to change, it is recommended that you send the information or
|
| 84 | a patch to the manual pages explaining the change to the manual pages
|
| 85 | maintainer at [email protected], and CC the list [email protected].
|
| 86 |
|
| 87 | Here is a list of files that are in the kernel source tree that are
|
| 88 | required reading:
|
| 89 |
|
| 90 | :ref:`Documentation/admin-guide/README.rst <readme>`
|
| 91 | This file gives a short background on the Linux kernel and describes
|
| 92 | what is necessary to do to configure and build the kernel. People
|
| 93 | who are new to the kernel should start here.
|
| 94 |
|
| 95 | :ref:`Documentation/process/changes.rst <changes>`
|
| 96 | This file gives a list of the minimum levels of various software
|
| 97 | packages that are necessary to build and run the kernel
|
| 98 | successfully.
|
| 99 |
|
| 100 | :ref:`Documentation/process/coding-style.rst <codingstyle>`
|
| 101 | This describes the Linux kernel coding style, and some of the
|
| 102 | rationale behind it. All new code is expected to follow the
|
| 103 | guidelines in this document. Most maintainers will only accept
|
| 104 | patches if these rules are followed, and many people will only
|
| 105 | review code if it is in the proper style.
|
| 106 |
|
| 107 | :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
|
| 108 | This file describes in explicit detail how to successfully create
|
| 109 | and send a patch, including (but not limited to):
|
| 110 |
|
| 111 | - Email contents
|
| 112 | - Email format
|
| 113 | - Who to send it to
|
| 114 |
|
| 115 | Following these rules will not guarantee success (as all patches are
|
| 116 | subject to scrutiny for content and style), but not following them
|
| 117 | will almost always prevent it.
|
| 118 |
|
| 119 | Other excellent descriptions of how to create patches properly are:
|
| 120 |
|
| 121 | "The Perfect Patch"
|
| 122 | https://www.ozlabs.org/~akpm/stuff/tpp.txt
|
| 123 |
|
| 124 | "Linux kernel patch submission format"
|
| 125 | https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html
|
| 126 |
|
| 127 | :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>`
|
| 128 | This file describes the rationale behind the conscious decision to
|
| 129 | not have a stable API within the kernel, including things like:
|
| 130 |
|
| 131 | - Subsystem shim-layers (for compatibility?)
|
| 132 | - Driver portability between Operating Systems.
|
| 133 | - Mitigating rapid change within the kernel source tree (or
|
| 134 | preventing rapid change)
|
| 135 |
|
| 136 | This document is crucial for understanding the Linux development
|
| 137 | philosophy and is very important for people moving to Linux from
|
| 138 | development on other Operating Systems.
|
| 139 |
|
| 140 | :ref:`Documentation/process/security-bugs.rst <securitybugs>`
|
| 141 | If you feel you have found a security problem in the Linux kernel,
|
| 142 | please follow the steps in this document to help notify the kernel
|
| 143 | developers, and help solve the issue.
|
| 144 |
|
| 145 | :ref:`Documentation/process/management-style.rst <managementstyle>`
|
| 146 | This document describes how Linux kernel maintainers operate and the
|
| 147 | shared ethos behind their methodologies. This is important reading
|
| 148 | for anyone new to kernel development (or anyone simply curious about
|
| 149 | it), as it resolves a lot of common misconceptions and confusion
|
| 150 | about the unique behavior of kernel maintainers.
|
| 151 |
|
| 152 | :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
|
| 153 | This file describes the rules on how the stable kernel releases
|
| 154 | happen, and what to do if you want to get a change into one of these
|
| 155 | releases.
|
| 156 |
|
| 157 | :ref:`Documentation/process/kernel-docs.rst <kernel_docs>`
|
| 158 | A list of external documentation that pertains to kernel
|
| 159 | development. Please consult this list if you do not find what you
|
| 160 | are looking for within the in-kernel documentation.
|
| 161 |
|
| 162 | :ref:`Documentation/process/applying-patches.rst <applying_patches>`
|
| 163 | A good introduction describing exactly what a patch is and how to
|
| 164 | apply it to the different development branches of the kernel.
|
| 165 |
|
| 166 | The kernel also has a large number of documents that can be
|
| 167 | automatically generated from the source code itself or from
|
| 168 | ReStructuredText markups (ReST), like this one. This includes a
|
| 169 | full description of the in-kernel API, and rules on how to handle
|
| 170 | locking properly.
|
| 171 |
|
| 172 | All such documents can be generated as PDF or HTML by running::
|
| 173 |
|
| 174 | make pdfdocs
|
| 175 | make htmldocs
|
| 176 |
|
| 177 | respectively from the main kernel source directory.
|
| 178 |
|
| 179 | The documents that uses ReST markup will be generated at Documentation/output.
|
| 180 | They can also be generated on LaTeX and ePub formats with::
|
| 181 |
|
| 182 | make latexdocs
|
| 183 | make epubdocs
|
| 184 |
|
| 185 | Becoming A Kernel Developer
|
| 186 | ---------------------------
|
| 187 |
|
| 188 | If you do not know anything about Linux kernel development, you should
|
| 189 | look at the Linux KernelNewbies project:
|
| 190 |
|
| 191 | https://kernelnewbies.org
|
| 192 |
|
| 193 | It consists of a helpful mailing list where you can ask almost any type
|
| 194 | of basic kernel development question (make sure to search the archives
|
| 195 | first, before asking something that has already been answered in the
|
| 196 | past.) It also has an IRC channel that you can use to ask questions in
|
| 197 | real-time, and a lot of helpful documentation that is useful for
|
| 198 | learning about Linux kernel development.
|
| 199 |
|
| 200 | The website has basic information about code organization, subsystems,
|
| 201 | and current projects (both in-tree and out-of-tree). It also describes
|
| 202 | some basic logistical information, like how to compile a kernel and
|
| 203 | apply a patch.
|
| 204 |
|
| 205 | If you do not know where you want to start, but you want to look for
|
| 206 | some task to start doing to join into the kernel development community,
|
| 207 | go to the Linux Kernel Janitor's project:
|
| 208 |
|
| 209 | https://kernelnewbies.org/KernelJanitors
|
| 210 |
|
| 211 | It is a great place to start. It describes a list of relatively simple
|
| 212 | problems that need to be cleaned up and fixed within the Linux kernel
|
| 213 | source tree. Working with the developers in charge of this project, you
|
| 214 | will learn the basics of getting your patch into the Linux kernel tree,
|
| 215 | and possibly be pointed in the direction of what to go work on next, if
|
| 216 | you do not already have an idea.
|
| 217 |
|
| 218 | Before making any actual modifications to the Linux kernel code, it is
|
| 219 | imperative to understand how the code in question works. For this
|
| 220 | purpose, nothing is better than reading through it directly (most tricky
|
| 221 | bits are commented well), perhaps even with the help of specialized
|
| 222 | tools. One such tool that is particularly recommended is the Linux
|
| 223 | Cross-Reference project, which is able to present source code in a
|
| 224 | self-referential, indexed webpage format. An excellent up-to-date
|
| 225 | repository of the kernel code may be found at:
|
| 226 |
|
| 227 | https://elixir.bootlin.com/
|
| 228 |
|
| 229 |
|
| 230 | The development process
|
| 231 | -----------------------
|
| 232 |
|
| 233 | Linux kernel development process currently consists of a few different
|
| 234 | main kernel "branches" and lots of different subsystem-specific kernel
|
| 235 | branches. These different branches are:
|
| 236 |
|
| 237 | - Linus's mainline tree
|
| 238 | - Various stable trees with multiple major numbers
|
| 239 | - Subsystem-specific trees
|
| 240 | - linux-next integration testing tree
|
| 241 |
|
| 242 | Mainline tree
|
| 243 | ~~~~~~~~~~~~~
|
| 244 |
|
| 245 | The mainline tree is maintained by Linus Torvalds, and can be found at
|
| 246 | https://kernel.org or in the repo. Its development process is as follows:
|
| 247 |
|
| 248 | - As soon as a new kernel is released a two week window is open,
|
| 249 | during this period of time maintainers can submit big diffs to
|
| 250 | Linus, usually the patches that have already been included in the
|
| 251 | linux-next for a few weeks. The preferred way to submit big changes
|
| 252 | is using git (the kernel's source management tool, more information
|
| 253 | can be found at https://git-scm.com/) but plain patches are also just
|
| 254 | fine.
|
| 255 | - After two weeks a -rc1 kernel is released and the focus is on making the
|
| 256 | new kernel as rock solid as possible. Most of the patches at this point
|
| 257 | should fix a regression. Bugs that have always existed are not
|
| 258 | regressions, so only push these kinds of fixes if they are important.
|
| 259 | Please note that a whole new driver (or filesystem) might be accepted
|
| 260 | after -rc1 because there is no risk of causing regressions with such a
|
| 261 | change as long as the change is self-contained and does not affect areas
|
| 262 | outside of the code that is being added. git can be used to send
|
| 263 | patches to Linus after -rc1 is released, but the patches need to also be
|
| 264 | sent to a public mailing list for review.
|
| 265 | - A new -rc is released whenever Linus deems the current git tree to
|
| 266 | be in a reasonably sane state adequate for testing. The goal is to
|
| 267 | release a new -rc kernel every week.
|
| 268 | - Process continues until the kernel is considered "ready", the
|
| 269 | process should last around 6 weeks.
|
| 270 |
|
| 271 | It is worth mentioning what Andrew Morton wrote on the linux-kernel
|
| 272 | mailing list about kernel releases:
|
| 273 |
|
| 274 | *"Nobody knows when a kernel will be released, because it's
|
| 275 | released according to perceived bug status, not according to a
|
| 276 | preconceived timeline."*
|
| 277 |
|
| 278 | Various stable trees with multiple major numbers
|
| 279 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 280 |
|
| 281 | Kernels with 3-part versions are -stable kernels. They contain
|
| 282 | relatively small and critical fixes for security problems or significant
|
| 283 | regressions discovered in a given major mainline release. Each release
|
| 284 | in a major stable series increments the third part of the version
|
| 285 | number, keeping the first two parts the same.
|
| 286 |
|
| 287 | This is the recommended branch for users who want the most recent stable
|
| 288 | kernel and are not interested in helping test development/experimental
|
| 289 | versions.
|
| 290 |
|
| 291 | Stable trees are maintained by the "stable" team <[email protected]>, and
|
| 292 | are released as needs dictate. The normal release period is approximately
|
| 293 | two weeks, but it can be longer if there are no pressing problems. A
|
| 294 | security-related problem, instead, can cause a release to happen almost
|
| 295 | instantly.
|
| 296 |
|
| 297 | The file :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
|
| 298 | in the kernel tree documents what kinds of changes are acceptable for
|
| 299 | the -stable tree, and how the release process works.
|
| 300 |
|
| 301 | Subsystem-specific trees
|
| 302 | ~~~~~~~~~~~~~~~~~~~~~~~~
|
| 303 |
|
| 304 | The maintainers of the various kernel subsystems --- and also many
|
| 305 | kernel subsystem developers --- expose their current state of
|
| 306 | development in source repositories. That way, others can see what is
|
| 307 | happening in the different areas of the kernel. In areas where
|
| 308 | development is rapid, a developer may be asked to base their submissions
|
| 309 | onto such a subsystem kernel tree so that conflicts between the
|
| 310 | submission and other already ongoing work are avoided.
|
| 311 |
|
| 312 | Most of these repositories are git trees, but there are also other SCMs
|
| 313 | in use, or patch queues being published as quilt series. Addresses of
|
| 314 | these subsystem repositories are listed in the MAINTAINERS file. Many
|
| 315 | of them can be browsed at https://git.kernel.org/.
|
| 316 |
|
| 317 | Before a proposed patch is committed to such a subsystem tree, it is
|
| 318 | subject to review which primarily happens on mailing lists (see the
|
| 319 | respective section below). For several kernel subsystems, this review
|
| 320 | process is tracked with the tool patchwork. Patchwork offers a web
|
| 321 | interface which shows patch postings, any comments on a patch or
|
| 322 | revisions to it, and maintainers can mark patches as under review,
|
| 323 | accepted, or rejected. Most of these patchwork sites are listed at
|
| 324 | https://patchwork.kernel.org/.
|
| 325 |
|
| 326 | linux-next integration testing tree
|
| 327 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
| 328 |
|
| 329 | Before updates from subsystem trees are merged into the mainline tree,
|
| 330 | they need to be integration-tested. For this purpose, a special
|
| 331 | testing repository exists into which virtually all subsystem trees are
|
| 332 | pulled on an almost daily basis:
|
| 333 |
|
| 334 | https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git
|
| 335 |
|
| 336 | This way, the linux-next gives a summary outlook onto what will be
|
| 337 | expected to go into the mainline kernel at the next merge period.
|
| 338 | Adventurous testers are very welcome to runtime-test the linux-next.
|
| 339 |
|
| 340 |
|
| 341 | Bug Reporting
|
| 342 | -------------
|
| 343 |
|
| 344 | The file 'Documentation/admin-guide/reporting-issues.rst' in the main kernel
|
| 345 | source directory describes how to report a possible kernel bug, and details
|
| 346 | what kind of information is needed by the kernel developers to help track
|
| 347 | down the problem.
|
| 348 |
|
| 349 |
|
| 350 | Managing bug reports
|
| 351 | --------------------
|
| 352 |
|
| 353 | One of the best ways to put into practice your hacking skills is by fixing
|
| 354 | bugs reported by other people. Not only will you help to make the kernel
|
| 355 | more stable, but you'll also learn to fix real-world problems and you will
|
| 356 | improve your skills, and other developers will be aware of your presence.
|
| 357 | Fixing bugs is one of the best ways to get merits among other developers,
|
| 358 | because not many people like wasting time fixing other people's bugs.
|
| 359 |
|
| 360 | To work on already reported bug reports, find a subsystem you are interested in.
|
| 361 | Check the MAINTAINERS file where bugs for that subsystem get reported to; often
|
| 362 | it will be a mailing list, rarely a bugtracker. Search the archives of said
|
| 363 | place for recent reports and help where you see fit. You may also want to check
|
| 364 | https://bugzilla.kernel.org for bug reports; only a handful of kernel subsystems
|
| 365 | use it actively for reporting or tracking, nevertheless bugs for the whole
|
| 366 | kernel get filed there.
|
| 367 |
|
| 368 |
|
| 369 | Mailing lists
|
| 370 | -------------
|
| 371 |
|
| 372 | As some of the above documents describe, the majority of the core kernel
|
| 373 | developers participate on the Linux Kernel Mailing list. Details on how
|
| 374 | to subscribe and unsubscribe from the list can be found at:
|
| 375 |
|
| 376 | https://subspace.kernel.org/subscribing.html
|
| 377 |
|
| 378 | There are archives of the mailing list on the web in many different
|
| 379 | places. Use a search engine to find these archives. For example:
|
| 380 |
|
| 381 | https://lore.kernel.org/linux-kernel/
|
| 382 |
|
| 383 | It is highly recommended that you search the archives about the topic
|
| 384 | you want to bring up, before you post it to the list. A lot of things
|
| 385 | already discussed in detail are only recorded at the mailing list
|
| 386 | archives.
|
| 387 |
|
| 388 | Most of the individual kernel subsystems also have their own separate
|
| 389 | mailing list where they do their development efforts. See the
|
| 390 | MAINTAINERS file for a list of what these lists are for the different
|
| 391 | groups.
|
| 392 |
|
| 393 | Many of the lists are hosted on kernel.org. Information on them can be
|
| 394 | found at:
|
| 395 |
|
| 396 | https://subspace.kernel.org
|
| 397 |
|
| 398 | Please remember to follow good behavioral habits when using the lists.
|
| 399 | Though a bit cheesy, the following URL has some simple guidelines for
|
| 400 | interacting with the list (or any list):
|
| 401 |
|
| 402 | https://subspace.kernel.org/etiquette.html
|
| 403 |
|
| 404 | If multiple people respond to your mail, the CC: list of recipients may
|
| 405 | get pretty large. Don't remove anybody from the CC: list without a good
|
| 406 | reason, or don't reply only to the list address. Get used to receiving the
|
| 407 | mail twice, one from the sender and the one from the list, and don't try
|
| 408 | to tune that by adding fancy mail-headers, people will not like it.
|
| 409 |
|
| 410 | Remember to keep the context and the attribution of your replies intact,
|
| 411 | keep the "John Kernelhacker wrote ...:" lines at the top of your reply, and
|
| 412 | add your statements between the individual quoted sections instead of
|
| 413 | writing at the top of the mail.
|
| 414 |
|
| 415 | If you add patches to your mail, make sure they are plain readable text
|
| 416 | as stated in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
|
| 417 | Kernel developers don't want to deal with
|
| 418 | attachments or compressed patches; they may want to comment on
|
| 419 | individual lines of your patch, which works only that way. Make sure you
|
| 420 | use a mail program that does not mangle spaces and tab characters. A
|
| 421 | good first test is to send the mail to yourself and try to apply your
|
| 422 | own patch by yourself. If that doesn't work, get your mail program fixed
|
| 423 | or change it until it works.
|
| 424 |
|
| 425 | Above all, please remember to show respect to other subscribers.
|
| 426 |
|
| 427 |
|
| 428 | Working with the community
|
| 429 | --------------------------
|
| 430 |
|
| 431 | The goal of the kernel community is to provide the best possible kernel
|
| 432 | there is. When you submit a patch for acceptance, it will be reviewed
|
| 433 | on its technical merits and those alone. So, what should you be
|
| 434 | expecting?
|
| 435 |
|
| 436 | - criticism
|
| 437 | - comments
|
| 438 | - requests for change
|
| 439 | - requests for justification
|
| 440 | - silence
|
| 441 |
|
| 442 | Remember, this is part of getting your patch into the kernel. You have
|
| 443 | to be able to take criticism and comments about your patches, evaluate
|
| 444 | them at a technical level and either rework your patches or provide
|
| 445 | clear and concise reasoning as to why those changes should not be made.
|
| 446 | If there are no responses to your posting, wait a few days and try
|
| 447 | again, sometimes things get lost in the huge volume.
|
| 448 |
|
| 449 | What should you not do?
|
| 450 |
|
| 451 | - expect your patch to be accepted without question
|
| 452 | - become defensive
|
| 453 | - ignore comments
|
| 454 | - resubmit the patch without making any of the requested changes
|
| 455 |
|
| 456 | In a community that is looking for the best technical solution possible,
|
| 457 | there will always be differing opinions on how beneficial a patch is.
|
| 458 | You have to be cooperative, and willing to adapt your idea to fit within
|
| 459 | the kernel. Or at least be willing to prove your idea is worth it.
|
| 460 | Remember, being wrong is acceptable as long as you are willing to work
|
| 461 | toward a solution that is right.
|
| 462 |
|
| 463 | It is normal that the answers to your first patch might simply be a list
|
| 464 | of a dozen things you should correct. This does **not** imply that your
|
| 465 | patch will not be accepted, and it is **not** meant against you
|
| 466 | personally. Simply correct all issues raised against your patch and
|
| 467 | resend it.
|
| 468 |
|
| 469 |
|
| 470 | Differences between the kernel community and corporate structures
|
| 471 | -----------------------------------------------------------------
|
| 472 |
|
| 473 | The kernel community works differently than most traditional corporate
|
| 474 | development environments. Here are a list of things that you can try to
|
| 475 | do to avoid problems:
|
| 476 |
|
| 477 | Good things to say regarding your proposed changes:
|
| 478 |
|
| 479 | - "This solves multiple problems."
|
| 480 | - "This deletes 2000 lines of code."
|
| 481 | - "Here is a patch that explains what I am trying to describe."
|
| 482 | - "I tested it on 5 different architectures..."
|
| 483 | - "Here is a series of small patches that..."
|
| 484 | - "This increases performance on typical machines..."
|
| 485 |
|
| 486 | Bad things you should avoid saying:
|
| 487 |
|
| 488 | - "We did it this way in AIX/ptx/Solaris, so therefore it must be
|
| 489 | good..."
|
| 490 | - "I've being doing this for 20 years, so..."
|
| 491 | - "This is required for my company to make money"
|
| 492 | - "This is for our Enterprise product line."
|
| 493 | - "Here is my 1000 page design document that describes my idea"
|
| 494 | - "I've been working on this for 6 months..."
|
| 495 | - "Here's a 5000 line patch that..."
|
| 496 | - "I rewrote all of the current mess, and here it is..."
|
| 497 | - "I have a deadline, and this patch needs to be applied now."
|
| 498 |
|
| 499 | Another way the kernel community is different than most traditional
|
| 500 | software engineering work environments is the faceless nature of
|
| 501 | interaction. One benefit of using email and irc as the primary forms of
|
| 502 | communication is the lack of discrimination based on gender or race.
|
| 503 | The Linux kernel work environment is accepting of women and minorities
|
| 504 | because all you are is an email address. The international aspect also
|
| 505 | helps to level the playing field because you can't guess gender based on
|
| 506 | a person's name. A man may be named Andrea and a woman may be named Pat.
|
| 507 | Most women who have worked in the Linux kernel and have expressed an
|
| 508 | opinion have had positive experiences.
|
| 509 |
|
| 510 | The language barrier can cause problems for some people who are not
|
| 511 | comfortable with English. A good grasp of the language can be needed in
|
| 512 | order to get ideas across properly on mailing lists, so it is
|
| 513 | recommended that you check your emails to make sure they make sense in
|
| 514 | English before sending them.
|
| 515 |
|
| 516 |
|
| 517 | Break up your changes
|
| 518 | ---------------------
|
| 519 |
|
| 520 | The Linux kernel community does not gladly accept large chunks of code
|
| 521 | dropped on it all at once. The changes need to be properly introduced,
|
| 522 | discussed, and broken up into tiny, individual portions. This is almost
|
| 523 | the exact opposite of what companies are used to doing. Your proposal
|
| 524 | should also be introduced very early in the development process, so that
|
| 525 | you can receive feedback on what you are doing. It also lets the
|
| 526 | community feel that you are working with them, and not simply using them
|
| 527 | as a dumping ground for your feature. However, don't send 50 emails at
|
| 528 | one time to a mailing list, your patch series should be smaller than
|
| 529 | that almost all of the time.
|
| 530 |
|
| 531 | The reasons for breaking things up are the following:
|
| 532 |
|
| 533 | 1) Small patches increase the likelihood that your patches will be
|
| 534 | applied, since they don't take much time or effort to verify for
|
| 535 | correctness. A 5 line patch can be applied by a maintainer with
|
| 536 | barely a second glance. However, a 500 line patch may take hours to
|
| 537 | review for correctness (the time it takes is exponentially
|
| 538 | proportional to the size of the patch, or something).
|
| 539 |
|
| 540 | Small patches also make it very easy to debug when something goes
|
| 541 | wrong. It's much easier to back out patches one by one than it is
|
| 542 | to dissect a very large patch after it's been applied (and broken
|
| 543 | something).
|
| 544 |
|
| 545 | 2) It's important not only to send small patches, but also to rewrite
|
| 546 | and simplify (or simply re-order) patches before submitting them.
|
| 547 |
|
| 548 | Here is an analogy from kernel developer Al Viro:
|
| 549 |
|
| 550 | *"Think of a teacher grading homework from a math student. The
|
| 551 | teacher does not want to see the student's trials and errors
|
| 552 | before they came up with the solution. They want to see the
|
| 553 | cleanest, most elegant answer. A good student knows this, and
|
| 554 | would never submit her intermediate work before the final
|
| 555 | solution.*
|
| 556 |
|
| 557 | *The same is true of kernel development. The maintainers and
|
| 558 | reviewers do not want to see the thought process behind the
|
| 559 | solution to the problem one is solving. They want to see a
|
| 560 | simple and elegant solution."*
|
| 561 |
|
| 562 | It may be challenging to keep the balance between presenting an elegant
|
| 563 | solution and working together with the community and discussing your
|
| 564 | unfinished work. Therefore it is good to get early in the process to
|
| 565 | get feedback to improve your work, but also keep your changes in small
|
| 566 | chunks that they may get already accepted, even when your whole task is
|
| 567 | not ready for inclusion now.
|
| 568 |
|
| 569 | Also realize that it is not acceptable to send patches for inclusion
|
| 570 | that are unfinished and will be "fixed up later."
|
| 571 |
|
| 572 |
|
| 573 | Justify your change
|
| 574 | -------------------
|
| 575 |
|
| 576 | Along with breaking up your patches, it is very important for you to let
|
| 577 | the Linux community know why they should add this change. New features
|
| 578 | must be justified as being needed and useful.
|
| 579 |
|
| 580 |
|
| 581 | Document your change
|
| 582 | --------------------
|
| 583 |
|
| 584 | When sending in your patches, pay special attention to what you say in
|
| 585 | the text in your email. This information will become the ChangeLog
|
| 586 | information for the patch, and will be preserved for everyone to see for
|
| 587 | all time. It should describe the patch completely, containing:
|
| 588 |
|
| 589 | - why the change is necessary
|
| 590 | - the overall design approach in the patch
|
| 591 | - implementation details
|
| 592 | - testing results
|
| 593 |
|
| 594 | For more details on what this should all look like, please see the
|
| 595 | ChangeLog section of the document:
|
| 596 |
|
| 597 | "The Perfect Patch"
|
| 598 | https://www.ozlabs.org/~akpm/stuff/tpp.txt
|
| 599 |
|
| 600 |
|
| 601 | All of these things are sometimes very hard to do. It can take years to
|
| 602 | perfect these practices (if at all). It's a continuous process of
|
| 603 | improvement that requires a lot of patience and determination. But
|
| 604 | don't give up, it's possible. Many have done it before, and each had to
|
| 605 | start exactly where you are now.
|
| 606 |
|
| 607 |
|
| 608 |
|
| 609 |
|
| 610 | ----------
|
| 611 |
|
| 612 | Thanks to Paolo Ciarrocchi who allowed the "Development Process"
|
| 613 | (https://lwn.net/Articles/94386/) section
|
| 614 | to be based on text he had written, and to Randy Dunlap and Gerrit
|
| 615 | Huizenga for some of the list of things you should and should not say.
|
| 616 | Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers,
|
| 617 | Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi
|
| 618 | Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop,
|
| 619 | David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard for
|
| 620 | their review, comments, and contributions. Without their help, this
|
| 621 | document would not have been possible.
|
| 622 |
|
| 623 |
|
| 624 |
|
| 625 | Maintainer: Greg Kroah-Hartman <[email protected]>
|