diff options
Diffstat (limited to 'Documentation/process/howto.rst')
| -rw-r--r-- | Documentation/process/howto.rst | 159 |
1 files changed, 67 insertions, 92 deletions
diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index c6875b1db56f..9438e03d6f50 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -1,3 +1,5 @@ +.. _process_howto: + HOWTO do Linux kernel development ================================= @@ -34,7 +36,7 @@ experience, the following books are good for, if anything, reference: - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] The kernel is written using GNU C and the GNU toolchain. While it -adheres to the ISO C89 standard, it uses a number of extensions that are +adheres to the ISO C11 standard, it uses a number of extensions that are not featured in the standard. The kernel is a freestanding C environment, with no reliance on the standard C library, so some portions of the C standard are not supported. Arbitrary long long @@ -57,12 +59,13 @@ of doing things. Legal Issues ------------ -The Linux kernel source code is released under the GPL. Please see the -file, COPYING, in the main directory of the source tree, for details on -the license. If you have further questions about the license, please -contact a lawyer, and do not ask on the Linux kernel mailing list. The -people on the mailing lists are not lawyers, and you should not rely on -their statements on legal matters. +The Linux kernel source code is released under the GPL. Please see the file +COPYING in the main directory of the source tree. The Linux kernel licensing +rules and how to use `SPDX <https://spdx.org/>`_ identifiers in source code are +described in :ref:`Documentation/process/license-rules.rst <kernel_licensing>`. +If you have further questions about the license, please contact a lawyer, and do +not ask on the Linux kernel mailing list. The people on the mailing lists are +not lawyers, and you should not rely on their statements on legal matters. For common questions and answers about the GPL, please see: @@ -79,13 +82,12 @@ documentation files are also added which explain how to use the feature. When a kernel change causes the interface that the kernel exposes to userspace to change, it is recommended that you send the information or a patch to the manual pages explaining the change to the manual pages -maintainer at mtk.manpages@gmail.com, and CC the list -linux-api@vger.kernel.org. +maintainer at alx@kernel.org, and CC the list linux-api@vger.kernel.org. Here is a list of files that are in the kernel source tree that are required reading: - README + :ref:`Documentation/admin-guide/README.rst <readme>` This file gives a short background on the Linux kernel and describes what is necessary to do to configure and build the kernel. People who are new to the kernel should start here. @@ -102,8 +104,8 @@ required reading: patches if these rules are followed, and many people will only review code if it is in the proper style. - :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` and :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` - These files describe in explicit detail how to successfully create + :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` + This file describes in explicit detail how to successfully create and send a patch, including (but not limited to): - Email contents @@ -120,7 +122,7 @@ required reading: https://www.ozlabs.org/~akpm/stuff/tpp.txt "Linux kernel patch submission format" - http://linux.yyz.us/patch-format.html + https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>` This file describes the rationale behind the conscious decision to @@ -135,7 +137,7 @@ required reading: philosophy and is very important for people moving to Linux from development on other Operating Systems. - :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` + :ref:`Documentation/process/security-bugs.rst <securitybugs>` If you feel you have found a security problem in the Linux kernel, please follow the steps in this document to help notify the kernel developers, and help solve the issue. @@ -213,13 +215,6 @@ will learn the basics of getting your patch into the Linux kernel tree, and possibly be pointed in the direction of what to go work on next, if you do not already have an idea. -If you already have a chunk of code that you want to put into the kernel -tree, but need some help getting it in the proper form, the -kernel-mentors project was created to help you out with this. It is a -mailing list, and can be found at: - - https://selenic.com/mailman/listinfo/kernel-mentors - Before making any actual modifications to the Linux kernel code, it is imperative to understand how the code in question works. For this purpose, nothing is better than reading through it directly (most tricky @@ -229,7 +224,7 @@ Cross-Reference project, which is able to present source code in a self-referential, indexed webpage format. An excellent up-to-date repository of the kernel code may be found at: - http://lxr.free-electrons.com/ + https://elixir.bootlin.com/ The development process @@ -239,23 +234,21 @@ Linux kernel development process currently consists of a few different main kernel "branches" and lots of different subsystem-specific kernel branches. These different branches are: - - main 4.x kernel tree - - 4.x.y -stable kernel tree - - 4.x -git kernel patches - - subsystem specific kernel trees and patches - - the 4.x -next kernel tree for integration tests + - Linus's mainline tree + - Various stable trees with multiple major numbers + - Subsystem-specific trees + - linux-next integration testing tree -4.x kernel tree -~~~~~~~~~~~~~~~ +Mainline tree +~~~~~~~~~~~~~ -4.x kernels are maintained by Linus Torvalds, and can be found on -https://kernel.org in the pub/linux/kernel/v4.x/ directory. Its development -process is as follows: +The mainline tree is maintained by Linus Torvalds, and can be found at +https://kernel.org or in the repo. Its development process is as follows: - - As soon as a new kernel is released a two weeks window is open, + - As soon as a new kernel is released a two week window is open, during this period of time maintainers can submit big diffs to Linus, usually the patches that have already been included in the - -next kernel for a few weeks. The preferred way to submit big changes + linux-next for a few weeks. The preferred way to submit big changes is using git (the kernel's source management tool, more information can be found at https://git-scm.com/) but plain patches are also just fine. @@ -282,41 +275,31 @@ mailing list about kernel releases: released according to perceived bug status, not according to a preconceived timeline."* -4.x.y -stable kernel tree -~~~~~~~~~~~~~~~~~~~~~~~~~ +Various stable trees with multiple major numbers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Kernels with 3-part versions are -stable kernels. They contain relatively small and critical fixes for security problems or significant -regressions discovered in a given 4.x kernel. +regressions discovered in a given major mainline release. Each release +in a major stable series increments the third part of the version +number, keeping the first two parts the same. This is the recommended branch for users who want the most recent stable kernel and are not interested in helping test development/experimental versions. -If no 4.x.y kernel is available, then the highest numbered 4.x -kernel is the current stable kernel. - -4.x.y are maintained by the "stable" team <stable@vger.kernel.org>, and +Stable trees are maintained by the "stable" team <stable@vger.kernel.org>, and are released as needs dictate. The normal release period is approximately two weeks, but it can be longer if there are no pressing problems. A security-related problem, instead, can cause a release to happen almost instantly. -The file Documentation/process/stable-kernel-rules.rst in the kernel tree -documents what kinds of changes are acceptable for the -stable tree, and -how the release process works. - -4.x -git patches -~~~~~~~~~~~~~~~~ - -These are daily snapshots of Linus' kernel tree which are managed in a -git repository (hence the name.) These patches are usually released -daily and represent the current state of Linus' tree. They are more -experimental than -rc kernels since they are generated automatically -without even a cursory glance to see if they are sane. +The file :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>` +in the kernel tree documents what kinds of changes are acceptable for +the -stable tree, and how the release process works. -Subsystem Specific kernel trees and patches -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Subsystem-specific trees +~~~~~~~~~~~~~~~~~~~~~~~~ The maintainers of the various kernel subsystems --- and also many kernel subsystem developers --- expose their current state of @@ -340,55 +323,47 @@ revisions to it, and maintainers can mark patches as under review, accepted, or rejected. Most of these patchwork sites are listed at https://patchwork.kernel.org/. -4.x -next kernel tree for integration tests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +linux-next integration testing tree +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Before updates from subsystem trees are merged into the mainline 4.x -tree, they need to be integration-tested. For this purpose, a special +Before updates from subsystem trees are merged into the mainline tree, +they need to be integration-tested. For this purpose, a special testing repository exists into which virtually all subsystem trees are pulled on an almost daily basis: - https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git + https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git -This way, the -next kernel gives a summary outlook onto what will be +This way, the linux-next gives a summary outlook onto what will be expected to go into the mainline kernel at the next merge period. -Adventurous testers are very welcome to runtime-test the -next kernel. +Adventurous testers are very welcome to runtime-test the linux-next. Bug Reporting ------------- -https://bugzilla.kernel.org is where the Linux kernel developers track kernel -bugs. Users are encouraged to report all bugs that they find in this -tool. For details on how to use the kernel bugzilla, please see: - - https://bugzilla.kernel.org/page.cgi?id=faq.html - -The file admin-guide/reporting-bugs.rst in the main kernel source directory has a good -template for how to report a possible kernel bug, and details what kind -of information is needed by the kernel developers to help track down the -problem. +The file 'Documentation/admin-guide/reporting-issues.rst' in the main kernel +source directory describes how to report a possible kernel bug, and details +what kind of information is needed by the kernel developers to help track +down the problem. Managing bug reports -------------------- One of the best ways to put into practice your hacking skills is by fixing -bugs reported by other people. Not only you will help to make the kernel -more stable, you'll learn to fix real world problems and you will improve -your skills, and other developers will be aware of your presence. Fixing -bugs is one of the best ways to get merits among other developers, because -not many people like wasting time fixing other people's bugs. - -To work in the already reported bug reports, go to https://bugzilla.kernel.org. -If you want to be advised of the future bug reports, you can subscribe to the -bugme-new mailing list (only new bug reports are mailed here) or to the -bugme-janitor mailing list (every change in the bugzilla is mailed here) - - https://lists.linux-foundation.org/mailman/listinfo/bugme-new - - https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors +bugs reported by other people. Not only will you help to make the kernel +more stable, but you'll also learn to fix real-world problems and you will +improve your skills, and other developers will be aware of your presence. +Fixing bugs is one of the best ways to get merits among other developers, +because not many people like wasting time fixing other people's bugs. +To work on already reported bug reports, find a subsystem you are interested in. +Check the MAINTAINERS file where bugs for that subsystem get reported to; often +it will be a mailing list, rarely a bugtracker. Search the archives of said +place for recent reports and help where you see fit. You may also want to check +https://bugzilla.kernel.org for bug reports; only a handful of kernel subsystems +use it actively for reporting or tracking, nevertheless bugs for the whole +kernel get filed there. Mailing lists @@ -398,12 +373,12 @@ As some of the above documents describe, the majority of the core kernel developers participate on the Linux Kernel Mailing list. Details on how to subscribe and unsubscribe from the list can be found at: - http://vger.kernel.org/vger-lists.html#linux-kernel + https://subspace.kernel.org/subscribing.html There are archives of the mailing list on the web in many different places. Use a search engine to find these archives. For example: - http://dir.gmane.org/gmane.linux.kernel + https://lore.kernel.org/linux-kernel/ It is highly recommended that you search the archives about the topic you want to bring up, before you post it to the list. A lot of things @@ -418,13 +393,13 @@ groups. Many of the lists are hosted on kernel.org. Information on them can be found at: - http://vger.kernel.org/vger-lists.html + https://subspace.kernel.org Please remember to follow good behavioral habits when using the lists. Though a bit cheesy, the following URL has some simple guidelines for interacting with the list (or any list): - http://www.albion.com/netiquette/ + https://subspace.kernel.org/etiquette.html If multiple people respond to your mail, the CC: list of recipients may get pretty large. Don't remove anybody from the CC: list without a good @@ -438,7 +413,7 @@ add your statements between the individual quoted sections instead of writing at the top of the mail. If you add patches to your mail, make sure they are plain readable text -as stated in Documentation/process/submitting-patches.rst. +as stated in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`. Kernel developers don't want to deal with attachments or compressed patches; they may want to comment on individual lines of your patch, which works only that way. Make sure you @@ -620,7 +595,7 @@ For more details on what this should all look like, please see the ChangeLog section of the document: "The Perfect Patch" - http://www.ozlabs.org/~akpm/stuff/tpp.txt + https://www.ozlabs.org/~akpm/stuff/tpp.txt All of these things are sometimes very hard to do. It can take years to |