Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > linux.kernel > #1486354 > unrolled thread
| Started by | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| First post | 2016-09-19 13:10 +0200 |
| Last post | 2016-09-21 11:30 +0200 |
| Articles | 20 on this page of 32 — 3 participants |
Back to article view | Back to linux.kernel
[PATCH v4 00/29] Create a book for Kernel development Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
[PATCH v4 09/29] Documentation/Changes: add minimal requirements for documentation build Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
[PATCH v4 01/29] doc-rst: add CSS styles for :kbd: and :menuselection: Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
[PATCH v4 08/29] Documentation/Changes: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
[PATCH v4 03/29] doc: development-process: rename files to rst Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
[PATCH v4 04/29] docs-rst: create a book for the development process Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
[PATCH v4 05/29] Documentation/HOWTO: convert to ReST notation Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
[PATCH v4 06/29] Documentation/applying-patches.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:10 +0200
[PATCH v4 28/29] Documentation/email-clients.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 25/29] Documentation/HOWTO: adjust external link references Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 11/29] Documentation/CodingStyle: use the proper tag for verbatim font Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 14/29] Documentation/ManagementStyle: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 17/29] Documentation/stable_kernel_rules.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
Re: [PATCH v4 17/29] Documentation/stable_kernel_rules.txt: convert it to ReST markup Greg KH <greg@kroah.com> - 2016-09-20 09:10 +0200
[PATCH v4 12/29] Documentation/CodingStyle: replace underline markups Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 27/29] Documentation/SubmitChecklist: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 02/29] doc: development-process: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 16/29] Documentation/stable_api_nonsense.txt: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 20/29] Documentation/SubmittingPatches: enrich the Sphinx output Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 07/29] Documentation/applying-patches.txt: Update the information there Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 10/29] Documentation/CodingStyle: Convert to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 24/29] Documentation/HOWTO: improve some markups to make it visually better Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 13/29] Documentation/CodingStyle: use the .. note:: markup where needed Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 23/29] Documentation/HOWTO: update information about generating documentation Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 22/29] Documentation/HOWTO: add cross-references to other documents Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
Re: [PATCH v4 22/29] Documentation/HOWTO: add cross-references to other documents Greg KH <greg@kroah.com> - 2016-09-20 09:10 +0200
[PATCH v4 26/29] Documentation/SubmitChecklist: update kernel-doc task Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 15/29] Documentation/SecurityBugs: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 19/29] Documentation/SubmittingPatches: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
[PATCH v4 18/29] Documentation/SubmittingDrivers: convert it to ReST markup Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-19 13:20 +0200
Re: [PATCH v4 00/29] Create a book for Kernel development Jonathan Corbet <corbet@lwn.net> - 2016-09-21 02:50 +0200
Re: [PATCH v4 00/29] Create a book for Kernel development Mauro Carvalho Chehab <mchehab@s-opensource.com> - 2016-09-21 11:30 +0200
Page 1 of 2 [1] 2 Next page →
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:10 +0200 |
| Subject | [PATCH v4 00/29] Create a book for Kernel development |
| Message-ID | <sj4Ct-4H9-1@gated-at.bofh.it> |
That's the 4th version of this series. It also contains a second patch series
with more ReST conversions and documentation improvements.
This patchset merges the content of a second patch series:
[PATCH 00/17] Improve documentation for the development-process
I opted to keep the patch changing the kernel-docs.txt changes
(patch 21/29). The patch is already written and another patch
(patch 22/29) depends on it, because there are references to
this file at Documentation/HOWTO.
It shouldn't be hard to get rid of it, but I'm not sure if worths
the effort. As I commented, people might find useful to update
it to point to more modern documents. If people won't do it,
it can still be removed from the Kernel a the next Kernel version.
Yet, if you prefer, feel free to drop patch 21/29 and replace
by a patch removing kernel-docs.txt, adding my ack.
I also folded all renaming stuff to a single patch (29/29).
Jon,
Please don't merge patch 29/29 as-is, as it requires more discussion.
I opted to not rename development-process there, nor to split it into
per-subsystem changes, as we need to first agree about the approach to
be taken. I opted to keep this at the series to allow people to test the
book generation, on both pdf and html formats.
IMHO, patches 1 to 28 should be OK to merge, as they don't do any
renames. We need to discuss more about patch 29, until we solve
this question:
"Should we rename those well-known documents?"
If the answer is "no":
- should we use symlinks instead?
- can't Sphinx be tricked to build them with their existing names?
If the answer is "yes":
- shoud we create files to replace CheckPatch/SubmitPatches/SubmitDrivers
that would point to the newer location?
Also, as you pointed, some of those files (like SecurityBugs) may fit better
on a "users manual" book.
For such book, we'll likely want to group most of the information at
the /README file, and add other stuff there too, like:
Documentation/kernel-parameters.txt
(perhaps splitting its content per-subystem?)
Also, as SecurityBooks is mentioned at HOWTO, if we put it on a separate
book, we'll need to enable interSphinx extension, in order to generate
cross-references between different documents. This is needed for the PDF
output.
Also, "development-process" is a very big name for a dir. We should likely
shorten it to just "process" or "devel". (and "Documentation/" is another
big name too). Those two big names makes several cross-references to
be bigger than the 80-cols limit, like:
:ref:`Documentation/development-process/SubmittingDrivers.rst <submittingdrivers>`
--
There are several documents related to Kernel development, where the
HOWTO works like an index to several such documents. There are also
a series of files describing the development process.
This patch series:
1) converts the Documentation/development-process/ to ReST
and creates a Sphinx book, prepared to support sub-books;
2) Converts several files under Documentation to ReST markup;
3) Move the converted files to development-process/ directory, adding
a .rst extension to them, adjusting cross-references and adding them
to the development-process book.
NOTE: HOWTO also mentions the /README document on it. While IMHO it
makes sense to convert it to ReST, moving it out of the main directory
didn't sound a good idea. So, I'm leaving this one untouched.
PS.: I decided to do such conversion because I received yet another
email from one developer wanted to submit drivers, but not being
aware of the right proceures. As usual, I pointed him to the Kernel
sources, but there are a way too much documentation there with a mix of
procedures and API docs inside.
It would be a way easier to point to a single URL where the submission
procedures would be altoghether. Hopefully, this will have a lot of time
in the future. My evil plan is to put this doc somewhere at LinuxTV and
have a standard e-mail prepared for such next requests :-D
The produced output, in HTML, is at:
https://mchehab.fedorapeople.org/development-process/
The LaTeX version at:
https://mchehab.fedorapeople.org/development-process/latex/development-process.tex
And the PDF version at:
https://mchehab.fedorapeople.org/development-process/latex/development-process.pdf
--
Version 4 changes:
- Keep chapter numeration on the Documentation/* files (CodingStyle
& friends);
- Use :: on the same line, to improve document reading in plain text;
- Added the contents of a separate patch series:
[PATCH 00/17] Improve documentation for the development-process
Several patches from such series were folded on the ReST conversion
patches.
Ok, this makes this one big, but it helped to keep some sanity, as
all renames could be folded into a single patch at the end of this
series.
Version 3 changes:
- Almost all changes here are just a patch set reordering to do first the
ReST conversion and then renames. Hopefully, Jon will be happier with
such approach ;)
- Fixed some issues pointed by Joe Pershes at the CodingStyle conversion;
- Better explain the rationale for using ``foo`` instead of "foo" at
CodingStyle.
Jani suggested to take the opportunity to standardize file name between
DocumentFoo, document-foo and document_foo. I opted to not do it
on this series, as we need first to agree on the convension. Once we have
some agreement, it should be easy to adjust the files to the agreed
nomenclature.
Version 2 changes:
- On version 1, I forgot to c/c LKML. Since v2, I'm c/c it, to give it a
broader audience.
- Per Jonathan Corbet's suggestion, this version is placing all documents at
the already existing developing-process/ directory, instead of creating a
new dir;
- Also per Jon's suggestion, it also converts the development-process files
to rst.
- Replaced all occurrences of the renamed files at the Kernel Documentation
dir;
- Added conf.py and the need logic to produce both LaTeX and PDF output;
Mauro Carvalho Chehab (29):
doc-rst: add CSS styles for :kbd: and :menuselection:
doc: development-process: convert it to ReST markup
doc: development-process: rename files to rst
docs-rst: create a book for the development process
Documentation/HOWTO: convert to ReST notation
Documentation/applying-patches.txt: convert it to ReST markup
Documentation/applying-patches.txt: Update the information there
Documentation/Changes: convert it to ReST markup
Documentation/Changes: add minimal requirements for documentation
build
Documentation/CodingStyle: Convert to ReST markup
Documentation/CodingStyle: use the proper tag for verbatim font
Documentation/CodingStyle: replace underline markups
Documentation/CodingStyle: use the .. note:: markup where needed
Documentation/ManagementStyle: convert it to ReST markup
Documentation/SecurityBugs: convert it to ReST markup
Documentation/stable_api_nonsense.txt: convert it to ReST markup
Documentation/stable_kernel_rules.txt: convert it to ReST markup
Documentation/SubmittingDrivers: convert it to ReST markup
Documentation/SubmittingPatches: convert it to ReST markup
Documentation/SubmittingPatches: enrich the Sphinx output
Documentation/kernel-docs.txt: convert it to ReST markup
Documentation/HOWTO: add cross-references to other documents
Documentation/HOWTO: update information about generating documentation
Documentation/HOWTO: improve some markups to make it visually better
Documentation/HOWTO: adjust external link references
Documentation/SubmitChecklist: update kernel-doc task
Documentation/SubmitChecklist: convert it to ReST markup
Documentation/email-clients.txt: convert it to ReST markup
docs-rst: move HOWTO and mentioned documents to development-process/
Documentation/ABI/README | 2 +-
Documentation/BUG-HUNTING | 2 +-
Documentation/DocBook/kernel-hacking.tmpl | 4 +-
Documentation/SubmitChecklist | 109 ---
Documentation/adding-syscalls.txt | 2 +-
Documentation/conf.py | 2 +
.../development-process/{1.Intro => 1.Intro.rst} | 68 +-
.../{2.Process => 2.Process.rst} | 41 +-
.../{3.Early-stage => 3.Early-stage.rst} | 22 +-
.../development-process/{4.Coding => 4.Coding.rst} | 48 +-
.../{5.Posting => 5.Posting.rst} | 32 +-
.../{6.Followthrough => 6.Followthrough.rst} | 14 +-
.../{7.AdvancedTopics => 7.AdvancedTopics.rst} | 13 +-
.../{8.Conclusion => 8.Conclusion.rst} | 8 +-
.../{Changes => development-process/Changes.rst} | 262 ++++---
.../CodingStyle.rst} | 387 ++++++----
.../{HOWTO => development-process/HOWTO.rst} | 156 ++--
.../ManagementStyle.rst} | 154 ++--
.../SecurityBugs.rst} | 8 +
.../development-process/SubmitChecklist.rst | 120 ++++
.../SubmittingDrivers.rst} | 56 +-
.../SubmittingPatches.rst} | 314 ++++----
.../applying-patches.rst} | 427 ++++++-----
Documentation/development-process/conf.py | 10 +
.../development-process/development-process.rst | 29 +
.../email-clients.rst} | 216 +++---
Documentation/development-process/index.rst | 29 +
Documentation/development-process/kernel-docs.rst | 791 +++++++++++++++++++++
.../stable_api_nonsense.rst} | 37 +-
.../stable_kernel_rules.rst} | 110 ++-
.../devicetree/bindings/submitting-patches.txt | 2 +-
Documentation/filesystems/locks.txt | 2 +-
Documentation/hwmon/submitting-patches | 8 +-
Documentation/index.rst | 1 +
Documentation/isdn/README | 2 +-
Documentation/ja_JP/HOWTO | 28 +-
Documentation/ja_JP/SubmitChecklist | 6 +-
Documentation/ja_JP/SubmittingPatches | 18 +-
Documentation/ja_JP/stable_api_nonsense.txt | 4 +-
Documentation/ja_JP/stable_kernel_rules.txt | 6 +-
Documentation/kernel-docs.txt | 731 -------------------
Documentation/kernel-documentation.rst | 2 +
Documentation/ko_KR/HOWTO | 28 +-
Documentation/ko_KR/stable_api_nonsense.txt | 4 +-
Documentation/networking/PLIP.txt | 2 +-
Documentation/networking/netdev-FAQ.txt | 8 +-
Documentation/scsi/scsi_mid_low_api.txt | 2 +-
Documentation/sphinx-static/theme_overrides.css | 15 +-
Documentation/virtual/kvm/review-checklist.txt | 4 +-
.../watchdog/convert_drivers_to_kernel_api.txt | 2 +-
Documentation/zh_CN/CodingStyle | 4 +-
Documentation/zh_CN/HOWTO | 28 +-
Documentation/zh_CN/SecurityBugs | 4 +-
Documentation/zh_CN/SubmittingDrivers | 8 +-
Documentation/zh_CN/SubmittingPatches | 12 +-
Documentation/zh_CN/email-clients.txt | 4 +-
Documentation/zh_CN/stable_api_nonsense.txt | 4 +-
Documentation/zh_CN/stable_kernel_rules.txt | 6 +-
MAINTAINERS | 2 +-
README | 4 +-
REPORTING-BUGS | 2 +-
drivers/net/ppp/Kconfig | 2 +-
drivers/pcmcia/Kconfig | 2 +-
fs/Kconfig.binfmt | 2 +-
fs/fuse/Kconfig | 2 +-
net/Kconfig | 4 +-
scripts/ver_linux | 2 +-
tools/testing/selftests/futex/README | 2 +-
68 files changed, 2544 insertions(+), 1898 deletions(-)
delete mode 100644 Documentation/SubmitChecklist
rename Documentation/development-process/{1.Intro => 1.Intro.rst} (87%)
rename Documentation/development-process/{2.Process => 2.Process.rst} (96%)
rename Documentation/development-process/{3.Early-stage => 3.Early-stage.rst} (97%)
rename Documentation/development-process/{4.Coding => 4.Coding.rst} (97%)
rename Documentation/development-process/{5.Posting => 5.Posting.rst} (96%)
rename Documentation/development-process/{6.Followthrough => 6.Followthrough.rst} (98%)
rename Documentation/development-process/{7.AdvancedTopics => 7.AdvancedTopics.rst} (98%)
rename Documentation/development-process/{8.Conclusion => 8.Conclusion.rst} (96%)
rename Documentation/{Changes => development-process/Changes.rst} (51%)
rename Documentation/{CodingStyle => development-process/CodingStyle.rst} (78%)
rename Documentation/{HOWTO => development-process/HOWTO.rst} (88%)
rename Documentation/{ManagementStyle => development-process/ManagementStyle.rst} (75%)
rename Documentation/{SecurityBugs => development-process/SecurityBugs.rst} (94%)
create mode 100644 Documentation/development-process/SubmitChecklist.rst
rename Documentation/{SubmittingDrivers => development-process/SubmittingDrivers.rst} (82%)
rename Documentation/{SubmittingPatches => development-process/SubmittingPatches.rst} (78%)
rename Documentation/{applying-patches.txt => development-process/applying-patches.rst} (52%)
create mode 100644 Documentation/development-process/conf.py
create mode 100644 Documentation/development-process/development-process.rst
rename Documentation/{email-clients.txt => development-process/email-clients.rst} (56%)
create mode 100644 Documentation/development-process/index.rst
create mode 100644 Documentation/development-process/kernel-docs.rst
rename Documentation/{stable_api_nonsense.txt => development-process/stable_api_nonsense.rst} (91%)
rename Documentation/{stable_kernel_rules.txt => development-process/stable_kernel_rules.rst} (64%)
delete mode 100644 Documentation/kernel-docs.txt
--
2.7.4
[toc] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:10 +0200 |
| Subject | [PATCH v4 09/29] Documentation/Changes: add minimal requirements for documentation build |
| Message-ID | <sj4Cu-4H9-3@gated-at.bofh.it> |
| In reply to | #1486354 |
As discussed at linux-doc ML, the best is to keep all documents backward compatible with Sphinx version 1.2, as it is the latest version found on some distros like Debian. All books currently support it. Please notice that, while it mentions the eventual need of XeLaTex and texlive to build pdf files, this is not a minimal requirement, as one could just be interested on building html documents. Also, identifying the minimal requirements for texlive packages is not trivial, as each distribution seems to use different criteria on grouping LaTex functionalities. While here, update the current kernel version to 4.x. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/Changes | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/Documentation/Changes b/Documentation/Changes index a9f365d864c7..93c8e1c15844 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -5,7 +5,7 @@ Intro ===== This document is designed to provide a list of the minimum levels of -software necessary to run the 3.0 kernels. +software necessary to run the 4.x kernels. This document is originally based on my "Changes" file for 2.0.x kernels and therefore owes credit to the same people as that file (Jared Mauch, @@ -51,8 +51,10 @@ mcelog 0.6 mcelog --version iptables 1.4.2 iptables -V openssl & libcrypto 1.0.0 openssl version bc 1.06.95 bc --version +Sphinx\ [#f1]_ 1.2 sphinx-build --version ====================== =============== ======================================== +.. [#f1] Sphinx is needed only to build the Kernel documentation Kernel compilation ****************** @@ -307,6 +309,30 @@ On x86 kernels the mcelog utility is needed to process and log machine check events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors reported by the CPU. Processing them is strongly encouraged. +Kernel documentation +******************** + +Sphinx +------ + +The ReST markups currently used by the Documentation/ files are meant to be +built with ``Sphinx`` version 1.2 or upper. If you're desiring to build +PDF outputs, it is recommended to use version 1.4.6. + +.. note:: + + Please notice that, for PDF and LaTeX output, you'll also need ``XeLaTeX`` + version 3.14159265. Depending on the distribution, you may also need + to install a series of ``texlive`` packages that provide the minimal + set of functionalities required for ``XeLaTex`` to work. + +Other tools +----------- + +In order to produce documentation from DocBook, you'll also need ``xmlto``. +Please notice, however, that we're currently migrating all documents to use +``Sphinx``. + Getting updated software ======================== @@ -453,3 +479,11 @@ NFS-Utils --------- - <http://nfs.sourceforge.net/> + +Kernel documentation +******************** + +Sphinx +------ + +- <http://www.sphinx-doc.org/> -- 2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:10 +0200 |
| Subject | [PATCH v4 01/29] doc-rst: add CSS styles for :kbd: and :menuselection: |
| Message-ID | <sj4Cu-4H9-9@gated-at.bofh.it> |
| In reply to | #1486354 |
As we're about to use those two markups, add them to the
theme style overrride.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/sphinx-static/theme_overrides.css | 15 ++++++++++++++-
1 file changed, 14 insertions(+), 1 deletion(-)
diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css
index e88461c4c1e6..d5764a4de5a2 100644
--- a/Documentation/sphinx-static/theme_overrides.css
+++ b/Documentation/sphinx-static/theme_overrides.css
@@ -42,6 +42,20 @@
caption a.headerlink { opacity: 0; }
caption a.headerlink:hover { opacity: 1; }
+ /* Menu selection and keystrokes */
+
+ span.menuselection {
+ color: blue;
+ font-family: "Courier New", Courier, monospace
+ }
+
+ code.kbd, code.kbd span {
+ color: white;
+ background-color: darkblue;
+ font-weight: bold;
+ font-family: "Courier New", Courier, monospace
+ }
+
/* inline literal: drop the borderbox, padding and red color */
code, .rst-content tt, .rst-content code {
@@ -55,5 +69,4 @@
.rst-content tt.literal,.rst-content tt.literal,.rst-content code.literal {
color: inherit;
}
-
}
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:10 +0200 |
| Subject | [PATCH v4 08/29] Documentation/Changes: convert it to ReST markup |
| Message-ID | <sj4Cu-4H9-13@gated-at.bofh.it> |
| In reply to | #1486354 |
- Fix chapter identation inconsistencies; - Convert table to ReST format; - use the right tag for bullets; - Fix bold emphasis; - mark blocks with :: tags; - use verbatim font for files; - make Sphinx happy Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/Changes | 224 ++++++++++++++++++++++++++++++-------------------- 1 file changed, 134 insertions(+), 90 deletions(-) diff --git a/Documentation/Changes b/Documentation/Changes index ec97b77c8b00..a9f365d864c7 100644 --- a/Documentation/Changes +++ b/Documentation/Changes @@ -1,3 +1,6 @@ +Minimal requerements to compile the Kernel +++++++++++++++++++++++++++++++++++++++++++ + Intro ===== @@ -10,9 +13,9 @@ Axel Boldt, Alessandro Sigala, and countless other users all over the 'net). Current Minimal Requirements -============================ +**************************** -Upgrade to at *least* these software revisions before thinking you've +Upgrade to at **least** these software revisions before thinking you've encountered a bug! If you're unsure what version you're currently running, the suggested command should tell you. @@ -21,34 +24,38 @@ running a Linux kernel. Also, not all tools are necessary on all systems; obviously, if you don't have any ISDN hardware, for example, you probably needn't concern yourself with isdn4k-utils. -o GNU C 3.2 # gcc --version -o GNU make 3.80 # make --version -o binutils 2.12 # ld -v -o util-linux 2.10o # fdformat --version -o module-init-tools 0.9.10 # depmod -V -o e2fsprogs 1.41.4 # e2fsck -V -o jfsutils 1.1.3 # fsck.jfs -V -o reiserfsprogs 3.6.3 # reiserfsck -V -o xfsprogs 2.6.0 # xfs_db -V -o squashfs-tools 4.0 # mksquashfs -version -o btrfs-progs 0.18 # btrfsck -o pcmciautils 004 # pccardctl -V -o quota-tools 3.09 # quota -V -o PPP 2.4.0 # pppd --version -o isdn4k-utils 3.1pre1 # isdnctrl 2>&1|grep version -o nfs-utils 1.0.5 # showmount --version -o procps 3.2.0 # ps --version -o oprofile 0.9 # oprofiled --version -o udev 081 # udevd --version -o grub 0.93 # grub --version || grub-install --version -o mcelog 0.6 # mcelog --version -o iptables 1.4.2 # iptables -V -o openssl & libcrypto 1.0.0 # openssl version -o bc 1.06.95 # bc --version +====================== =============== ======================================== + Program Minimal version Command to check the version +====================== =============== ======================================== +GNU C 3.2 gcc --version +GNU make 3.80 make --version +binutils 2.12 ld -v +util-linux 2.10o fdformat --version +module-init-tools 0.9.10 depmod -V +e2fsprogs 1.41.4 e2fsck -V +jfsutils 1.1.3 fsck.jfs -V +reiserfsprogs 3.6.3 reiserfsck -V +xfsprogs 2.6.0 xfs_db -V +squashfs-tools 4.0 mksquashfs -version +btrfs-progs 0.18 btrfsck +pcmciautils 004 pccardctl -V +quota-tools 3.09 quota -V +PPP 2.4.0 pppd --version +isdn4k-utils 3.1pre1 isdnctrl 2>&1|grep version +nfs-utils 1.0.5 showmount --version +procps 3.2.0 ps --version +oprofile 0.9 oprofiled --version +udev 081 udevd --version +grub 0.93 grub --version || grub-install --version +mcelog 0.6 mcelog --version +iptables 1.4.2 iptables -V +openssl & libcrypto 1.0.0 openssl version +bc 1.06.95 bc --version +====================== =============== ======================================== Kernel compilation -================== +****************** GCC --- @@ -64,16 +71,16 @@ You will need GNU make 3.80 or later to build the kernel. Binutils -------- -Linux on IA-32 has recently switched from using as86 to using gas for -assembling the 16-bit boot code, removing the need for as86 to compile +Linux on IA-32 has recently switched from using ``as86`` to using ``gas`` for +assembling the 16-bit boot code, removing the need for ``as86`` to compile your kernel. This change does, however, mean that you need a recent release of binutils. Perl ---- -You will need perl 5 and the following modules: Getopt::Long, Getopt::Std, -File::Basename, and File::Find to build the kernel. +You will need perl 5 and the following modules: ``Getopt::Long``, +``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel. BC -- @@ -93,7 +100,7 @@ and higher. System utilities -================ +**************** Architectural changes --------------------- @@ -115,7 +122,7 @@ well as the desired DocBook stylesheets. Util-linux ---------- -New versions of util-linux provide *fdisk support for larger disks, +New versions of util-linux provide ``fdisk`` support for larger disks, support new options to mount, recognize more supported partition types, have a fdformat which works with 2.4 kernels, and similar goodies. You'll probably want to upgrade. @@ -125,54 +132,57 @@ Ksymoops If the unthinkable happens and your kernel oopses, you may need the ksymoops tool to decode it, but in most cases you don't. -It is generally preferred to build the kernel with CONFIG_KALLSYMS so +It is generally preferred to build the kernel with ``CONFIG_KALLSYMS`` so that it produces readable dumps that can be used as-is (this also produces better output than ksymoops). If for some reason your kernel -is not build with CONFIG_KALLSYMS and you have no way to rebuild and +is not build with ``CONFIG_KALLSYMS`` and you have no way to rebuild and reproduce the Oops with that option, then you can still decode that Oops with ksymoops. Module-Init-Tools ----------------- -A new module loader is now in the kernel that requires module-init-tools +A new module loader is now in the kernel that requires ``module-init-tools`` to use. It is backward compatible with the 2.4.x series kernels. Mkinitrd -------- -These changes to the /lib/modules file tree layout also require that +These changes to the ``/lib/modules`` file tree layout also require that mkinitrd be upgraded. E2fsprogs --------- -The latest version of e2fsprogs fixes several bugs in fsck and +The latest version of ``e2fsprogs`` fixes several bugs in fsck and debugfs. Obviously, it's a good idea to upgrade. JFSutils -------- -The jfsutils package contains the utilities for the file system. +The ``jfsutils`` package contains the utilities for the file system. The following utilities are available: -o fsck.jfs - initiate replay of the transaction log, and check + +- ``fsck.jfs`` - initiate replay of the transaction log, and check and repair a JFS formatted partition. -o mkfs.jfs - create a JFS formatted partition. -o other file system utilities are also available in this package. + +- ``mkfs.jfs`` - create a JFS formatted partition. + +- other file system utilities are also available in this package. Reiserfsprogs ------------- The reiserfsprogs package should be used for reiserfs-3.6.x (Linux kernels 2.4.x). It is a combined package and contains working -versions of mkreiserfs, resize_reiserfs, debugreiserfs and -reiserfsck. These utils work on both i386 and alpha platforms. +versions of ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` and +``reiserfsck``. These utils work on both i386 and alpha platforms. Xfsprogs -------- -The latest version of xfsprogs contains mkfs.xfs, xfs_db, and the -xfs_repair utilities, among others, for the XFS filesystem. It is +The latest version of ``xfsprogs`` contains ``mkfs.xfs``, ``xfs_db``, and the +``xfs_repair`` utilities, among others, for the XFS filesystem. It is architecture independent and any version from 2.0.0 onward should work correctly with this version of the XFS kernel code (2.6.0 or later is recommended, due to some significant improvements). @@ -180,7 +190,7 @@ later is recommended, due to some significant improvements). PCMCIAutils ----------- -PCMCIAutils replaces pcmcia-cs. It properly sets up +PCMCIAutils replaces ``pcmcia-cs``. It properly sets up PCMCIA sockets at system startup and loads the appropriate modules for 16-bit PCMCIA devices if the kernel is modularized and the hotplug subsystem is used. @@ -200,17 +210,20 @@ A driver has been added to allow updating of Intel IA32 microcode, accessible as a normal (misc) character device. If you are not using udev you may need to: -mkdir /dev/cpu -mknod /dev/cpu/microcode c 10 184 -chmod 0644 /dev/cpu/microcode +:: + + mkdir /dev/cpu + mknod /dev/cpu/microcode c 10 184 + chmod 0644 /dev/cpu/microcode as root before you can use this. You'll probably also want to get the user-space microcode_ctl utility to use with this. udev ---- -udev is a userspace application for populating /dev dynamically with -only entries for devices actually present. udev replaces the basic + +``udev`` is a userspace application for populating ``/dev`` dynamically with +only entries for devices actually present. ``udev`` replaces the basic functionality of devfs, while allowing persistent device naming for devices. @@ -218,10 +231,10 @@ FUSE ---- Needs libfuse 2.4.0 or later. Absolute minimum is 2.3.0 but mount -options 'direct_io' and 'kernel_cache' won't work. +options ``direct_io`` and ``kernel_cache`` won't work. Networking -========== +********** General changes --------------- @@ -245,7 +258,9 @@ upgrade pppd to at least 2.4.0. If you are not using udev, you must have the device file /dev/ppp which can be made by: -mknod /dev/ppp c 108 0 +:: + + mknod /dev/ppp c 108 0 as root. @@ -260,23 +275,25 @@ NFS-utils In ancient (2.4 and earlier) kernels, the nfs server needed to know about any client that expected to be able to access files via NFS. This -information would be given to the kernel by "mountd" when the client -mounted the filesystem, or by "exportfs" at system startup. exportfs -would take information about active clients from /var/lib/nfs/rmtab. +information would be given to the kernel by ``mountd`` when the client +mounted the filesystem, or by ``exportfs`` at system startup. exportfs +would take information about active clients from ``/var/lib/nfs/rmtab``. This approach is quite fragile as it depends on rmtab being correct which is not always easy, particularly when trying to implement -fail-over. Even when the system is working well, rmtab suffers from +fail-over. Even when the system is working well, ``rmtab`` suffers from getting lots of old entries that never get removed. With modern kernels we have the option of having the kernel tell mountd when it gets a request from an unknown host, and mountd can give appropriate export information to the kernel. This removes the -dependency on rmtab and means that the kernel only needs to know about +dependency on ``rmtab`` and means that the kernel only needs to know about currently active clients. To enable this new functionality, you need to: +:: + mount -t nfsd nfsd /proc/fs/nfsd before running exportfs or mountd. It is recommended that all NFS @@ -287,8 +304,8 @@ mcelog ------ On x86 kernels the mcelog utility is needed to process and log machine check -events when CONFIG_X86_MCE is enabled. Machine check events are errors reported -by the CPU. Processing them is strongly encouraged. +events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors +reported by the CPU. Processing them is strongly encouraged. Getting updated software ======================== @@ -298,114 +315,141 @@ Kernel compilation gcc --- -o <ftp://ftp.gnu.org/gnu/gcc/> + +- <ftp://ftp.gnu.org/gnu/gcc/> Make ---- -o <ftp://ftp.gnu.org/gnu/make/> + +- <ftp://ftp.gnu.org/gnu/make/> Binutils -------- -o <ftp://ftp.kernel.org/pub/linux/devel/binutils/> + +- <ftp://ftp.kernel.org/pub/linux/devel/binutils/> OpenSSL ------- -o <https://www.openssl.org/> + +- <https://www.openssl.org/> System utilities **************** Util-linux ---------- -o <ftp://ftp.kernel.org/pub/linux/utils/util-linux/> + +- <ftp://ftp.kernel.org/pub/linux/utils/util-linux/> Ksymoops -------- -o <ftp://ftp.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/> + +- <ftp://ftp.kernel.org/pub/linux/utils/kernel/ksymoops/v2.4/> Module-Init-Tools ----------------- -o <ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/modules/> + +- <ftp://ftp.kernel.org/pub/linux/kernel/people/rusty/modules/> Mkinitrd -------- -o <https://code.launchpad.net/initrd-tools/main> + +- <https://code.launchpad.net/initrd-tools/main> E2fsprogs --------- -o <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz> + +- <http://prdownloads.sourceforge.net/e2fsprogs/e2fsprogs-1.29.tar.gz> JFSutils -------- -o <http://jfs.sourceforge.net/> + +- <http://jfs.sourceforge.net/> Reiserfsprogs ------------- -o <http://www.kernel.org/pub/linux/utils/fs/reiserfs/> + +- <http://www.kernel.org/pub/linux/utils/fs/reiserfs/> Xfsprogs -------- -o <ftp://oss.sgi.com/projects/xfs/> + +- <ftp://oss.sgi.com/projects/xfs/> Pcmciautils ----------- -o <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/> + +- <ftp://ftp.kernel.org/pub/linux/utils/kernel/pcmcia/> Quota-tools ----------- -o <http://sourceforge.net/projects/linuxquota/> +----------- + +- <http://sourceforge.net/projects/linuxquota/> DocBook Stylesheets ------------------- -o <http://sourceforge.net/projects/docbook/files/docbook-dsssl/> + +- <http://sourceforge.net/projects/docbook/files/docbook-dsssl/> XMLTO XSLT Frontend ------------------- -o <http://cyberelk.net/tim/xmlto/> + +- <http://cyberelk.net/tim/xmlto/> Intel P6 microcode ------------------ -o <https://downloadcenter.intel.com/> + +- <https://downloadcenter.intel.com/> udev ---- -o <http://www.freedesktop.org/software/systemd/man/udev.html> + +- <http://www.freedesktop.org/software/systemd/man/udev.html> FUSE ---- -o <http://sourceforge.net/projects/fuse> + +- <http://sourceforge.net/projects/fuse> mcelog ------ -o <http://www.mcelog.org/> + +- <http://www.mcelog.org/> Networking ********** PPP --- -o <ftp://ftp.samba.org/pub/ppp/> + +- <ftp://ftp.samba.org/pub/ppp/> Isdn4k-utils ------------ -o <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/> + +- <ftp://ftp.isdn4linux.de/pub/isdn4linux/utils/> NFS-utils --------- -o <http://sourceforge.net/project/showfiles.php?group_id=14> + +- <http://sourceforge.net/project/showfiles.php?group_id=14> Iptables -------- -o <http://www.iptables.org/downloads.html> + +- <http://www.iptables.org/downloads.html> Ip-route2 --------- -o <https://www.kernel.org/pub/linux/utils/net/iproute2/> + +- <https://www.kernel.org/pub/linux/utils/net/iproute2/> OProfile -------- -o <http://oprofile.sf.net/download/> + +- <http://oprofile.sf.net/download/> NFS-Utils --------- -o <http://nfs.sourceforge.net/> + +- <http://nfs.sourceforge.net/> -- 2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:10 +0200 |
| Subject | [PATCH v4 03/29] doc: development-process: rename files to rst |
| Message-ID | <sj4Cu-4H9-19@gated-at.bofh.it> |
| In reply to | #1486354 |
Now that the documents were converted, rename them to .rst, as
this is needed by the Sphinx build logic.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/development-process/{1.Intro => 1.Intro.rst} | 0
Documentation/development-process/{2.Process => 2.Process.rst} | 0
Documentation/development-process/{3.Early-stage => 3.Early-stage.rst} | 0
Documentation/development-process/{4.Coding => 4.Coding.rst} | 0
Documentation/development-process/{5.Posting => 5.Posting.rst} | 0
.../development-process/{6.Followthrough => 6.Followthrough.rst} | 0
.../development-process/{7.AdvancedTopics => 7.AdvancedTopics.rst} | 0
Documentation/development-process/{8.Conclusion => 8.Conclusion.rst} | 0
8 files changed, 0 insertions(+), 0 deletions(-)
rename Documentation/development-process/{1.Intro => 1.Intro.rst} (100%)
rename Documentation/development-process/{2.Process => 2.Process.rst} (100%)
rename Documentation/development-process/{3.Early-stage => 3.Early-stage.rst} (100%)
rename Documentation/development-process/{4.Coding => 4.Coding.rst} (100%)
rename Documentation/development-process/{5.Posting => 5.Posting.rst} (100%)
rename Documentation/development-process/{6.Followthrough => 6.Followthrough.rst} (100%)
rename Documentation/development-process/{7.AdvancedTopics => 7.AdvancedTopics.rst} (100%)
rename Documentation/development-process/{8.Conclusion => 8.Conclusion.rst} (100%)
diff --git a/Documentation/development-process/1.Intro b/Documentation/development-process/1.Intro.rst
similarity index 100%
rename from Documentation/development-process/1.Intro
rename to Documentation/development-process/1.Intro.rst
diff --git a/Documentation/development-process/2.Process b/Documentation/development-process/2.Process.rst
similarity index 100%
rename from Documentation/development-process/2.Process
rename to Documentation/development-process/2.Process.rst
diff --git a/Documentation/development-process/3.Early-stage b/Documentation/development-process/3.Early-stage.rst
similarity index 100%
rename from Documentation/development-process/3.Early-stage
rename to Documentation/development-process/3.Early-stage.rst
diff --git a/Documentation/development-process/4.Coding b/Documentation/development-process/4.Coding.rst
similarity index 100%
rename from Documentation/development-process/4.Coding
rename to Documentation/development-process/4.Coding.rst
diff --git a/Documentation/development-process/5.Posting b/Documentation/development-process/5.Posting.rst
similarity index 100%
rename from Documentation/development-process/5.Posting
rename to Documentation/development-process/5.Posting.rst
diff --git a/Documentation/development-process/6.Followthrough b/Documentation/development-process/6.Followthrough.rst
similarity index 100%
rename from Documentation/development-process/6.Followthrough
rename to Documentation/development-process/6.Followthrough.rst
diff --git a/Documentation/development-process/7.AdvancedTopics b/Documentation/development-process/7.AdvancedTopics.rst
similarity index 100%
rename from Documentation/development-process/7.AdvancedTopics
rename to Documentation/development-process/7.AdvancedTopics.rst
diff --git a/Documentation/development-process/8.Conclusion b/Documentation/development-process/8.Conclusion.rst
similarity index 100%
rename from Documentation/development-process/8.Conclusion
rename to Documentation/development-process/8.Conclusion.rst
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:10 +0200 |
| Subject | [PATCH v4 04/29] docs-rst: create a book for the development process |
| Message-ID | <sj4Cu-4H9-11@gated-at.bofh.it> |
| In reply to | #1486354 |
Now that the files at Documentation/development-process/
were converted to ReST, make create a book at Sphinx.
As we'll have other books related to the development process,
we'll add it as a sub-book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/conf.py | 2 ++
Documentation/development-process/conf.py | 10 ++++++++++
Documentation/development-process/index.rst | 9 +++++++++
Documentation/index.rst | 1 +
4 files changed, 22 insertions(+)
create mode 100644 Documentation/development-process/conf.py
create mode 100644 Documentation/development-process/index.rst
diff --git a/Documentation/conf.py b/Documentation/conf.py
index c25e95d46272..bf6f310e5170 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -338,6 +338,8 @@ latex_elements = {
latex_documents = [
('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation',
'The kernel development community', 'manual'),
+ ('development-process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
+ 'The kernel development community', 'manual'),
('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide',
'The kernel development community', 'manual'),
('media/index', 'media.tex', 'Linux Media Subsystem Documentation',
diff --git a/Documentation/development-process/conf.py b/Documentation/development-process/conf.py
new file mode 100644
index 000000000000..4b4a12dace02
--- /dev/null
+++ b/Documentation/development-process/conf.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = 'Linux Kernel Development Documentation'
+
+tags.add("subproject")
+
+latex_documents = [
+ ('index', 'development-process.tex', 'Linux Kernel Development Documentation',
+ 'The kernel development community', 'manual'),
+]
diff --git a/Documentation/development-process/index.rst b/Documentation/development-process/index.rst
new file mode 100644
index 000000000000..c37475d91090
--- /dev/null
+++ b/Documentation/development-process/index.rst
@@ -0,0 +1,9 @@
+Linux Kernel Development Documentation
+======================================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ development-process
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 05eded59820e..c6cf3971788d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -12,6 +12,7 @@ Contents:
:maxdepth: 2
kernel-documentation
+ development-process/index
dev-tools/tools
media/index
gpu/index
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:10 +0200 |
| Subject | [PATCH v4 05/29] Documentation/HOWTO: convert to ReST notation |
| Message-ID | <sj4Cu-4H9-27@gated-at.bofh.it> |
| In reply to | #1486354 |
This document is almost compliant with ReST notation, but some
small adjustments are needed to make it parse properly by
Sphinx (mostly, add blank lines where needed).
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/HOWTO | 53 +++++++++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 49 insertions(+), 4 deletions(-)
diff --git a/Documentation/HOWTO b/Documentation/HOWTO
index 1f345da28ec5..5a85e3a8112b 100644
--- a/Documentation/HOWTO
+++ b/Documentation/HOWTO
@@ -1,5 +1,5 @@
HOWTO do Linux kernel development
----------------------------------
+=================================
This is the be-all, end-all document on this topic. It contains
instructions on how to become a Linux kernel developer and how to learn
@@ -28,6 +28,7 @@ kernel development. Assembly (any architecture) is not required unless
you plan to do low-level development for that architecture. Though they
are not a good substitute for a solid C education and/or years of
experience, the following books are good for, if anything, reference:
+
- "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
- "Practical C Programming" by Steve Oualline [O'Reilly]
- "C: A Reference Manual" by Harbison and Steele [Prentice Hall]
@@ -64,6 +65,7 @@ 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:
+
http://www.gnu.org/licenses/gpl-faq.html
@@ -82,6 +84,7 @@ linux-api@vger.kernel.org.
Here is a list of files that are in the kernel source tree that are
required reading:
+
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
@@ -99,30 +102,37 @@ required reading:
patches if these rules are followed, and many people will only
review code if it is in the proper style.
- Documentation/SubmittingPatches
- Documentation/SubmittingDrivers
+ Documentation/SubmittingPatches and Documentation/SubmittingDrivers
These files describe in explicit detail how to successfully create
and send a patch, including (but not limited to):
+
- Email contents
- Email format
- Who to send it to
+
Following these rules will not guarantee success (as all patches are
subject to scrutiny for content and style), but not following them
will almost always prevent it.
Other excellent descriptions of how to create patches properly are:
+
"The Perfect Patch"
+
http://www.ozlabs.org/~akpm/stuff/tpp.txt
+
"Linux kernel patch submission format"
+
http://linux.yyz.us/patch-format.html
Documentation/stable_api_nonsense.txt
This file describes the rationale behind the conscious decision to
not have a stable API within the kernel, including things like:
+
- Subsystem shim-layers (for compatibility?)
- Driver portability between Operating Systems.
- Mitigating rapid change within the kernel source tree (or
preventing rapid change)
+
This document is crucial for understanding the Linux development
philosophy and is very important for people moving to Linux from
development on other Operating Systems.
@@ -159,10 +169,14 @@ full description of the in-kernel API, and rules on how to handle
locking properly. The documents will be created in the
Documentation/DocBook/ directory and can be generated as PDF,
Postscript, HTML, and man pages by running:
+
+::
+
make pdfdocs
make psdocs
make htmldocs
make mandocs
+
respectively from the main kernel source directory.
@@ -171,7 +185,9 @@ Becoming A Kernel Developer
If you do not know anything about Linux kernel development, you should
look at the Linux KernelNewbies project:
+
http://kernelnewbies.org
+
It consists of a helpful mailing list where you can ask almost any type
of basic kernel development question (make sure to search the archives
first, before asking something that has already been answered in the
@@ -187,7 +203,9 @@ apply a patch.
If you do not know where you want to start, but you want to look for
some task to start doing to join into the kernel development community,
go to the Linux Kernel Janitor's project:
+
http://kernelnewbies.org/KernelJanitors
+
It is a great place to start. It describes a list of relatively simple
problems that need to be cleaned up and fixed within the Linux kernel
source tree. Working with the developers in charge of this project, you
@@ -199,6 +217,7 @@ 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:
+
http://selenic.com/mailman/listinfo/kernel-mentors
Before making any actual modifications to the Linux kernel code, it is
@@ -209,6 +228,7 @@ tools. One such tool that is particularly recommended is the Linux
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/
@@ -218,6 +238,7 @@ The development process
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
@@ -229,6 +250,7 @@ branches. These different branches are:
4.x kernels are maintained by Linus Torvalds, and can be found on
kernel.org in the pub/linux/kernel/v4.x/ directory. Its development
process is as follows:
+
- As soon as a new kernel is released a two weeks 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
@@ -253,6 +275,9 @@ process is as follows:
It is worth mentioning what Andrew Morton wrote on the linux-kernel
mailing list about kernel releases:
+
+::
+
"Nobody knows when a kernel will be released, because it's
released according to perceived bug status, not according to a
preconceived timeline."
@@ -318,6 +343,7 @@ Before updates from subsystem trees are merged into the mainline 4.x
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:
+
http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
This way, the -next kernel gives a summary outlook onto what will be
@@ -331,6 +357,7 @@ Bug Reporting
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:
+
http://bugzilla.kernel.org/page.cgi?id=faq.html
The file REPORTING-BUGS in the main kernel source directory has a good
@@ -365,10 +392,14 @@ Mailing lists
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
+
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
+
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
already discussed in detail are only recorded at the mailing list
@@ -381,11 +412,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
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/
If multiple people respond to your mail, the CC: list of recipients may
@@ -418,6 +451,7 @@ The goal of the kernel community is to provide the best possible kernel
there is. When you submit a patch for acceptance, it will be reviewed
on its technical merits and those alone. So, what should you be
expecting?
+
- criticism
- comments
- requests for change
@@ -432,6 +466,7 @@ If there are no responses to your posting, wait a few days and try
again, sometimes things get lost in the huge volume.
What should you not do?
+
- expect your patch to be accepted without question
- become defensive
- ignore comments
@@ -457,7 +492,9 @@ Differences between the kernel community and corporate structures
The kernel community works differently than most traditional corporate
development environments. Here are a list of things that you can try to
do to avoid problems:
+
Good things to say regarding your proposed changes:
+
- "This solves multiple problems."
- "This deletes 2000 lines of code."
- "Here is a patch that explains what I am trying to describe."
@@ -466,6 +503,7 @@ do to avoid problems:
- "This increases performance on typical machines..."
Bad things you should avoid saying:
+
- "We did it this way in AIX/ptx/Solaris, so therefore it must be
good..."
- "I've being doing this for 20 years, so..."
@@ -527,12 +565,15 @@ The reasons for breaking things up are the following:
and simplify (or simply re-order) patches before submitting them.
Here is an analogy from kernel developer Al Viro:
+
+::
+
"Think of a teacher grading homework from a math student. The
teacher does not want to see the student's trials and errors
before they came up with the solution. They want to see the
cleanest, most elegant answer. A good student knows this, and
would never submit her intermediate work before the final
- solution."
+ solution.
The same is true of kernel development. The maintainers and
reviewers do not want to see the thought process behind the
@@ -565,6 +606,7 @@ When sending in your patches, pay special attention to what you say in
the text in your email. This information will become the ChangeLog
information for the patch, and will be preserved for everyone to see for
all time. It should describe the patch completely, containing:
+
- why the change is necessary
- the overall design approach in the patch
- implementation details
@@ -572,7 +614,9 @@ all time. It should describe the patch completely, containing:
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
@@ -588,6 +632,7 @@ start exactly where you are now.
----------
+
Thanks to Paolo Ciarrocchi who allowed the "Development Process"
(http://lwn.net/Articles/94386/) section
to be based on text he had written, and to Randy Dunlap and Gerrit
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:10 +0200 |
| Subject | [PATCH v4 06/29] Documentation/applying-patches.txt: convert it to ReST markup |
| Message-ID | <sj4Cu-4H9-21@gated-at.bofh.it> |
| In reply to | #1486354 |
- use the correct markup to identify each section; - Add some blank lines for Sphinx to properly interpret the markups; - Remove a blank space on some paragraphs; - Fix the verbatim and bold markups; - Cleanup the remaining errors to make Sphinx happy. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/applying-patches.txt | 311 ++++++++++++++++++++++--------------- 1 file changed, 189 insertions(+), 122 deletions(-) diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt index 77df55b0225a..573eb3bee19e 100644 --- a/Documentation/applying-patches.txt +++ b/Documentation/applying-patches.txt @@ -1,9 +1,12 @@ - Applying Patches To The Linux Kernel - ------------------------------------ +Applying Patches To The Linux Kernel +++++++++++++++++++++++++++++++++++++ - Original by: Jesper Juhl, August 2005 - Last update: 2006-01-05 +Original by: + Jesper Juhl, August 2005 + +Last update: + 2006-01-05 A frequently asked question on the Linux Kernel Mailing List is how to apply @@ -17,10 +20,12 @@ their specific patches) is also provided. What is a patch? ---- - A patch is a small text document containing a delta of changes between two -different versions of a source tree. Patches are created with the `diff' +================ + +A patch is a small text document containing a delta of changes between two +different versions of a source tree. Patches are created with the ``diff`` program. + To correctly apply a patch you need to know what base it was generated from and what new version the patch will change the source tree into. These should both be present in the patch file metadata or be possible to deduce @@ -28,8 +33,9 @@ from the filename. How do I apply or revert a patch? ---- - You apply a patch with the `patch' program. The patch program reads a diff +================================= + +You apply a patch with the ``patch`` program. The patch program reads a diff (or patch) file and makes the changes to the source tree described in it. Patches for the Linux kernel are generated relative to the parent directory @@ -38,26 +44,39 @@ holding the kernel source dir. This means that paths to files inside the patch file contain the name of the kernel source directories it was generated against (or some other directory names like "a/" and "b/"). + Since this is unlikely to match the name of the kernel source dir on your local machine (but is often useful info to see what version an otherwise unlabeled patch was generated against) you should change into your kernel source directory and then strip the first element of the path from filenames -in the patch file when applying it (the -p1 argument to `patch' does this). +in the patch file when applying it (the ``-p1`` argument to ``patch`` does +this). To revert a previously applied patch, use the -R argument to patch. So, if you applied a patch like this: + +:: + patch -p1 < ../patch-x.y.z You can revert (undo) it like this: + +:: + patch -R -p1 < ../patch-x.y.z -How do I feed a patch/diff file to `patch'? ---- - This (as usual with Linux and other UNIX like operating systems) can be +How do I feed a patch/diff file to ``patch``? +============================================= + +This (as usual with Linux and other UNIX like operating systems) can be done in several different ways. + In all the examples below I feed the file (in uncompressed form) to patch via stdin using the following syntax: + +:: + patch -p1 < path/to/patch-x.y.z If you just want to be able to follow the examples below and don't want to @@ -66,34 +85,45 @@ section here. Patch can also get the name of the file to use via the -i argument, like this: + +:: + patch -p1 -i path/to/patch-x.y.z If your patch file is compressed with gzip or bzip2 and you don't want to uncompress it before applying it, then you can feed it to patch like this instead: + +:: + zcat path/to/patch-x.y.z.gz | patch -p1 bzcat path/to/patch-x.y.z.bz2 | patch -p1 If you wish to uncompress the patch file by hand first before applying it (what I assume you've done in the examples below), then you simply run gunzip or bunzip2 on the file -- like this: + +:: + gunzip patch-x.y.z.gz bunzip2 patch-x.y.z.bz2 Which will leave you with a plain text patch-x.y.z file that you can feed to -patch via stdin or the -i argument, as you prefer. +patch via stdin or the ``-i`` argument, as you prefer. -A few other nice arguments for patch are -s which causes patch to be silent +A few other nice arguments for patch are ``-s`` which causes patch to be silent except for errors which is nice to prevent errors from scrolling out of the -screen too fast, and --dry-run which causes patch to just print a listing of -what would happen, but doesn't actually make any changes. Finally --verbose +screen too fast, and ``--dry-run`` which causes patch to just print a listing of +what would happen, but doesn't actually make any changes. Finally ``--verbose`` tells patch to print more information about the work being done. Common errors when patching ---- - When patch applies a patch file it attempts to verify the sanity of the +=========================== + +When patch applies a patch file it attempts to verify the sanity of the file in different ways. + Checking that the file looks like a valid patch file and checking the code around the bits being modified matches the context provided in the patch are just two of the basic sanity checks patch does. @@ -111,13 +141,13 @@ everything looks good it has just moved up or down a bit, and patch will usually adjust the line numbers and apply the patch. Whenever patch applies a patch that it had to modify a bit to make it fit -it'll tell you about it by saying the patch applied with 'fuzz'. +it'll tell you about it by saying the patch applied with **fuzz**. You should be wary of such changes since even though patch probably got it right it doesn't /always/ get it right, and the result will sometimes be wrong. When patch encounters a change that it can't fix up with fuzz it rejects it -outright and leaves a file with a .rej extension (a reject file). You can +outright and leaves a file with a ``.rej`` extension (a reject file). You can read this file to see exactly what change couldn't be applied, so you can go fix it up by hand if you wish. @@ -132,43 +162,47 @@ to start with a fresh tree downloaded in full from kernel.org. Let's look a bit more at some of the messages patch can produce. -If patch stops and presents a "File to patch:" prompt, then patch could not +If patch stops and presents a ``File to patch:`` prompt, then patch could not find a file to be patched. Most likely you forgot to specify -p1 or you are in the wrong directory. Less often, you'll find patches that need to be -applied with -p0 instead of -p1 (reading the patch file should reveal if +applied with ``-p0`` instead of ``-p1`` (reading the patch file should reveal if this is the case -- if so, then this is an error by the person who created the patch but is not fatal). -If you get "Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines)." or a +If you get ``Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines).`` or a message similar to that, then it means that patch had to adjust the location of the change (in this example it needed to move 7 lines from where it expected to make the change to make it fit). + The resulting file may or may not be OK, depending on the reason the file was different than expected. + This often happens if you try to apply a patch that was generated against a different kernel version than the one you are trying to patch. -If you get a message like "Hunk #3 FAILED at 2387.", then it means that the +If you get a message like ``Hunk #3 FAILED at 2387.``, then it means that the patch could not be applied correctly and the patch program was unable to -fuzz its way through. This will generate a .rej file with the change that -caused the patch to fail and also a .orig file showing you the original +fuzz its way through. This will generate a ``.rej`` file with the change that +caused the patch to fail and also a ``.orig`` file showing you the original content that couldn't be changed. -If you get "Reversed (or previously applied) patch detected! Assume -R? [n]" +If you get ``Reversed (or previously applied) patch detected! Assume -R? [n]`` then patch detected that the change contained in the patch seems to have already been made. + If you actually did apply this patch previously and you just re-applied it in error, then just say [n]o and abort this patch. If you applied this patch previously and actually intended to revert it, but forgot to specify -R, -then you can say [y]es here to make patch revert it for you. +then you can say [**y**]es here to make patch revert it for you. + This can also happen if the creator of the patch reversed the source and destination directories when creating the patch, and in that case reverting the patch will in fact apply it. -A message similar to "patch: **** unexpected end of file in patch" or "patch -unexpectedly ends in middle of line" means that patch could make no sense of -the file you fed to it. Either your download is broken, you tried to feed -patch a compressed patch file without uncompressing it first, or the patch +A message similar to ``patch: **** unexpected end of file in patch`` or +``patch unexpectedly ends in middle of line`` means that patch could make no +sense of the file you fed to it. Either your download is broken, you tried to +feed patch a compressed patch file without uncompressing it first, or the patch file that you are using has been mangled by a mail client or mail transfer agent along the way somewhere, e.g., by splitting a long line into two lines. Often these warnings can easily be fixed by joining (concatenating) the @@ -182,28 +216,34 @@ to start over with a fresh download of a full kernel tree and the patch you wish to apply. -Are there any alternatives to `patch'? ---- - Yes there are alternatives. +Are there any alternatives to ``patch``? +======================================== - You can use the `interdiff' program (http://cyberelk.net/tim/patchutils/) to + +Yes there are alternatives. + +You can use the ``interdiff`` program (http://cyberelk.net/tim/patchutils/) to generate a patch representing the differences between two patches and then apply the result. + This will let you move from something like 2.6.12.2 to 2.6.12.3 in a single step. The -z flag to interdiff will even let you feed it patches in gzip or bzip2 compressed form directly without the use of zcat or bzcat or manual decompression. Here's how you'd go from 2.6.12.2 to 2.6.12.3 in a single step: + +:: + interdiff -z ../patch-2.6.12.2.bz2 ../patch-2.6.12.3.gz | patch -p1 Although interdiff may save you a step or two you are generally advised to do the additional steps since interdiff can get things wrong in some cases. - Another alternative is `ketchup', which is a python script for automatic +Another alternative is ``ketchup``, which is a python script for automatic downloading and applying of patches (http://www.selenic.com/ketchup/). - Other nice tools are diffstat, which shows a summary of changes made by a +Other nice tools are diffstat, which shows a summary of changes made by a patch; lsdiff, which displays a short listing of affected files in a patch file, along with (optionally) the line numbers of the start of each patch; and grepdiff, which displays a list of the files modified by a patch where @@ -211,24 +251,29 @@ the patch contains a given regular expression. Where can I download the patches? ---- - The patches are available at http://kernel.org/ +================================= + +The patches are available at http://kernel.org/ Most recent patches are linked from the front page, but they also have specific homes. The 2.6.x.y (-stable) and 2.6.x patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/ + + ftp://ftp.kernel.org/pub/linux/kernel/v2.6/ The -rc patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/testing/ + + ftp://ftp.kernel.org/pub/linux/kernel/v2.6/testing/ The -git patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/ + + ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/ The -mm kernels live at - ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/ -In place of ftp.kernel.org you can use ftp.cc.kernel.org, where cc is a + ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/ + +In place of ``ftp.kernel.org`` you can use ``ftp.cc.kernel.org``, where cc is a country code. This way you'll be downloading from a mirror site that's most likely geographically closer to you, resulting in faster downloads for you, less bandwidth used globally and less load on the main kernel.org servers -- @@ -236,8 +281,9 @@ these are good things, so do use mirrors when possible. The 2.6.x kernels ---- - These are the base stable releases released by Linus. The highest numbered +================= + +These are the base stable releases released by Linus. The highest numbered release is the most recent. If regressions or other serious flaws are found, then a -stable fix patch @@ -246,30 +292,33 @@ kernel is released, a patch is made available that is a delta between the previous 2.6.x kernel and the new one. To apply a patch moving from 2.6.11 to 2.6.12, you'd do the following (note -that such patches do *NOT* apply on top of 2.6.x.y kernels but on top of the +that such patches do **NOT** apply on top of 2.6.x.y kernels but on top of the base 2.6.x kernel -- if you need to move from 2.6.x.y to 2.6.x+1 you need to first revert the 2.6.x.y patch). Here are some examples: -# moving from 2.6.11 to 2.6.12 -$ cd ~/linux-2.6.11 # change to kernel source dir -$ patch -p1 < ../patch-2.6.12 # apply the 2.6.12 patch -$ cd .. -$ mv linux-2.6.11 linux-2.6.12 # rename source dir +:: -# moving from 2.6.11.1 to 2.6.12 -$ cd ~/linux-2.6.11.1 # change to kernel source dir -$ patch -p1 -R < ../patch-2.6.11.1 # revert the 2.6.11.1 patch - # source dir is now 2.6.11 -$ patch -p1 < ../patch-2.6.12 # apply new 2.6.12 patch -$ cd .. -$ mv linux-2.6.11.1 linux-2.6.12 # rename source dir + # moving from 2.6.11 to 2.6.12 + $ cd ~/linux-2.6.11 # change to kernel source dir + $ patch -p1 < ../patch-2.6.12 # apply the 2.6.12 patch + $ cd .. + $ mv linux-2.6.11 linux-2.6.12 # rename source dir + + # moving from 2.6.11.1 to 2.6.12 + $ cd ~/linux-2.6.11.1 # change to kernel source dir + $ patch -p1 -R < ../patch-2.6.11.1 # revert the 2.6.11.1 patch + # source dir is now 2.6.11 + $ patch -p1 < ../patch-2.6.12 # apply new 2.6.12 patch + $ cd .. + $ mv linux-2.6.11.1 linux-2.6.12 # rename source dir The 2.6.x.y kernels ---- - Kernels with 4-digit versions are -stable kernels. They contain small(ish) +=================== + +Kernels with 4-digit versions are -stable kernels. They contain small(ish) critical fixes for security problems or significant regressions discovered in a given 2.6.x kernel. @@ -280,30 +329,35 @@ versions. If no 2.6.x.y kernel is available, then the highest numbered 2.6.x kernel is the current stable kernel. - note: the -stable team usually do make incremental patches available as well +.. note:: + + The -stable team usually do make incremental patches available as well as patches against the latest mainline release, but I only cover the non-incremental ones below. The incremental ones can be found at ftp://ftp.kernel.org/pub/linux/kernel/v2.6/incr/ These patches are not incremental, meaning that for example the 2.6.12.3 patch does not apply on top of the 2.6.12.2 kernel source, but rather on top -of the base 2.6.12 kernel source . +of the base 2.6.12 kernel source. + So, in order to apply the 2.6.12.3 patch to your existing 2.6.12.2 kernel source you have to first back out the 2.6.12.2 patch (so you are left with a base 2.6.12 kernel source) and then apply the new 2.6.12.3 patch. Here's a small example: -$ cd ~/linux-2.6.12.2 # change into the kernel source dir -$ patch -p1 -R < ../patch-2.6.12.2 # revert the 2.6.12.2 patch -$ patch -p1 < ../patch-2.6.12.3 # apply the new 2.6.12.3 patch -$ cd .. -$ mv linux-2.6.12.2 linux-2.6.12.3 # rename the kernel source dir +:: + $ cd ~/linux-2.6.12.2 # change to the kernel source dir + $ patch -p1 -R < ../patch-2.6.12.2 # revert the 2.6.12.2 patch + $ patch -p1 < ../patch-2.6.12.3 # apply the new 2.6.12.3 patch + $ cd .. + $ mv linux-2.6.12.2 linux-2.6.12.3 # rename the kernel source dir The -rc kernels ---- - These are release-candidate kernels. These are development kernels released +=============== + +These are release-candidate kernels. These are development kernels released by Linus whenever he deems the current git (the kernel's source management tool) tree to be in a reasonably sane state adequate for testing. @@ -321,35 +375,39 @@ The -rc patches are not incremental, they apply to a base 2.6.x kernel, just like the 2.6.x.y patches described above. The kernel version before the -rcN suffix denotes the version of the kernel that this -rc kernel will eventually turn into. + So, 2.6.13-rc5 means that this is the fifth release candidate for the 2.6.13 kernel and the patch should be applied on top of the 2.6.12 kernel source. Here are 3 examples of how to apply these patches: -# first an example of moving from 2.6.12 to 2.6.13-rc3 -$ cd ~/linux-2.6.12 # change into the 2.6.12 source dir -$ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch -$ cd .. -$ mv linux-2.6.12 linux-2.6.13-rc3 # rename the source dir +:: -# now let's move from 2.6.13-rc3 to 2.6.13-rc5 -$ cd ~/linux-2.6.13-rc3 # change into the 2.6.13-rc3 dir -$ patch -p1 -R < ../patch-2.6.13-rc3 # revert the 2.6.13-rc3 patch -$ patch -p1 < ../patch-2.6.13-rc5 # apply the new 2.6.13-rc5 patch -$ cd .. -$ mv linux-2.6.13-rc3 linux-2.6.13-rc5 # rename the source dir + # first an example of moving from 2.6.12 to 2.6.13-rc3 + $ cd ~/linux-2.6.12 # change to the 2.6.12 source dir + $ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch + $ cd .. + $ mv linux-2.6.12 linux-2.6.13-rc3 # rename the source dir -# finally let's try and move from 2.6.12.3 to 2.6.13-rc5 -$ cd ~/linux-2.6.12.3 # change to the kernel source dir -$ patch -p1 -R < ../patch-2.6.12.3 # revert the 2.6.12.3 patch -$ patch -p1 < ../patch-2.6.13-rc5 # apply new 2.6.13-rc5 patch -$ cd .. -$ mv linux-2.6.12.3 linux-2.6.13-rc5 # rename the kernel source dir + # now let's move from 2.6.13-rc3 to 2.6.13-rc5 + $ cd ~/linux-2.6.13-rc3 # change to the 2.6.13-rc3 dir + $ patch -p1 -R < ../patch-2.6.13-rc3 # revert the 2.6.13-rc3 patch + $ patch -p1 < ../patch-2.6.13-rc5 # apply the new 2.6.13-rc5 patch + $ cd .. + $ mv linux-2.6.13-rc3 linux-2.6.13-rc5 # rename the source dir + + # finally let's try and move from 2.6.12.3 to 2.6.13-rc5 + $ cd ~/linux-2.6.12.3 # change to the kernel source dir + $ patch -p1 -R < ../patch-2.6.12.3 # revert the 2.6.12.3 patch + $ patch -p1 < ../patch-2.6.13-rc5 # apply new 2.6.13-rc5 patch + $ cd .. + $ mv linux-2.6.12.3 linux-2.6.13-rc5 # rename the kernel source dir The -git kernels ---- - These are daily snapshots of Linus' kernel tree (managed in a git +================ + +These are daily snapshots of Linus' kernel tree (managed in a git repository, hence the name). These patches are usually released daily and represent the current state of @@ -364,35 +422,40 @@ named 2.6.13-rc3-git2 applies to the source of the 2.6.13-rc3 kernel. Here are some examples of how to apply these patches: -# moving from 2.6.12 to 2.6.12-git1 -$ cd ~/linux-2.6.12 # change to the kernel source dir -$ patch -p1 < ../patch-2.6.12-git1 # apply the 2.6.12-git1 patch -$ cd .. -$ mv linux-2.6.12 linux-2.6.12-git1 # rename the kernel source dir +:: -# moving from 2.6.12-git1 to 2.6.13-rc2-git3 -$ cd ~/linux-2.6.12-git1 # change to the kernel source dir -$ patch -p1 -R < ../patch-2.6.12-git1 # revert the 2.6.12-git1 patch - # we now have a 2.6.12 kernel -$ patch -p1 < ../patch-2.6.13-rc2 # apply the 2.6.13-rc2 patch - # the kernel is now 2.6.13-rc2 -$ patch -p1 < ../patch-2.6.13-rc2-git3 # apply the 2.6.13-rc2-git3 patch - # the kernel is now 2.6.13-rc2-git3 -$ cd .. -$ mv linux-2.6.12-git1 linux-2.6.13-rc2-git3 # rename source dir + # moving from 2.6.12 to 2.6.12-git1 + $ cd ~/linux-2.6.12 # change to the kernel source dir + $ patch -p1 < ../patch-2.6.12-git1 # apply the 2.6.12-git1 patch + $ cd .. + $ mv linux-2.6.12 linux-2.6.12-git1 # rename the kernel source dir + + # moving from 2.6.12-git1 to 2.6.13-rc2-git3 + $ cd ~/linux-2.6.12-git1 # change to the kernel source dir + $ patch -p1 -R < ../patch-2.6.12-git1 # revert the 2.6.12-git1 patch + # we now have a 2.6.12 kernel + $ patch -p1 < ../patch-2.6.13-rc2 # apply the 2.6.13-rc2 patch + # the kernel is now 2.6.13-rc2 + $ patch -p1 < ../patch-2.6.13-rc2-git3 # apply the 2.6.13-rc2-git3 patch + # the kernel is now 2.6.13-rc2-git3 + $ cd .. + $ mv linux-2.6.12-git1 linux-2.6.13-rc2-git3 # rename source dir The -mm kernels ---- - These are experimental kernels released by Andrew Morton. +=============== + +These are experimental kernels released by Andrew Morton. The -mm tree serves as a sort of proving ground for new features and other experimental patches. + Once a patch has proved its worth in -mm for a while Andrew pushes it on to Linus for inclusion in mainline. Although it's encouraged that patches flow to Linus via the -mm tree, this is not always enforced. + Subsystem maintainers (or individuals) sometimes push their patches directly to Linus, even though (or after) they have been merged and tested in -mm (or sometimes even without prior testing in -mm). @@ -417,31 +480,35 @@ Testing of -mm kernels is greatly appreciated since the whole point of the tree is to weed out regressions, crashes, data corruption bugs, build breakage (and any other bug in general) before changes are merged into the more stable mainline Linus tree. + But testers of -mm should be aware that breakage in this tree is more common than in any other tree. The -mm kernels are not released on a fixed schedule, but usually a few -mm kernels are released in between each -rc kernel (1 to 3 is common). + The -mm kernels apply to either a base 2.6.x kernel (when no -rc kernels have been released yet) or to a Linus -rc kernel. Here are some examples of applying the -mm patches: -# moving from 2.6.12 to 2.6.12-mm1 -$ cd ~/linux-2.6.12 # change to the 2.6.12 source dir -$ patch -p1 < ../2.6.12-mm1 # apply the 2.6.12-mm1 patch -$ cd .. -$ mv linux-2.6.12 linux-2.6.12-mm1 # rename the source appropriately +:: -# moving from 2.6.12-mm1 to 2.6.13-rc3-mm3 -$ cd ~/linux-2.6.12-mm1 -$ patch -p1 -R < ../2.6.12-mm1 # revert the 2.6.12-mm1 patch - # we now have a 2.6.12 source -$ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch - # we now have a 2.6.13-rc3 source -$ patch -p1 < ../2.6.13-rc3-mm3 # apply the 2.6.13-rc3-mm3 patch -$ cd .. -$ mv linux-2.6.12-mm1 linux-2.6.13-rc3-mm3 # rename the source dir + # moving from 2.6.12 to 2.6.12-mm1 + $ cd ~/linux-2.6.12 # change to the 2.6.12 source dir + $ patch -p1 < ../2.6.12-mm1 # apply the 2.6.12-mm1 patch + $ cd .. + $ mv linux-2.6.12 linux-2.6.12-mm1 # rename the source appropriately + + # moving from 2.6.12-mm1 to 2.6.13-rc3-mm3 + $ cd ~/linux-2.6.12-mm1 + $ patch -p1 -R < ../2.6.12-mm1 # revert the 2.6.12-mm1 patch + # we now have a 2.6.12 source + $ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch + # we now have a 2.6.13-rc3 source + $ patch -p1 < ../2.6.13-rc3-mm3 # apply the 2.6.13-rc3-mm3 patch + $ cd .. + $ mv linux-2.6.12-mm1 linux-2.6.13-rc3-mm3 # rename the source dir This concludes this list of explanations of the various kernel trees. -- 2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 28/29] Documentation/email-clients.txt: convert it to ReST markup |
| Message-ID | <sj4M9-4KI-5@gated-at.bofh.it> |
| In reply to | #1486354 |
As this file is mentioned at the development-process/ book,
let's convert it to ReST markup.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/SubmittingPatches | 2 +-
Documentation/development-process/5.Posting.rst | 2 +-
Documentation/email-clients.txt | 214 ++++++++++++++----------
Documentation/ja_JP/SubmittingPatches | 2 +-
Documentation/zh_CN/email-clients.txt | 4 +-
5 files changed, 127 insertions(+), 97 deletions(-)
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 9c3dfa7babf3..801f5cd5103b 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -358,7 +358,7 @@ decreasing the likelihood of your MIME-attached change being accepted.
Exception: If your mailer is mangling patches then someone may ask
you to re-send them using MIME.
-See Documentation/email-clients.txt for hints about configuring
+See Documentation/development-process/email-clients.rst for hints about configuring
your e-mail client so that it sends your patches untouched.
7) E-mail size
diff --git a/Documentation/development-process/5.Posting.rst b/Documentation/development-process/5.Posting.rst
index b511ddf7e82a..945d40200538 100644
--- a/Documentation/development-process/5.Posting.rst
+++ b/Documentation/development-process/5.Posting.rst
@@ -248,7 +248,7 @@ take care of:
be examined in any detail. If there is any doubt at all, mail the patch
to yourself and convince yourself that it shows up intact.
- Documentation/email-clients.txt has some helpful hints on making
+ Documentation/development-process/email-clients.rst has some helpful hints on making
specific mail clients work for sending patches.
- Are you sure your patch is free of silly mistakes? You should always
diff --git a/Documentation/email-clients.txt b/Documentation/email-clients.txt
index 2d485dea8cec..0deb240bee56 100644
--- a/Documentation/email-clients.txt
+++ b/Documentation/email-clients.txt
@@ -1,23 +1,25 @@
Email clients info for Linux
-======================================================================
+============================
Git
-----------------------------------------------------------------------
-These days most developers use `git send-email` instead of regular
+---
+
+These days most developers use ``git send-email`` instead of regular
email clients. The man page for this is quite good. On the receiving
-end, maintainers use `git am` to apply the patches.
+end, maintainers use ``git am`` to apply the patches.
-If you are new to git then send your first patch to yourself. Save it
-as raw text including all the headers. Run `git am raw_email.txt` and
-then review the changelog with `git log`. When that works then send
+If you are new to ``git`` then send your first patch to yourself. Save it
+as raw text including all the headers. Run ``git am raw_email.txt`` and
+then review the changelog with ``git log``. When that works then send
the patch to the appropriate mailing list(s).
General Preferences
-----------------------------------------------------------------------
+-------------------
+
Patches for the Linux kernel are submitted via email, preferably as
inline text in the body of the email. Some maintainers accept
attachments, but then the attachments should have content-type
-"text/plain". However, attachments are generally frowned upon because
+``text/plain``. However, attachments are generally frowned upon because
it makes quoting portions of the patch more difficult in the patch
review process.
@@ -25,7 +27,7 @@ Email clients that are used for Linux kernel patches should send the
patch text untouched. For example, they should not modify or delete tabs
or spaces, even at the beginning or end of lines.
-Don't send patches with "format=flowed". This can cause unexpected
+Don't send patches with ``format=flowed``. This can cause unexpected
and unwanted line breaks.
Don't let your email client do automatic word wrapping for you.
@@ -54,57 +56,63 @@ mailing lists.
Some email client (MUA) hints
-----------------------------------------------------------------------
+-----------------------------
+
Here are some specific MUA configuration hints for editing and sending
patches for the Linux kernel. These are not meant to be complete
software package configuration summaries.
+
Legend:
-TUI = text-based user interface
-GUI = graphical user interface
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- TUI = text-based user interface
+- GUI = graphical user interface
+
Alpine (TUI)
+************
Config options:
-In the "Sending Preferences" section:
-- "Do Not Send Flowed Text" must be enabled
-- "Strip Whitespace Before Sending" must be disabled
+In the :menuselection:`Sending Preferences` section:
+
+- :menuselection:`Do Not Send Flowed Text` must be ``enabled``
+- :menuselection:`Strip Whitespace Before Sending` must be ``disabled``
When composing the message, the cursor should be placed where the patch
-should appear, and then pressing CTRL-R let you specify the patch file
+should appear, and then pressing :kbd:`CTRL-R` let you specify the patch file
to insert into the message.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Claws Mail (GUI)
+****************
Works. Some people use this successfully for patches.
-To insert a patch use Message->Insert File (CTRL+i) or an external editor.
+To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`)
+or an external editor.
If the inserted patch has to be edited in the Claws composition window
-"Auto wrapping" in Configuration->Preferences->Compose->Wrapping should be
+"Auto wrapping" in
+:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` should be
disabled.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Evolution (GUI)
+***************
Some people use this successfully for patches.
When composing mail select: Preformat
- from Format->Paragraph Style->Preformatted (Ctrl-7)
+ from :menuselection:`Format-->Paragraph Style-->Preformatted` (:kbd:`CTRL-7`)
or the toolbar
Then use:
- Insert->Text File... (Alt-n x)
+:menuselection:`Insert-->Text File...` (:kbd:`ALT-N x`)
to insert the patch.
-You can also "diff -Nru old.c new.c | xclip", select Preformat, then
-paste with the middle button.
+You can also ``diff -Nru old.c new.c | xclip``, select
+:menuselection:`Preformat`, then paste with the middle button.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Kmail (GUI)
+***********
Some people use Kmail successfully for patches.
@@ -120,11 +128,12 @@ word-wrapped and you can uncheck "word wrap" without losing the existing
wrapping.
At the bottom of your email, put the commonly-used patch delimiter before
-inserting your patch: three hyphens (---).
+inserting your patch: three hyphens (``---``).
-Then from the "Message" menu item, select insert file and choose your patch.
+Then from the :menuselection:`Message` menu item, select insert file and
+choose your patch.
As an added bonus you can customise the message creation toolbar menu
-and put the "insert file" icon there.
+and put the :menuselection:`insert file` icon there.
Make the composer window wide enough so that no lines wrap. As of
KMail 1.13.5 (KDE 4.5.4), KMail will apply word wrapping when sending
@@ -139,86 +148,108 @@ as inlined text will make them tricky to extract from their 7-bit encoding.
If you absolutely must send patches as attachments instead of inlining
them as text, right click on the attachment and select properties, and
-highlight "Suggest automatic display" to make the attachment inlined to
-make it more viewable.
+highlight :menuselection:`Suggest automatic display` to make the attachment
+inlined to make it more viewable.
When saving patches that are sent as inlined text, select the email that
contains the patch from the message list pane, right click and select
-"save as". You can use the whole email unmodified as a patch if it was
-properly composed. There is no option currently to save the email when you
-are actually viewing it in its own window -- there has been a request filed
-at kmail's bugzilla and hopefully this will be addressed. Emails are saved
-as read-write for user only so you will have to chmod them to make them
+:menuselection:`save as`. You can use the whole email unmodified as a patch
+if it was properly composed. There is no option currently to save the email
+when you are actually viewing it in its own window -- there has been a request
+filed at kmail's bugzilla and hopefully this will be addressed. Emails are
+saved as read-write for user only so you will have to chmod them to make them
group and world readable if you copy them elsewhere.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Lotus Notes (GUI)
+*****************
Run away from it.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Mutt (TUI)
+**********
-Plenty of Linux developers use mutt, so it must work pretty well.
+Plenty of Linux developers use ``mutt``, so it must work pretty well.
Mutt doesn't come with an editor, so whatever editor you use should be
used in a way that there are no automatic linebreaks. Most editors have
-an "insert file" option that inserts the contents of a file unaltered.
+an :menuselection:`insert file` option that inserts the contents of a file
+unaltered.
+
+To use ``vim`` with mutt:
+
+::
-To use 'vim' with mutt:
set editor="vi"
- If using xclip, type the command
+If using xclip, type the command
+
+::
+
:set paste
- before middle button or shift-insert or use
+
+before middle button or shift-insert or use
+
+::
+
:r filename
if you want to include the patch inline.
-(a)ttach works fine without "set paste".
+(a)ttach works fine without ``set paste``.
-You can also generate patches with 'git format-patch' and then use Mutt
+You can also generate patches with ``git format-patch`` and then use Mutt
to send them:
+
+::
+
$ mutt -H 0001-some-bug-fix.patch
Config options:
+
It should work with default settings.
-However, it's a good idea to set the "send_charset" to:
+However, it's a good idea to set the ``send_charset`` to:
+
+::
+
set send_charset="us-ascii:utf-8"
Mutt is highly customizable. Here is a minimum configuration to start
using Mutt to send patches through Gmail:
-# .muttrc
-# ================ IMAP ====================
-set imap_user = 'yourusername@gmail.com'
-set imap_pass = 'yourpassword'
-set spoolfile = imaps://imap.gmail.com/INBOX
-set folder = imaps://imap.gmail.com/
-set record="imaps://imap.gmail.com/[Gmail]/Sent Mail"
-set postponed="imaps://imap.gmail.com/[Gmail]/Drafts"
-set mbox="imaps://imap.gmail.com/[Gmail]/All Mail"
+::
-# ================ SMTP ====================
-set smtp_url = "smtp://username@smtp.gmail.com:587/"
-set smtp_pass = $imap_pass
-set ssl_force_tls = yes # Require encrypted connection
+ # .muttrc
+ # ================ IMAP ====================
+ set imap_user = 'yourusername@gmail.com'
+ set imap_pass = 'yourpassword'
+ set spoolfile = imaps://imap.gmail.com/INBOX
+ set folder = imaps://imap.gmail.com/
+ set record="imaps://imap.gmail.com/[Gmail]/Sent Mail"
+ set postponed="imaps://imap.gmail.com/[Gmail]/Drafts"
+ set mbox="imaps://imap.gmail.com/[Gmail]/All Mail"
-# ================ Composition ====================
-set editor = `echo \$EDITOR`
-set edit_headers = yes # See the headers when editing
-set charset = UTF-8 # value of $LANG; also fallback for send_charset
-# Sender, email address, and sign-off line must match
-unset use_domain # because joe@localhost is just embarrassing
-set realname = "YOUR NAME"
-set from = "username@gmail.com"
-set use_from = yes
+ # ================ SMTP ====================
+ set smtp_url = "smtp://username@smtp.gmail.com:587/"
+ set smtp_pass = $imap_pass
+ set ssl_force_tls = yes # Require encrypted connection
+
+ # ================ Composition ====================
+ set editor = `echo \$EDITOR`
+ set edit_headers = yes # See the headers when editing
+ set charset = UTF-8 # value of $LANG; also fallback for send_charset
+ # Sender, email address, and sign-off line must match
+ unset use_domain # because joe@localhost is just embarrassing
+ set realname = "YOUR NAME"
+ set from = "username@gmail.com"
+ set use_from = yes
The Mutt docs have lots more information:
+
http://dev.mutt.org/trac/wiki/UseCases/Gmail
+
http://dev.mutt.org/doc/manual.html
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Pine (TUI)
+**********
Pine has had some whitespace truncation issues in the past, but these
should all be fixed now.
@@ -226,12 +257,13 @@ should all be fixed now.
Use alpine (pine's successor) if you can.
Config options:
-- quell-flowed-text is needed for recent versions
-- the "no-strip-whitespace-before-send" option is needed
+
+- ``quell-flowed-text`` is needed for recent versions
+- the ``no-strip-whitespace-before-send`` option is needed
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sylpheed (GUI)
+**************
- Works well for inlining text (or using attachments).
- Allows use of an external editor.
@@ -241,50 +273,50 @@ Sylpheed (GUI)
- Adding addresses to address book doesn't understand the display name
properly.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Thunderbird (GUI)
+*****************
Thunderbird is an Outlook clone that likes to mangle text, but there are ways
to coerce it into behaving.
- Allow use of an external editor:
The easiest thing to do with Thunderbird and patches is to use an
- "external editor" extension and then just use your favorite $EDITOR
+ "external editor" extension and then just use your favorite ``$EDITOR``
for reading/merging patches into the body text. To do this, download
and install the extension, then add a button for it using
- View->Toolbars->Customize... and finally just click on it when in the
- Compose dialog.
+ :menuselection:`View-->Toolbars-->Customize...` and finally just click on it
+ when in the :menuselection:`Compose` dialog.
Please note that "external editor" requires that your editor must not
fork, or in other words, the editor must not return before closing.
You may have to pass additional flags or change the settings of your
editor. Most notably if you are using gvim then you must pass the -f
- option to gvim by putting "/usr/bin/gvim -f" (if the binary is in
- /usr/bin) to the text editor field in "external editor" settings. If you
- are using some other editor then please read its manual to find out how
- to do this.
+ option to gvim by putting ``/usr/bin/gvim -f`` (if the binary is in
+ ``/usr/bin``) to the text editor field in :menuselection:`external editor`
+ settings. If you are using some other editor then please read its manual
+ to find out how to do this.
To beat some sense out of the internal editor, do this:
-- Edit your Thunderbird config settings so that it won't use format=flowed.
- Go to "edit->preferences->advanced->config editor" to bring up the
- thunderbird's registry editor.
+- Edit your Thunderbird config settings so that it won't use ``format=flowed``.
+ Go to :menuselection:`edit-->preferences-->advanced-->config editor` to bring up
+ the thunderbird's registry editor.
-- Set "mailnews.send_plaintext_flowed" to "false"
+- Set ``mailnews.send_plaintext_flowed`` to ``false``
-- Set "mailnews.wraplength" from "72" to "0"
+- Set ``mailnews.wraplength`` from ``72`` to ``0``
-- "View" > "Message Body As" > "Plain Text"
+- :menuselection:`View-->Message Body As-->Plain Text`
-- "View" > "Character Encoding" > "Unicode (UTF-8)"
+- :menuselection:`View-->Character Encoding-->Unicode (UTF-8)`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
TkRat (GUI)
+***********
Works. Use "Insert file..." or external editor.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Gmail (Web GUI)
+***************
Does not work for sending patches.
@@ -295,5 +327,3 @@ although tab2space problem can be solved with external editor.
Another problem is that Gmail will base64-encode any message that has a
non-ASCII character. That includes things like European names.
-
- ###
diff --git a/Documentation/ja_JP/SubmittingPatches b/Documentation/ja_JP/SubmittingPatches
index 5d6ae639bfa0..fffa3106edd2 100644
--- a/Documentation/ja_JP/SubmittingPatches
+++ b/Documentation/ja_JP/SubmittingPatches
@@ -246,7 +246,7 @@ MIME 形式の添付ファイルは Linus に手間を取らせることにな
あれば、誰かが MIME 形式のパッチを再送するよう求めるかもしれません。
余計な変更を加えずにあなたのパッチを送信するための電子メールクライアントの設定
-のヒントについては Documentation/email-clients.txt を参照してください。
+のヒントについては Documentation/development-process/email-clients.rst を参照してください。
8) 電子メールのサイズ
diff --git a/Documentation/zh_CN/email-clients.txt b/Documentation/zh_CN/email-clients.txt
index b9a1a3e6c78d..ede049c4b2e2 100644
--- a/Documentation/zh_CN/email-clients.txt
+++ b/Documentation/zh_CN/email-clients.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/email-clients.txt
+Chinese translated version of Documentation/development-process/email-clients.rst
If you have any comment or update to the content, please contact the
original document maintainer directly. However, if you have a problem
@@ -8,7 +8,7 @@ or if there is a problem with the translation.
Chinese maintainer: Harry Wei <harryxiyou@gmail.com>
---------------------------------------------------------------------
-Documentation/email-clients.txt 的中文翻译
+Documentation/development-process/email-clients.rst 的中文翻译
如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 25/29] Documentation/HOWTO: adjust external link references |
| Message-ID | <sj4Ma-4KI-17@gated-at.bofh.it> |
| In reply to | #1486354 |
- A few link references were missing http://
- Several sites are now redirecting to https protocol. On such
cases, just use the https URL.
NOTE: all URLs were checked and they're pointing to the right places.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/HOWTO | 37 +++++++++++++++++--------------------
1 file changed, 17 insertions(+), 20 deletions(-)
diff --git a/Documentation/HOWTO b/Documentation/HOWTO
index 784724aa4f34..adde88a6d9c4 100644
--- a/Documentation/HOWTO
+++ b/Documentation/HOWTO
@@ -66,7 +66,7 @@ their statements on legal matters.
For common questions and answers about the GPL, please see:
- http://www.gnu.org/licenses/gpl-faq.html
+ https://www.gnu.org/licenses/gpl-faq.html
Documentation
@@ -117,11 +117,9 @@ required reading:
Other excellent descriptions of how to create patches properly are:
"The Perfect Patch"
-
- http://www.ozlabs.org/~akpm/stuff/tpp.txt
+ https://www.ozlabs.org/~akpm/stuff/tpp.txt
"Linux kernel patch submission format"
-
http://linux.yyz.us/patch-format.html
:ref:`Documentation/stable_api_nonsense.txt <stable_api_nonsense>`
@@ -202,7 +200,7 @@ Becoming A Kernel Developer
If you do not know anything about Linux kernel development, you should
look at the Linux KernelNewbies project:
- http://kernelnewbies.org
+ https://kernelnewbies.org
It consists of a helpful mailing list where you can ask almost any type
of basic kernel development question (make sure to search the archives
@@ -220,7 +218,7 @@ If you do not know where you want to start, but you want to look for
some task to start doing to join into the kernel development community,
go to the Linux Kernel Janitor's project:
- http://kernelnewbies.org/KernelJanitors
+ https://kernelnewbies.org/KernelJanitors
It is a great place to start. It describes a list of relatively simple
problems that need to be cleaned up and fixed within the Linux kernel
@@ -234,7 +232,7 @@ 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:
- http://selenic.com/mailman/listinfo/kernel-mentors
+ 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
@@ -264,7 +262,7 @@ branches. These different branches are:
4.x kernel tree
-----------------
4.x kernels are maintained by Linus Torvalds, and can be found on
-kernel.org in the pub/linux/kernel/v4.x/ directory. Its development
+https://kernel.org in the pub/linux/kernel/v4.x/ directory. Its development
process is as follows:
- As soon as a new kernel is released a two weeks window is open,
@@ -272,7 +270,7 @@ process is as follows:
Linus, usually the patches that have already been included in the
-next kernel 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 http://git-scm.com/) but plain patches are also just
+ can be found at https://git-scm.com/) but plain patches are also just
fine.
- After two weeks a -rc1 kernel is released it is now possible to push
only patches that do not include new features that could affect the
@@ -340,7 +338,7 @@ submission and other already ongoing work are avoided.
Most of these repositories are git trees, but there are also other SCMs
in use, or patch queues being published as quilt series. Addresses of
these subsystem repositories are listed in the MAINTAINERS file. Many
-of them can be browsed at http://git.kernel.org/.
+of them can be browsed at https://git.kernel.org/.
Before a proposed patch is committed to such a subsystem tree, it is
subject to review which primarily happens on mailing lists (see the
@@ -349,7 +347,7 @@ process is tracked with the tool patchwork. Patchwork offers a web
interface which shows patch postings, any comments on a patch or
revisions to it, and maintainers can mark patches as under review,
accepted, or rejected. Most of these patchwork sites are listed at
-http://patchwork.kernel.org/.
+https://patchwork.kernel.org/.
4.x -next kernel tree for integration tests
-------------------------------------------
@@ -358,7 +356,7 @@ 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:
- http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
+ https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
This way, the -next kernel gives a summary outlook onto what will be
expected to go into the mainline kernel at the next merge period.
@@ -368,11 +366,11 @@ Adventurous testers are very welcome to runtime-test the -next kernel.
Bug Reporting
-------------
-bugzilla.kernel.org is where the Linux kernel developers track kernel
+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:
- http://bugzilla.kernel.org/page.cgi?id=faq.html
+ https://bugzilla.kernel.org/page.cgi?id=faq.html
The file REPORTING-BUGS in the main kernel source directory has a good
template for how to report a possible kernel bug, and details what kind
@@ -390,13 +388,14 @@ 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 http://bugzilla.kernel.org.
+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)
- http://lists.linux-foundation.org/mailman/listinfo/bugme-new
- http://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
+ https://lists.linux-foundation.org/mailman/listinfo/bugme-new
+
+ https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
@@ -632,8 +631,6 @@ ChangeLog section of the document:
http://www.ozlabs.org/~akpm/stuff/tpp.txt
-
-
All of these things are sometimes very hard to do. It can take years to
perfect these practices (if at all). It's a continuous process of
improvement that requires a lot of patience and determination. But
@@ -646,7 +643,7 @@ start exactly where you are now.
----------
Thanks to Paolo Ciarrocchi who allowed the "Development Process"
-(http://lwn.net/Articles/94386/) section
+(https://lwn.net/Articles/94386/) section
to be based on text he had written, and to Randy Dunlap and Gerrit
Huizenga for some of the list of things you should and should not say.
Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers,
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 11/29] Documentation/CodingStyle: use the proper tag for verbatim font |
| Message-ID | <sj4Ma-4KI-57@gated-at.bofh.it> |
| In reply to | #1486354 |
On Sphinx/ReST notation, ``foo`` means that foo will be will be
marked as inline literal, effectively making it to be presented
as a monospaced font.
As we want this document to be parsed by Sphinx, instead of using
"foo", use ``foo`` for the names that are literal, because it is an
usual typographic convention to use monospaced fonts for functions
and language commands on documents, and we're following such
convention on the other ReST books.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/CodingStyle | 98 +++++++++++++++++++++++------------------------
1 file changed, 49 insertions(+), 49 deletions(-)
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index f103de7e2028..c25528d76af1 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -37,8 +37,8 @@ benefit of warning you when you're nesting your functions too deep.
Heed that warning.
The preferred way to ease multiple indentation levels in a switch statement is
-to align the "switch" and its subordinate "case" labels in the same column
-instead of "double-indenting" the "case" labels. E.g.:
+to align the ``switch`` and its subordinate ``case`` labels in the same column
+instead of ``double-indenting`` the ``case`` labels. E.g.:
.. code-block:: c
@@ -141,7 +141,7 @@ special anyway (you can't nest them in C).
Note that the closing brace is empty on a line of its own, _except_ in
the cases where it is followed by a continuation of the same statement,
-ie a "while" in a do-statement or an "else" in an if-statement, like
+ie a ``while`` in a do-statement or an ``else`` in an if-statement, like
this:
.. code-block:: c
@@ -228,7 +228,7 @@ Do not add spaces around (inside) parenthesized expressions. This example is
s = sizeof( struct file );
When declaring pointer data or a function that returns a pointer type, the
-preferred use of '\*' is adjacent to the data name or function name and not
+preferred use of ``*`` is adjacent to the data name or function name and not
adjacent to the type name. Examples:
.. code-block:: c
@@ -255,10 +255,10 @@ no space after the prefix increment & decrement unary operators::
++ --
-and no space around the '.' and "->" structure member operators.
+and no space around the ``.`` and ``->`` structure member operators.
Do not leave trailing whitespace at the ends of lines. Some editors with
-"smart" indentation will insert whitespace at the beginning of new lines as
+``smart`` indentation will insert whitespace at the beginning of new lines as
appropriate, so you can start typing the next line of code right away.
However, some such editors do not remove the whitespace if you end up not
putting a line of code there, such as if you leave a blank line. As a result,
@@ -276,17 +276,17 @@ context lines.
C is a Spartan language, and so should your naming be. Unlike Modula-2
and Pascal programmers, C programmers do not use cute names like
ThisVariableIsATemporaryCounter. A C programmer would call that
-variable "tmp", which is much easier to write, and not the least more
+variable ``tmp``, which is much easier to write, and not the least more
difficult to understand.
HOWEVER, while mixed-case names are frowned upon, descriptive names for
-global variables are a must. To call a global function "foo" is a
+global variables are a must. To call a global function ``foo`` is a
shooting offense.
GLOBAL variables (to be used only if you _really_ need them) need to
have descriptive names, as do global functions. If you have a function
that counts the number of active users, you should call that
-"count_active_users()" or similar, you should _not_ call it "cntusr()".
+``count_active_users()`` or similar, you should _not_ call it ``cntusr()``.
Encoding the type of a function into the name (so-called Hungarian
notation) is brain damaged - the compiler knows the types anyway and can
@@ -294,9 +294,9 @@ check those, and it only confuses the programmer. No wonder MicroSoft
makes buggy programs.
LOCAL variable names should be short, and to the point. If you have
-some random integer loop counter, it should probably be called "i".
-Calling it "loop_counter" is non-productive, if there is no chance of it
-being mis-understood. Similarly, "tmp" can be just about any type of
+some random integer loop counter, it should probably be called ``i``.
+Calling it ``loop_counter`` is non-productive, if there is no chance of it
+being mis-understood. Similarly, ``tmp`` can be just about any type of
variable that is used to hold a temporary value.
If you are afraid to mix up your local variable names, you have another
@@ -307,7 +307,7 @@ See chapter 6 (Functions).
5) Typedefs
-----------
-Please don't use things like "vps_t".
+Please don't use things like ``vps_t``.
It's a _mistake_ to use typedef for structures and pointers. When you see a
.. code-block:: c
@@ -322,35 +322,35 @@ In contrast, if it says
struct virtual_container *a;
-you can actually tell what "a" is.
+you can actually tell what ``a`` is.
-Lots of people think that typedefs "help readability". Not so. They are
+Lots of people think that typedefs ``help readability``. Not so. They are
useful only for:
(a) totally opaque objects (where the typedef is actively used to _hide_
what the object is).
- Example: "pte_t" etc. opaque objects that you can only access using
+ Example: ``pte_t`` etc. opaque objects that you can only access using
the proper accessor functions.
- NOTE! Opaqueness and "accessor functions" are not good in themselves.
+ NOTE! Opaqueness and ``accessor functions`` are not good in themselves.
The reason we have them for things like pte_t etc. is that there
really is absolutely _zero_ portably accessible information there.
(b) Clear integer types, where the abstraction _helps_ avoid confusion
- whether it is "int" or "long".
+ whether it is ``int`` or ``long``.
u8/u16/u32 are perfectly fine typedefs, although they fit into
category (d) better than here.
NOTE! Again - there needs to be a _reason_ for this. If something is
- "unsigned long", then there's no reason to do
+ ``unsigned long``, then there's no reason to do
typedef unsigned long myflags_t;
but if there is a clear reason for why it under certain circumstances
- might be an "unsigned int" and under other configurations might be
- "unsigned long", then by all means go ahead and use a typedef.
+ might be an ``unsigned int`` and under other configurations might be
+ ``unsigned long``, then by all means go ahead and use a typedef.
(c) when you use sparse to literally create a _new_ type for
type-checking.
@@ -359,10 +359,10 @@ useful only for:
exceptional circumstances.
Although it would only take a short amount of time for the eyes and
- brain to become accustomed to the standard types like 'uint32_t',
+ brain to become accustomed to the standard types like ``uint32_t``,
some people object to their use anyway.
- Therefore, the Linux-specific 'u8/u16/u32/u64' types and their
+ Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their
signed equivalents which are identical to standard types are
permitted -- although they are not mandatory in new code of your
own.
@@ -373,7 +373,7 @@ useful only for:
(e) Types safe for use in userspace.
In certain structures which are visible to userspace, we cannot
- require C99 types and cannot use the 'u32' form above. Thus, we
+ require C99 types and cannot use the ``u32`` form above. Thus, we
use __u32 and similar types in all structures which are shared
with userspace.
@@ -440,13 +440,13 @@ locations and some common work such as cleanup has to be done. If there is no
cleanup needed then just return directly.
Choose label names which say what the goto does or why the goto exists. An
-example of a good name could be "out_free_buffer:" if the goto frees "buffer".
-Avoid using GW-BASIC names like "err1:" and "err2:", as you would have to
+example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``.
+Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to
renumber them if you ever add or remove exit paths, and they make correctness
difficult to verify anyway.
It is advised to indent labels with a single space (not tab), so that
-"diff -p" does not confuse labels with functions.
+``diff -p`` does not confuse labels with functions.
The rationale for using gotos is:
@@ -480,7 +480,7 @@ The rationale for using gotos is:
return result;
}
-A common type of bug to be aware of is "one err bugs" which look like this:
+A common type of bug to be aware of is ``one err bugs`` which look like this:
.. code-block:: c
@@ -489,9 +489,9 @@ A common type of bug to be aware of is "one err bugs" which look like this:
kfree(foo);
return ret;
-The bug in this code is that on some exit paths "foo" is NULL. Normally the
-fix for this is to split it up into two error labels "err_free_bar:" and
-"err_free_foo:":
+The bug in this code is that on some exit paths ``foo`` is NULL. Normally the
+fix for this is to split it up into two error labels ``err_free_bar:`` and
+``err_free_foo:``:
.. code-block:: c
@@ -560,7 +560,7 @@ item, explaining its use.
---------------------------
That's OK, we all do. You've probably been told by your long-time Unix
-user helper that "GNU emacs" automatically formats the C sources for
+user helper that ``GNU emacs`` automatically formats the C sources for
you, and you've noticed that yes, it does do that, but the defaults it
uses are less than desirable (in fact, they are worse than random
typing - an infinite number of monkeys typing into GNU emacs would never
@@ -605,26 +605,26 @@ This will make emacs go better with the kernel coding style for C
files below ``~/src/linux-trees``.
But even if you fail in getting emacs to do sane formatting, not
-everything is lost: use "indent".
+everything is lost: use ``indent``.
Now, again, GNU indent has the same brain-dead settings that GNU emacs
has, which is why you need to give it a few command line options.
However, that's not too bad, because even the makers of GNU indent
recognize the authority of K&R (the GNU people aren't evil, they are
just severely misguided in this matter), so you just give indent the
-options "-kr -i8" (stands for "K&R, 8 character indents"), or use
-"scripts/Lindent", which indents in the latest style.
+options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use
+``scripts/Lindent``, which indents in the latest style.
-"indent" has a lot of options, and especially when it comes to comment
+``indent`` has a lot of options, and especially when it comes to comment
re-formatting you may want to take a look at the man page. But
-remember: "indent" is not a fix for bad programming.
+remember: ``indent`` is not a fix for bad programming.
10) Kconfig configuration files
-------------------------------
For all of the Kconfig* configuration files throughout the source tree,
-the indentation is somewhat different. Lines under a "config" definition
+the indentation is somewhat different. Lines under a ``config`` definition
are indented with one tab, while help text is indented an additional two
spaces. Example::
@@ -669,13 +669,13 @@ counting is a memory management technique. Usually both are needed, and
they are not to be confused with each other.
Many data structures can indeed have two levels of reference counting,
-when there are users of different "classes". The subclass count counts
+when there are users of different ``classes``. The subclass count counts
the number of subclass users, and decrements the global count just once
when the subclass count goes to zero.
-Examples of this kind of "multi-level-reference-counting" can be found in
-memory management ("struct mm_struct": mm_users and mm_count), and in
-filesystem code ("struct super_block": s_count and s_active).
+Examples of this kind of ``multi-level-reference-counting`` can be found in
+memory management (``struct mm_struct``: mm_users and mm_count), and in
+filesystem code (``struct super_block``: s_count and s_active).
Remember: if another thread can find your data structure, and you don't
have a reference count on it, you almost certainly have a bug.
@@ -719,7 +719,7 @@ Things to avoid when using macros:
return -EBUGGERED; \
} while (0)
-is a _very_ bad idea. It looks like a function call but exits the "calling"
+is a _very_ bad idea. It looks like a function call but exits the ``calling``
function; don't break the internal parsers of those who will read the code.
2) macros that depend on having a local variable with a magic name:
@@ -767,7 +767,7 @@ covers RTL which is used frequently with assembly language in the kernel.
Kernel developers like to be seen as literate. Do mind the spelling
of kernel messages to make a good impression. Do not use crippled
-words like "dont"; use "do not" or "don't" instead. Make the messages
+words like ``dont``; use ``do not`` or ``don't`` instead. Make the messages
concise, clear, and unambiguous.
Kernel messages do not have to be terminated with a period.
@@ -839,7 +839,7 @@ and return NULL if that occurred.
----------------------
There appears to be a common misperception that gcc has a magic "make me
-faster" speedup option called "inline". While the use of inlines can be
+faster" speedup option called ``inline``. While the use of inlines can be
appropriate (for example as a means of replacing macros, see Chapter 12), it
very often is not. Abundant use of the inline keyword leads to a much bigger
kernel, which in turn slows the system as a whole down, due to a bigger
@@ -869,7 +869,7 @@ something it would have done anyway.
Functions can return values of many different kinds, and one of the
most common is a value indicating whether the function succeeded or
failed. Such a value can be represented as an error-code integer
-(-Exxx = failure, 0 = success) or a "succeeded" boolean (0 = failure,
+(-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure,
non-zero = success).
Mixing up these two sorts of representations is a fertile source of
@@ -882,8 +882,8 @@ convention::
the function should return an error-code integer. If the name
is a predicate, the function should return a "succeeded" boolean.
-For example, "add work" is a command, and the add_work() function returns 0
-for success or -EBUSY for failure. In the same way, "PCI device present" is
+For example, ``add work`` is a command, and the add_work() function returns 0
+for success or -EBUSY for failure. In the same way, ``PCI device present`` is
a predicate, and the pci_dev_present() function returns 1 if it succeeds in
finding a matching device or 0 if it doesn't.
@@ -969,7 +969,7 @@ that inline assembly can use C parameters.
Large, non-trivial assembly functions should go in .S files, with corresponding
C prototypes defined in C header files. The C prototypes for assembly
-functions should use "asmlinkage".
+functions should use ``asmlinkage``.
You may need to mark your asm statement as volatile, to prevent GCC from
removing it if GCC doesn't notice any side effects. You don't always need to
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 14/29] Documentation/ManagementStyle: convert it to ReST markup |
| Message-ID | <sj4Ma-4KI-23@gated-at.bofh.it> |
| In reply to | #1486354 |
- Convert document name to ReST;
- Convert footnotes;
- Convert sections to ReST format;
- Don't use _foo_, as Sphinx doesn't support underline. Instead,
use bold;
- While here, remove whitespaces at the end of lines.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/ManagementStyle | 154 ++++++++++++++++++++++--------------------
1 file changed, 82 insertions(+), 72 deletions(-)
diff --git a/Documentation/ManagementStyle b/Documentation/ManagementStyle
index a211ee8d8b44..1471df6015a2 100644
--- a/Documentation/ManagementStyle
+++ b/Documentation/ManagementStyle
@@ -1,10 +1,10 @@
-
- Linux kernel management style
+Linux kernel management style
+=============================
This is a short document describing the preferred (or made up, depending
on who you ask) management style for the linux kernel. It's meant to
mirror the CodingStyle document to some degree, and mainly written to
-avoid answering (*) the same (or similar) questions over and over again.
+avoid answering [#f1]_ the same (or similar) questions over and over again.
Management style is very personal and much harder to quantify than
simple coding style rules, so this document may or may not have anything
@@ -14,50 +14,52 @@ might not actually be true. You'll have to decide for yourself.
Btw, when talking about "kernel manager", it's all about the technical
lead persons, not the people who do traditional management inside
companies. If you sign purchase orders or you have any clue about the
-budget of your group, you're almost certainly not a kernel manager.
-These suggestions may or may not apply to you.
+budget of your group, you're almost certainly not a kernel manager.
+These suggestions may or may not apply to you.
First off, I'd suggest buying "Seven Habits of Highly Effective
-People", and NOT read it. Burn it, it's a great symbolic gesture.
+People", and NOT read it. Burn it, it's a great symbolic gesture.
-(*) This document does so not so much by answering the question, but by
-making it painfully obvious to the questioner that we don't have a clue
-to what the answer is.
+.. [#f1] This document does so not so much by answering the question, but by
+ making it painfully obvious to the questioner that we don't have a clue
+ to what the answer is.
Anyway, here goes:
+.. _decisions:
- Chapter 1: Decisions
+1) Decisions
+------------
Everybody thinks managers make decisions, and that decision-making is
important. The bigger and more painful the decision, the bigger the
manager must be to make it. That's very deep and obvious, but it's not
-actually true.
+actually true.
-The name of the game is to _avoid_ having to make a decision. In
+The name of the game is to **avoid** having to make a decision. In
particular, if somebody tells you "choose (a) or (b), we really need you
to decide on this", you're in trouble as a manager. The people you
manage had better know the details better than you, so if they come to
you for a technical decision, you're screwed. You're clearly not
-competent to make that decision for them.
+competent to make that decision for them.
(Corollary:if the people you manage don't know the details better than
-you, you're also screwed, although for a totally different reason.
-Namely that you are in the wrong job, and that _they_ should be managing
-your brilliance instead).
+you, you're also screwed, although for a totally different reason.
+Namely that you are in the wrong job, and that **they** should be managing
+your brilliance instead).
-So the name of the game is to _avoid_ decisions, at least the big and
+So the name of the game is to **avoid** decisions, at least the big and
painful ones. Making small and non-consequential decisions is fine, and
makes you look like you know what you're doing, so what a kernel manager
needs to do is to turn the big and painful ones into small things where
-nobody really cares.
+nobody really cares.
It helps to realize that the key difference between a big decision and a
small one is whether you can fix your decision afterwards. Any decision
can be made small by just always making sure that if you were wrong (and
-you _will_ be wrong), you can always undo the damage later by
+you **will** be wrong), you can always undo the damage later by
backtracking. Suddenly, you get to be doubly managerial for making
-_two_ inconsequential decisions - the wrong one _and_ the right one.
+**two** inconsequential decisions - the wrong one **and** the right one.
And people will even see that as true leadership (*cough* bullshit
*cough*).
@@ -65,10 +67,10 @@ And people will even see that as true leadership (*cough* bullshit
Thus the key to avoiding big decisions becomes to just avoiding to do
things that can't be undone. Don't get ushered into a corner from which
you cannot escape. A cornered rat may be dangerous - a cornered manager
-is just pitiful.
+is just pitiful.
It turns out that since nobody would be stupid enough to ever really let
-a kernel manager have huge fiscal responsibility _anyway_, it's usually
+a kernel manager have huge fiscal responsibility **anyway**, it's usually
fairly easy to backtrack. Since you're not going to be able to waste
huge amounts of money that you might not be able to repay, the only
thing you can backtrack on is a technical decision, and there
@@ -76,113 +78,118 @@ back-tracking is very easy: just tell everybody that you were an
incompetent nincompoop, say you're sorry, and undo all the worthless
work you had people work on for the last year. Suddenly the decision
you made a year ago wasn't a big decision after all, since it could be
-easily undone.
+easily undone.
It turns out that some people have trouble with this approach, for two
reasons:
+
- admitting you were an idiot is harder than it looks. We all like to
maintain appearances, and coming out in public to say that you were
- wrong is sometimes very hard indeed.
+ wrong is sometimes very hard indeed.
- having somebody tell you that what you worked on for the last year
wasn't worthwhile after all can be hard on the poor lowly engineers
- too, and while the actual _work_ was easy enough to undo by just
+ too, and while the actual **work** was easy enough to undo by just
deleting it, you may have irrevocably lost the trust of that
engineer. And remember: "irrevocable" was what we tried to avoid in
the first place, and your decision ended up being a big one after
- all.
+ all.
Happily, both of these reasons can be mitigated effectively by just
admitting up-front that you don't have a friggin' clue, and telling
people ahead of the fact that your decision is purely preliminary, and
might be the wrong thing. You should always reserve the right to change
-your mind, and make people very _aware_ of that. And it's much easier
-to admit that you are stupid when you haven't _yet_ done the really
+your mind, and make people very **aware** of that. And it's much easier
+to admit that you are stupid when you haven't **yet** done the really
stupid thing.
Then, when it really does turn out to be stupid, people just roll their
-eyes and say "Oops, he did it again".
+eyes and say "Oops, he did it again".
This preemptive admission of incompetence might also make the people who
actually do the work also think twice about whether it's worth doing or
-not. After all, if _they_ aren't certain whether it's a good idea, you
+not. After all, if **they** aren't certain whether it's a good idea, you
sure as hell shouldn't encourage them by promising them that what they
work on will be included. Make them at least think twice before they
-embark on a big endeavor.
+embark on a big endeavor.
Remember: they'd better know more about the details than you do, and
they usually already think they have the answer to everything. The best
thing you can do as a manager is not to instill confidence, but rather a
-healthy dose of critical thinking on what they do.
+healthy dose of critical thinking on what they do.
Btw, another way to avoid a decision is to plaintively just whine "can't
we just do both?" and look pitiful. Trust me, it works. If it's not
clear which approach is better, they'll eventually figure it out. The
answer may end up being that both teams get so frustrated by the
-situation that they just give up.
+situation that they just give up.
That may sound like a failure, but it's usually a sign that there was
something wrong with both projects, and the reason the people involved
couldn't decide was that they were both wrong. You end up coming up
smelling like roses, and you avoided yet another decision that you could
-have screwed up on.
+have screwed up on.
- Chapter 2: People
+2) People
+---------
Most people are idiots, and being a manager means you'll have to deal
-with it, and perhaps more importantly, that _they_ have to deal with
-_you_.
+with it, and perhaps more importantly, that **they** have to deal with
+**you**.
It turns out that while it's easy to undo technical mistakes, it's not
as easy to undo personality disorders. You just have to live with
-theirs - and yours.
+theirs - and yours.
However, in order to prepare yourself as a kernel manager, it's best to
remember not to burn any bridges, bomb any innocent villagers, or
alienate too many kernel developers. It turns out that alienating people
is fairly easy, and un-alienating them is hard. Thus "alienating"
immediately falls under the heading of "not reversible", and becomes a
-no-no according to Chapter 1.
+no-no according to :ref:`decisions`.
There's just a few simple rules here:
+
(1) don't call people d*ckheads (at least not in public)
(2) learn how to apologize when you forgot rule (1)
The problem with #1 is that it's very easy to do, since you can say
-"you're a d*ckhead" in millions of different ways (*), sometimes without
+"you're a d*ckhead" in millions of different ways [#f2]_, sometimes without
even realizing it, and almost always with a white-hot conviction that
-you are right.
+you are right.
And the more convinced you are that you are right (and let's face it,
-you can call just about _anybody_ a d*ckhead, and you often _will_ be
-right), the harder it ends up being to apologize afterwards.
+you can call just about **anybody** a d*ckhead, and you often **will** be
+right), the harder it ends up being to apologize afterwards.
To solve this problem, you really only have two options:
+
- get really good at apologies
- spread the "love" out so evenly that nobody really ends up feeling
like they get unfairly targeted. Make it inventive enough, and they
- might even be amused.
+ might even be amused.
The option of being unfailingly polite really doesn't exist. Nobody will
trust somebody who is so clearly hiding his true character.
-(*) Paul Simon sang "Fifty Ways to Leave Your Lover", because quite
-frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't
-scan nearly as well. But I'm sure he thought about it.
+.. [#f2] Paul Simon sang "Fifty Ways to Leave Your Lover", because quite
+ frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't
+ scan nearly as well. But I'm sure he thought about it.
- Chapter 3: People II - the Good Kind
+3) People II - the Good Kind
+----------------------------
While it turns out that most people are idiots, the corollary to that is
sadly that you are one too, and that while we can all bask in the secure
knowledge that we're better than the average person (let's face it,
nobody ever believes that they're average or below-average), we should
also admit that we're not the sharpest knife around, and there will be
-other people that are less of an idiot than you are.
+other people that are less of an idiot than you are.
-Some people react badly to smart people. Others take advantage of them.
+Some people react badly to smart people. Others take advantage of them.
-Make sure that you, as a kernel maintainer, are in the second group.
+Make sure that you, as a kernel maintainer, are in the second group.
Suck up to them, because they are the people who will make your job
easier. In particular, they'll be able to make your decisions for you,
which is what the game is all about.
@@ -191,7 +198,7 @@ So when you find somebody smarter than you are, just coast along. Your
management responsibilities largely become ones of saying "Sounds like a
good idea - go wild", or "That sounds good, but what about xxx?". The
second version in particular is a great way to either learn something
-new about "xxx" or seem _extra_ managerial by pointing out something the
+new about "xxx" or seem **extra** managerial by pointing out something the
smarter person hadn't thought about. In either case, you win.
One thing to look out for is to realize that greatness in one area does
@@ -199,47 +206,49 @@ not necessarily translate to other areas. So you might prod people in
specific directions, but let's face it, they might be good at what they
do, and suck at everything else. The good news is that people tend to
naturally gravitate back to what they are good at, so it's not like you
-are doing something irreversible when you _do_ prod them in some
+are doing something irreversible when you **do** prod them in some
direction, just don't push too hard.
- Chapter 4: Placing blame
+4) Placing blame
+----------------
Things will go wrong, and people want somebody to blame. Tag, you're it.
It's not actually that hard to accept the blame, especially if people
-kind of realize that it wasn't _all_ your fault. Which brings us to the
+kind of realize that it wasn't **all** your fault. Which brings us to the
best way of taking the blame: do it for another guy. You'll feel good
for taking the fall, he'll feel good about not getting blamed, and the
guy who lost his whole 36GB porn-collection because of your incompetence
will grudgingly admit that you at least didn't try to weasel out of it.
Then make the developer who really screwed up (if you can find him) know
-_in_private_ that he screwed up. Not just so he can avoid it in the
+**in_private** that he screwed up. Not just so he can avoid it in the
future, but so that he knows he owes you one. And, perhaps even more
importantly, he's also likely the person who can fix it. Because, let's
-face it, it sure ain't you.
+face it, it sure ain't you.
-Taking the blame is also why you get to be manager in the first place.
+Taking the blame is also why you get to be manager in the first place.
It's part of what makes people trust you, and allow you the potential
glory, because you're the one who gets to say "I screwed up". And if
you've followed the previous rules, you'll be pretty good at saying that
-by now.
+by now.
- Chapter 5: Things to avoid
+5) Things to avoid
+------------------
There's one thing people hate even more than being called "d*ckhead",
and that is being called a "d*ckhead" in a sanctimonious voice. The
first you can apologize for, the second one you won't really get the
chance. They likely will no longer be listening even if you otherwise
-do a good job.
+do a good job.
We all think we're better than anybody else, which means that when
-somebody else puts on airs, it _really_ rubs us the wrong way. You may
+somebody else puts on airs, it **really** rubs us the wrong way. You may
be morally and intellectually superior to everybody around you, but
-don't try to make it too obvious unless you really _intend_ to irritate
-somebody (*).
+don't try to make it too obvious unless you really **intend** to irritate
+somebody [#f3]_.
Similarly, don't be too polite or subtle about things. Politeness easily
ends up going overboard and hiding the problem, and as they say, "On the
@@ -251,15 +260,16 @@ Some humor can help pad both the bluntness and the moralizing. Going
overboard to the point of being ridiculous can drive a point home
without making it painful to the recipient, who just thinks you're being
silly. It can thus help get through the personal mental block we all
-have about criticism.
+have about criticism.
-(*) Hint: internet newsgroups that are not directly related to your work
-are great ways to take out your frustrations at other people. Write
-insulting posts with a sneer just to get into a good flame every once in
-a while, and you'll feel cleansed. Just don't crap too close to home.
+.. [#f3] Hint: internet newsgroups that are not directly related to your work
+ are great ways to take out your frustrations at other people. Write
+ insulting posts with a sneer just to get into a good flame every once in
+ a while, and you'll feel cleansed. Just don't crap too close to home.
- Chapter 6: Why me?
+6) Why me?
+----------
Since your main responsibility seems to be to take the blame for other
peoples mistakes, and make it painfully obvious to everybody else that
@@ -268,9 +278,9 @@ first place?
First off, while you may or may not get screaming teenage girls (or
boys, let's not be judgmental or sexist here) knocking on your dressing
-room door, you _will_ get an immense feeling of personal accomplishment
+room door, you **will** get an immense feeling of personal accomplishment
for being "in charge". Never mind the fact that you're really leading
by trying to keep up with everybody else and running after them as fast
-as you can. Everybody will still think you're the person in charge.
+as you can. Everybody will still think you're the person in charge.
It's a great job if you can hack it.
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 17/29] Documentation/stable_kernel_rules.txt: convert it to ReST markup |
| Message-ID | <sj4Mb-4KI-59@gated-at.bofh.it> |
| In reply to | #1486354 |
- use ReST markups for section headers;
- add cross-references to the options;
- mark code blocks;
- a few minor changes to make Sphinx happy.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/stable_kernel_rules.txt | 101 +++++++++++++++++++++++-----------
1 file changed, 68 insertions(+), 33 deletions(-)
diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt
index ffd4575ec9f2..387d8a44eda2 100644
--- a/Documentation/stable_kernel_rules.txt
+++ b/Documentation/stable_kernel_rules.txt
@@ -1,4 +1,5 @@
-Everything you ever wanted to know about Linux -stable releases.
+Everything you ever wanted to know about Linux -stable releases
+===============================================================
Rules on what kind of patches are accepted, and which ones are not, into the
"-stable" tree:
@@ -27,7 +28,8 @@ Rules on what kind of patches are accepted, and which ones are not, into the
- It or an equivalent fix must already exist in Linus' tree (upstream).
-Procedure for submitting patches to the -stable tree:
+Procedure for submitting patches to the -stable tree
+----------------------------------------------------
- If the patch covers files in net/ or drivers/net please follow netdev stable
submission guidelines as described in
@@ -35,56 +37,78 @@ Procedure for submitting patches to the -stable tree:
- Security patches should not be handled (solely) by the -stable review
process but should follow the procedures in Documentation/SecurityBugs.
-For all other submissions, choose one of the following procedures:
+For all other submissions, choose one of the following procedures
+-----------------------------------------------------------------
- --- Option 1 ---
+.. _option_1:
+
+Option 1
+********
+
+To have the patch automatically included in the stable tree, add the tag
+
+.. code-block:: none
- To have the patch automatically included in the stable tree, add the tag
Cc: stable@vger.kernel.org
- in the sign-off area. Once the patch is merged it will be applied to
- the stable tree without anything else needing to be done by the author
- or subsystem maintainer.
- --- Option 2 ---
+in the sign-off area. Once the patch is merged it will be applied to
+the stable tree without anything else needing to be done by the author
+or subsystem maintainer.
- After the patch has been merged to Linus' tree, send an email to
- stable@vger.kernel.org containing the subject of the patch, the commit ID,
- why you think it should be applied, and what kernel version you wish it to
- be applied to.
+.. _option_2:
- --- Option 3 ---
+Option 2
+********
- Send the patch, after verifying that it follows the above rules, to
- stable@vger.kernel.org. You must note the upstream commit ID in the
- changelog of your submission, as well as the kernel version you wish
- it to be applied to.
+After the patch has been merged to Linus' tree, send an email to
+stable@vger.kernel.org containing the subject of the patch, the commit ID,
+why you think it should be applied, and what kernel version you wish it to
+be applied to.
-Option 1 is *strongly* preferred, is the easiest and most common. Options 2 and
-3 are more useful if the patch isn't deemed worthy at the time it is applied to
-a public git tree (for instance, because it deserves more regression testing
-first). Option 3 is especially useful if the patch needs some special handling
-to apply to an older kernel (e.g., if API's have changed in the meantime).
+.. _option_3:
-Note that for Option 3, if the patch deviates from the original upstream patch
-(for example because it had to be backported) this must be very clearly
-documented and justified in the patch description.
+Option 3
+********
+
+Send the patch, after verifying that it follows the above rules, to
+stable@vger.kernel.org. You must note the upstream commit ID in the
+changelog of your submission, as well as the kernel version you wish
+it to be applied to.
+
+:ref:`option_1` is **strongly** preferred, is the easiest and most common.
+:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed
+worthy at the time it is applied to a public git tree (for instance, because
+it deserves more regression testing first). :ref:`option_3` is especially
+useful if the patch needs some special handling to apply to an older kernel
+(e.g., if API's have changed in the meantime).
+
+Note that for :ref:`option_3`, if the patch deviates from the original
+upstream patch (for example because it had to be backported) this must be very
+clearly documented and justified in the patch description.
The upstream commit ID must be specified with a separate line above the commit
text, like this:
+.. code-block:: none
+
commit <sha1> upstream.
Additionally, some patches submitted via Option 1 may have additional patch
prerequisites which can be cherry-picked. This can be specified in the following
format in the sign-off area:
+.. code-block:: none
+
Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle
Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle
Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic
Cc: <stable@vger.kernel.org> # 3.3.x
- Signed-off-by: Ingo Molnar <mingo@elte.hu>
+ Signed-off-by: Ingo Molnar <mingo@elte.hu>
+
+The tag sequence has the meaning of:
+
+.. code-block:: none
- The tag sequence has the meaning of:
git cherry-pick a1f84a3
git cherry-pick 1b9508f
git cherry-pick fd21073
@@ -93,12 +117,17 @@ format in the sign-off area:
Also, some patches may have kernel version prerequisites. This can be
specified in the following format in the sign-off area:
+.. code-block:: none
+
Cc: <stable@vger.kernel.org> # 3.3.x-
- The tag has the meaning of:
+The tag has the meaning of:
+
+.. code-block:: none
+
git cherry-pick <this commit>
- For each "-stable" tree starting with the specified version.
+For each "-stable" tree starting with the specified version.
Following the submission:
@@ -109,7 +138,8 @@ Following the submission:
other developers and by the relevant subsystem maintainer.
-Review cycle:
+Review cycle
+------------
- When the -stable maintainers decide for a review cycle, the patches will be
sent to the review committee, and the maintainer of the affected area of
@@ -125,17 +155,22 @@ Review cycle:
security kernel team, and not go through the normal review cycle.
Contact the kernel security team for more details on this procedure.
-Trees:
+Trees
+-----
- The queues of patches, for both completed versions and in progress
versions can be found at:
+
http://git.kernel.org/?p=linux/kernel/git/stable/stable-queue.git
+
- The finalized and tagged releases of all stable kernels can be found
in separate branches per version at:
+
http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git
-Review committee:
+Review committee
+----------------
- This is made up of a number of kernel developers who have volunteered for
this task, and a few that haven't.
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Greg KH <greg@kroah.com> |
|---|---|
| Date | 2016-09-20 09:10 +0200 |
| Subject | Re: [PATCH v4 17/29] Documentation/stable_kernel_rules.txt: convert it to ReST markup |
| Message-ID | <sjnlM-8eo-9@gated-at.bofh.it> |
| In reply to | #1486372 |
On Mon, Sep 19, 2016 at 08:07:51AM -0300, Mauro Carvalho Chehab wrote: > - use ReST markups for section headers; > - add cross-references to the options; > - mark code blocks; > - a few minor changes to make Sphinx happy. > > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> > --- > Documentation/stable_kernel_rules.txt | 101 +++++++++++++++++++++++----------- > 1 file changed, 68 insertions(+), 33 deletions(-) > Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 12/29] Documentation/CodingStyle: replace underline markups |
| Message-ID | <sj4Ma-4KI-25@gated-at.bofh.it> |
| In reply to | #1486354 |
Sphinx doesn't accept underline markups by purpose.
While there are ways to support underline via CSS, this won't
be portable with non-html outputs.
As we want CodingStyle to do emphasis, replace _foo_ by **foo**,
using bold emphasis.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/CodingStyle | 32 ++++++++++++++++----------------
1 file changed, 16 insertions(+), 16 deletions(-)
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index c25528d76af1..0024c36b8046 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -2,7 +2,7 @@ Linux kernel coding style
=========================
This is a short document describing the preferred coding style for the
-linux kernel. Coding style is very personal, and I won't _force_ my
+linux kernel. Coding style is very personal, and I won't **force** my
views on anybody, but this is what goes for anything that I have to be
able to maintain, and I'd prefer it for most other things too. Please
at least consider the points made here.
@@ -136,10 +136,10 @@ opening brace at the beginning of the next line, thus:
Heretic people all over the world have claimed that this inconsistency
is ... well ... inconsistent, but all right-thinking people know that
-(a) K&R are _right_ and (b) K&R are right. Besides, functions are
+(a) K&R are **right** and (b) K&R are right. Besides, functions are
special anyway (you can't nest them in C).
-Note that the closing brace is empty on a line of its own, _except_ in
+Note that the closing brace is empty on a line of its own, **except** in
the cases where it is followed by a continuation of the same statement,
ie a ``while`` in a do-statement or an ``else`` in an if-statement, like
this:
@@ -283,10 +283,10 @@ HOWEVER, while mixed-case names are frowned upon, descriptive names for
global variables are a must. To call a global function ``foo`` is a
shooting offense.
-GLOBAL variables (to be used only if you _really_ need them) need to
+GLOBAL variables (to be used only if you **really** need them) need to
have descriptive names, as do global functions. If you have a function
that counts the number of active users, you should call that
-``count_active_users()`` or similar, you should _not_ call it ``cntusr()``.
+``count_active_users()`` or similar, you should **not** call it ``cntusr()``.
Encoding the type of a function into the name (so-called Hungarian
notation) is brain damaged - the compiler knows the types anyway and can
@@ -308,7 +308,7 @@ See chapter 6 (Functions).
-----------
Please don't use things like ``vps_t``.
-It's a _mistake_ to use typedef for structures and pointers. When you see a
+It's a **mistake** to use typedef for structures and pointers. When you see a
.. code-block:: c
@@ -327,7 +327,7 @@ you can actually tell what ``a`` is.
Lots of people think that typedefs ``help readability``. Not so. They are
useful only for:
- (a) totally opaque objects (where the typedef is actively used to _hide_
+ (a) totally opaque objects (where the typedef is actively used to **hide**
what the object is).
Example: ``pte_t`` etc. opaque objects that you can only access using
@@ -335,15 +335,15 @@ useful only for:
NOTE! Opaqueness and ``accessor functions`` are not good in themselves.
The reason we have them for things like pte_t etc. is that there
- really is absolutely _zero_ portably accessible information there.
+ really is absolutely **zero** portably accessible information there.
- (b) Clear integer types, where the abstraction _helps_ avoid confusion
+ (b) Clear integer types, where the abstraction **helps** avoid confusion
whether it is ``int`` or ``long``.
u8/u16/u32 are perfectly fine typedefs, although they fit into
category (d) better than here.
- NOTE! Again - there needs to be a _reason_ for this. If something is
+ NOTE! Again - there needs to be a **reason** for this. If something is
``unsigned long``, then there's no reason to do
typedef unsigned long myflags_t;
@@ -352,7 +352,7 @@ useful only for:
might be an ``unsigned int`` and under other configurations might be
``unsigned long``, then by all means go ahead and use a typedef.
- (c) when you use sparse to literally create a _new_ type for
+ (c) when you use sparse to literally create a **new** type for
type-checking.
(d) New types which are identical to standard C99 types, in certain
@@ -381,7 +381,7 @@ Maybe there are other cases too, but the rule should basically be to NEVER
EVER use a typedef unless you can clearly match one of those rules.
In general, a pointer, or a struct that has elements that can reasonably
-be directly accessed should _never_ be a typedef.
+be directly accessed should **never** be a typedef.
6) Functions
@@ -509,7 +509,7 @@ Ideally you should simulate errors to test all exit paths.
Comments are good, but there is also a danger of over-commenting. NEVER
try to explain HOW your code works in a comment: it's much better to
-write the code so that the _working_ is obvious, and it's a waste of
+write the code so that the **working** is obvious, and it's a waste of
time to explain badly written code.
Generally, you want your comments to tell WHAT your code does, not HOW.
@@ -656,14 +656,14 @@ Data structures that have visibility outside the single-threaded
environment they are created and destroyed in should always have
reference counts. In the kernel, garbage collection doesn't exist (and
outside the kernel garbage collection is slow and inefficient), which
-means that you absolutely _have_ to reference count all your uses.
+means that you absolutely **have** to reference count all your uses.
Reference counting means that you can avoid locking, and allows multiple
users to have access to the data structure in parallel - and not having
to worry about the structure suddenly going away from under them just
because they slept or did something else for a while.
-Note that locking is _not_ a replacement for reference counting.
+Note that locking is **not** a replacement for reference counting.
Locking is used to keep data structures coherent, while reference
counting is a memory management technique. Usually both are needed, and
they are not to be confused with each other.
@@ -719,7 +719,7 @@ Things to avoid when using macros:
return -EBUGGERED; \
} while (0)
-is a _very_ bad idea. It looks like a function call but exits the ``calling``
+is a **very** bad idea. It looks like a function call but exits the ``calling``
function; don't break the internal parsers of those who will read the code.
2) macros that depend on having a local variable with a magic name:
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 27/29] Documentation/SubmitChecklist: convert it to ReST markup |
| Message-ID | <sj4Mb-4KI-61@gated-at.bofh.it> |
| In reply to | #1486354 |
- use ``foo`` to markup inline literal stuff, effectively making it
to be presented as a monospaced font when parsed by Sphinx;
- the markup below the title should have the same length as the
title;
- Fix the list markups, from "1:" to "1)";
- Split item 2 into a separate list for the build options, in order
to be presented as a list on Sphinx;
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/SubmitChecklist | 116 ++++++++++++++++++++++--------------------
1 file changed, 62 insertions(+), 54 deletions(-)
diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist
index bb114c8a781c..22a370ff34e5 100644
--- a/Documentation/SubmitChecklist
+++ b/Documentation/SubmitChecklist
@@ -1,110 +1,118 @@
Linux Kernel patch submission checklist
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Here are some basic things that developers should do if they want to see their
kernel patch submissions accepted more quickly.
These are all above and beyond the documentation that is provided in
-Documentation/SubmittingPatches and elsewhere regarding submitting Linux
-kernel patches.
+Documentation/SubmittingPatches
+and elsewhere regarding submitting Linux kernel patches.
-1: If you use a facility then #include the file that defines/declares
+1) If you use a facility then #include the file that defines/declares
that facility. Don't depend on other header files pulling in ones
that you use.
-2: Builds cleanly with applicable or modified CONFIG options =y, =m, and
- =n. No gcc warnings/errors, no linker warnings/errors.
+2) Builds cleanly:
-2b: Passes allnoconfig, allmodconfig
+ a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and
+ ``=n``. No ``gcc`` warnings/errors, no linker warnings/errors.
-2c: Builds successfully when using O=builddir
+ b) Passes ``allnoconfig``, ``allmodconfig``
-3: Builds on multiple CPU architectures by using local cross-compile tools
+ c) Builds successfully when using ``O=builddir``
+
+3) Builds on multiple CPU architectures by using local cross-compile tools
or some other build farm.
-4: ppc64 is a good architecture for cross-compilation checking because it
- tends to use `unsigned long' for 64-bit quantities.
+4) ppc64 is a good architecture for cross-compilation checking because it
+ tends to use ``unsigned long`` for 64-bit quantities.
5: Check your patch for general style as detailed in
- Documentation/CodingStyle. Check for trivial violations with the
- patch style checker prior to submission (scripts/checkpatch.pl).
+ Documentation/CodingStyle.
+ Check for trivial violations with the patch style checker prior to
+ submission (``scripts/checkpatch.pl``).
You should be able to justify all violations that remain in
your patch.
-6: Any new or modified CONFIG options don't muck up the config menu.
+6) Any new or modified ``CONFIG`` options don't muck up the config menu.
-7: All new Kconfig options have help text.
+7) All new ``Kconfig`` options have help text.
-8: Has been carefully reviewed with respect to relevant Kconfig
+8) Has been carefully reviewed with respect to relevant ``Kconfig``
combinations. This is very hard to get right with testing -- brainpower
pays off here.
-9: Check cleanly with sparse.
+9) Check cleanly with sparse.
-10: Use 'make checkstack' and 'make namespacecheck' and fix any problems
- that they find. Note: checkstack does not point out problems explicitly,
- but any one function that uses more than 512 bytes on the stack is a
- candidate for change.
+10) Use ``make checkstack`` and ``make namespacecheck`` and fix any problems
+ that they find.
+
+ .. note::
+
+ ``checkstack`` does not point out problems explicitly,
+ but any one function that uses more than 512 bytes on the stack is a
+ candidate for change.
11: Include :ref:`kernel-doc <kernel_doc>` to document global kernel APIs.
(Not required for static functions, but OK there also.) Use
``make htmldocs`` or ``make pdfdocs`` to check the
:ref:`kernel-doc <kernel_doc>` and fix any issues.
-12: Has been tested with CONFIG_PREEMPT, CONFIG_DEBUG_PREEMPT,
- CONFIG_DEBUG_SLAB, CONFIG_DEBUG_PAGEALLOC, CONFIG_DEBUG_MUTEXES,
- CONFIG_DEBUG_SPINLOCK, CONFIG_DEBUG_ATOMIC_SLEEP, CONFIG_PROVE_RCU
- and CONFIG_DEBUG_OBJECTS_RCU_HEAD all simultaneously enabled.
+12) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``,
+ ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
+ ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``,
+ ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all
+ simultaneously enabled.
-13: Has been build- and runtime tested with and without CONFIG_SMP and
- CONFIG_PREEMPT.
+13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and
+ ``CONFIG_PREEMPT.``
-14: If the patch affects IO/Disk, etc: has been tested with and without
- CONFIG_LBDAF.
+14) If the patch affects IO/Disk, etc: has been tested with and without
+ ``CONFIG_LBDAF.``
-15: All codepaths have been exercised with all lockdep features enabled.
+15) All codepaths have been exercised with all lockdep features enabled.
-16: All new /proc entries are documented under Documentation/
+16) All new ``/proc`` entries are documented under ``Documentation/``
-17: All new kernel boot parameters are documented in
- Documentation/kernel-parameters.txt.
+17) All new kernel boot parameters are documented in
+ ``Documentation/kernel-parameters.txt``.
-18: All new module parameters are documented with MODULE_PARM_DESC()
+18) All new module parameters are documented with ``MODULE_PARM_DESC()``
-19: All new userspace interfaces are documented in Documentation/ABI/.
- See Documentation/ABI/README for more information.
+19) All new userspace interfaces are documented in ``Documentation/ABI/``.
+ See ``Documentation/ABI/README`` for more information.
Patches that change userspace interfaces should be CCed to
linux-api@vger.kernel.org.
-20: Check that it all passes `make headers_check'.
+20) Check that it all passes ``make headers_check``.
-21: Has been checked with injection of at least slab and page-allocation
- failures. See Documentation/fault-injection/.
+21) Has been checked with injection of at least slab and page-allocation
+ failures. See ``Documentation/fault-injection/``.
If the new code is substantial, addition of subsystem-specific fault
injection might be appropriate.
-22: Newly-added code has been compiled with `gcc -W' (use "make
- EXTRA_CFLAGS=-W"). This will generate lots of noise, but is good for
- finding bugs like "warning: comparison between signed and unsigned".
+22) Newly-added code has been compiled with ``gcc -W`` (use
+ ``make EXTRA_CFLAGS=-W``). This will generate lots of noise, but is good
+ for finding bugs like "warning: comparison between signed and unsigned".
-23: Tested after it has been merged into the -mm patchset to make sure
+23) Tested after it has been merged into the -mm patchset to make sure
that it still works with all of the other queued patches and various
changes in the VM, VFS, and other subsystems.
-24: All memory barriers {e.g., barrier(), rmb(), wmb()} need a comment in the
- source code that explains the logic of what they are doing and why.
+24) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a
+ comment in the source code that explains the logic of what they are doing
+ and why.
-25: If any ioctl's are added by the patch, then also update
- Documentation/ioctl/ioctl-number.txt.
+25) If any ioctl's are added by the patch, then also update
+ ``Documentation/ioctl/ioctl-number.txt``.
-26: If your modified source code depends on or uses any of the kernel
- APIs or features that are related to the following kconfig symbols,
- then test multiple builds with the related kconfig symbols disabled
- and/or =m (if that option is available) [not all of these at the
+26) If your modified source code depends on or uses any of the kernel
+ APIs or features that are related to the following ``Kconfig`` symbols,
+ then test multiple builds with the related ``Kconfig`` symbols disabled
+ and/or ``=m`` (if that option is available) [not all of these at the
same time, just various/random combinations of them]:
- CONFIG_SMP, CONFIG_SYSFS, CONFIG_PROC_FS, CONFIG_INPUT, CONFIG_PCI,
- CONFIG_BLOCK, CONFIG_PM, CONFIG_MAGIC_SYSRQ,
- CONFIG_NET, CONFIG_INET=n (but latter with CONFIG_NET=y)
+ ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``,
+ ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``).
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 02/29] doc: development-process: convert it to ReST markup |
| Message-ID | <sj4Ma-4KI-41@gated-at.bofh.it> |
| In reply to | #1486354 |
This document is on good shape for ReST: all it was needed was
to fix the section markups, add a toctree, convert the tables
and add a few code/quote blocks.
While not strictly required, I opted to use lowercase for
the titles, just like the other books that were converted
to Sphinx.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/development-process/1.Intro | 68 ++++++++++------------
Documentation/development-process/2.Process | 41 +++++++++----
Documentation/development-process/3.Early-stage | 22 +++++--
Documentation/development-process/4.Coding | 46 ++++++++++-----
Documentation/development-process/5.Posting | 26 +++++++--
Documentation/development-process/6.Followthrough | 14 +++--
Documentation/development-process/7.AdvancedTopics | 13 ++++-
Documentation/development-process/8.Conclusion | 8 ++-
.../development-process/development-process.rst | 27 +++++++++
9 files changed, 179 insertions(+), 86 deletions(-)
create mode 100644 Documentation/development-process/development-process.rst
diff --git a/Documentation/development-process/1.Intro b/Documentation/development-process/1.Intro
index 9b614480aa84..22642b3fe903 100644
--- a/Documentation/development-process/1.Intro
+++ b/Documentation/development-process/1.Intro
@@ -1,16 +1,8 @@
-1: A GUIDE TO THE KERNEL DEVELOPMENT PROCESS
+Introdution
+===========
-The purpose of this document is to help developers (and their managers)
-work with the development community with a minimum of frustration. It is
-an attempt to document how this community works in a way which is
-accessible to those who are not intimately familiar with Linux kernel
-development (or, indeed, free software development in general). While
-there is some technical material here, this is very much a process-oriented
-discussion which does not require a deep knowledge of kernel programming to
-understand.
-
-
-1.1: EXECUTIVE SUMMARY
+Executive summary
+-----------------
The rest of this section covers the scope of the kernel development process
and the kinds of frustrations that developers and their employers can
@@ -20,41 +12,41 @@ availability to users, community support in many forms, and the ability to
influence the direction of kernel development. Code contributed to the
Linux kernel must be made available under a GPL-compatible license.
-Section 2 introduces the development process, the kernel release cycle, and
-the mechanics of the merge window. The various phases in the patch
-development, review, and merging cycle are covered. There is some
+:ref:`development_process` introduces the development process, the kernel
+release cycle, and the mechanics of the merge window. The various phases in
+the patch development, review, and merging cycle are covered. There is some
discussion of tools and mailing lists. Developers wanting to get started
with kernel development are encouraged to track down and fix bugs as an
initial exercise.
-Section 3 covers early-stage project planning, with an emphasis on
-involving the development community as soon as possible.
+:ref:`development_early_stage` covers early-stage project planning, with an
+emphasis on involving the development community as soon as possible.
-Section 4 is about the coding process; several pitfalls which have been
-encountered by other developers are discussed. Some requirements for
+:ref:`development_coding` is about the coding process; several pitfalls which
+have been encountered by other developers are discussed. Some requirements for
patches are covered, and there is an introduction to some of the tools
which can help to ensure that kernel patches are correct.
-Section 5 talks about the process of posting patches for review. To be
-taken seriously by the development community, patches must be properly
-formatted and described, and they must be sent to the right place.
+:ref:`development_posting` talks about the process of posting patches for
+review. To be taken seriously by the development community, patches must be
+properly formatted and described, and they must be sent to the right place.
Following the advice in this section should help to ensure the best
possible reception for your work.
-Section 6 covers what happens after posting patches; the job is far from
-done at that point. Working with reviewers is a crucial part of the
-development process; this section offers a number of tips on how to avoid
-problems at this important stage. Developers are cautioned against
+:ref:`development_followthrough` covers what happens after posting patches; the
+job is far from done at that point. Working with reviewers is a crucial part
+of the development process; this section offers a number of tips on how to
+avoid problems at this important stage. Developers are cautioned against
assuming that the job is done when a patch is merged into the mainline.
-Section 7 introduces a couple of "advanced" topics: managing patches with
-git and reviewing patches posted by others.
+:ref:`development_advancedtopics` introduces a couple of "advanced" topics:
+managing patches with git and reviewing patches posted by others.
-Section 8 concludes the document with pointers to sources for more
-information on kernel development.
+:ref:`development_conclusion` concludes the document with pointers to sources
+for more information on kernel development.
-
-1.2: WHAT THIS DOCUMENT IS ABOUT
+What this document is about
+---------------------------
The Linux kernel, at over 8 million lines of code and well over 1000
contributors to each release, is one of the largest and most active free
@@ -108,8 +100,8 @@ community is always in need of developers who will help to make the kernel
better; the following text should help you - or those who work for you -
join our community.
-
-1.3: CREDITS
+Credits
+-------
This document was written by Jonathan Corbet, corbet@lwn.net. It has been
improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland
@@ -120,8 +112,8 @@ Jochen Voß.
This work was supported by the Linux Foundation; thanks especially to
Amanda McPherson, who saw the value of this effort and made it all happen.
-
-1.4: THE IMPORTANCE OF GETTING CODE INTO THE MAINLINE
+The importance of getting code into the mainline
+------------------------------------------------
Some companies and developers occasionally wonder why they should bother
learning how to work with the kernel community and get their code into the
@@ -233,8 +225,8 @@ commercial life, after which a new version must be released. At that
point, vendors whose code is in the mainline and well maintained will be
much better positioned to get the new product ready for market quickly.
-
-1.5: LICENSING
+Licensing
+---------
Code is contributed to the Linux kernel under a number of licenses, but all
code must be compatible with version 2 of the GNU General Public License
diff --git a/Documentation/development-process/2.Process b/Documentation/development-process/2.Process
index c24e156a6118..ce5561bb3f8e 100644
--- a/Documentation/development-process/2.Process
+++ b/Documentation/development-process/2.Process
@@ -1,4 +1,7 @@
-2: HOW THE DEVELOPMENT PROCESS WORKS
+.. _development_process:
+
+How the development process works
+=================================
Linux kernel development in the early 1990's was a pretty loose affair,
with relatively small numbers of users and developers involved. With a
@@ -7,19 +10,21 @@ course of one year, the kernel has since had to evolve a number of
processes to keep development happening smoothly. A solid understanding of
how the process works is required in order to be an effective part of it.
-
-2.1: THE BIG PICTURE
+The big picture
+---------------
The kernel developers use a loosely time-based release process, with a new
major kernel release happening every two or three months. The recent
release history looks like this:
+ ====== =================
2.6.38 March 14, 2011
2.6.37 January 4, 2011
2.6.36 October 20, 2010
2.6.35 August 1, 2010
2.6.34 May 15, 2010
2.6.33 February 24, 2010
+ ====== =================
Every 2.6.x release is a major kernel release with new features, internal
API changes, and more. A typical 2.6 release can contain nearly 10,000
@@ -68,6 +73,7 @@ At that point the whole process starts over again.
As an example, here is how the 2.6.38 development cycle went (all dates in
2011):
+ ============== ===============================
January 4 2.6.37 stable release
January 18 2.6.38-rc1, merge window closes
January 21 2.6.38-rc2
@@ -78,6 +84,7 @@ As an example, here is how the 2.6.38 development cycle went (all dates in
March 1 2.6.38-rc7
March 7 2.6.38-rc8
March 14 2.6.38 stable release
+ ============== ===============================
How do the developers decide when to close the development cycle and create
the stable release? The most significant metric used is the list of
@@ -105,11 +112,13 @@ next development kernel. Kernels will typically receive stable updates for
a little more than one development cycle past their initial release. So,
for example, the 2.6.36 kernel's history looked like:
+ ============== ===============================
October 10 2.6.36 stable release
November 22 2.6.36.1
December 9 2.6.36.2
January 7 2.6.36.3
February 17 2.6.36.4
+ ============== ===============================
2.6.36.4 was the final stable update for the 2.6.36 release.
@@ -117,9 +126,11 @@ Some kernels are designated "long term" kernels; they will receive support
for a longer period. As of this writing, the current long term kernels
and their maintainers are:
+ ====== ====================== ===========================
2.6.27 Willy Tarreau (Deep-frozen stable kernel)
2.6.32 Greg Kroah-Hartman
2.6.35 Andi Kleen (Embedded flag kernel)
+ ====== ====================== ===========================
The selection of a kernel for long-term support is purely a matter of a
maintainer having the need and the time to maintain that release. There
@@ -127,7 +138,8 @@ are no known plans for long-term support for any specific upcoming
release.
-2.2: THE LIFECYCLE OF A PATCH
+The lifecycle of a patch
+------------------------
Patches do not go directly from the developer's keyboard into the mainline
kernel. There is, instead, a somewhat involved (if somewhat informal)
@@ -195,8 +207,8 @@ is to try to cut the process down to a single "merging into the mainline"
step. This approach invariably leads to frustration for everybody
involved.
-
-2.3: HOW PATCHES GET INTO THE KERNEL
+How patches get into the Kernel
+-------------------------------
There is exactly one person who can merge patches into the mainline kernel
repository: Linus Torvalds. But, of the over 9,500 patches which went
@@ -242,7 +254,8 @@ finding the right maintainer. Sending patches directly to Linus is not
normally the right way to go.
-2.4: NEXT TREES
+Next trees
+----------
The chain of subsystem trees guides the flow of patches into the kernel,
but it also raises an interesting question: what if somebody wants to look
@@ -294,7 +307,8 @@ all patches merged during a given merge window should really have found
their way into linux-next some time before the merge window opens.
-2.4.1: STAGING TREES
+Staging trees
+-------------
The kernel source tree contains the drivers/staging/ directory, where
many sub-directories for drivers or filesystems that are on their way to
@@ -322,7 +336,8 @@ staging drivers. So staging is, at best, a stop on the way toward becoming
a proper mainline driver.
-2.5: TOOLS
+Tools
+-----
As can be seen from the above text, the kernel development process depends
heavily on the ability to herd collections of patches in various
@@ -368,7 +383,8 @@ upstream. For the management of certain kinds of trees (-mm, for example),
quilt is the best tool for the job.
-2.6: MAILING LISTS
+Mailing lists
+-------------
A great deal of Linux kernel development work is done by way of mailing
lists. It is hard to be a fully-functioning member of the community
@@ -436,7 +452,8 @@ filesystem, etc. subsystems. The best place to look for mailing lists is
in the MAINTAINERS file packaged with the kernel source.
-2.7: GETTING STARTED WITH KERNEL DEVELOPMENT
+Getting started with Kernel development
+---------------------------------------
Questions about how to get started with the kernel development process are
common - from both individuals and companies. Equally common are missteps
@@ -463,6 +480,8 @@ they wish for by these means.
Andrew Morton gives this advice for aspiring kernel developers
+::
+
The #1 project for all kernel beginners should surely be "make sure
that the kernel runs perfectly at all times on all machines which
you can lay your hands on". Usually the way to do this is to work
diff --git a/Documentation/development-process/3.Early-stage b/Documentation/development-process/3.Early-stage
index f87ba7b3fbac..af2c0af931d6 100644
--- a/Documentation/development-process/3.Early-stage
+++ b/Documentation/development-process/3.Early-stage
@@ -1,4 +1,7 @@
-3: EARLY-STAGE PLANNING
+.. _development_early_stage:
+
+Early-stage planning
+====================
When contemplating a Linux kernel development project, it can be tempting
to jump right in and start coding. As with any significant project,
@@ -7,7 +10,8 @@ line of code is written. Some time spent in early planning and
communication can save far more time later on.
-3.1: SPECIFYING THE PROBLEM
+Specifying the problem
+----------------------
Like any engineering project, a successful kernel enhancement starts with a
clear description of the problem to be solved. In some cases, this step is
@@ -64,7 +68,8 @@ answers to a short set of questions:
Only then does it make sense to start considering possible solutions.
-3.2: EARLY DISCUSSION
+Early discussion
+----------------
When planning a kernel development project, it makes great sense to hold
discussions with the community before launching into implementation. Early
@@ -117,7 +122,8 @@ In each of these cases, a great deal of pain and extra work could have been
avoided with some early discussion with the kernel developers.
-3.3: WHO DO YOU TALK TO?
+Who do you talk to?
+-------------------
When developers decide to take their plans public, the next question will
be: where do we start? The answer is to find the right mailing list(s) and
@@ -141,6 +147,8 @@ development project.
The task of finding the right maintainer is sometimes challenging enough
that the kernel developers have added a script to ease the process:
+::
+
.../scripts/get_maintainer.pl
This script will return the current maintainer(s) for a given file or
@@ -155,7 +163,8 @@ If all else fails, talking to Andrew Morton can be an effective way to
track down a maintainer for a specific piece of code.
-3.4: WHEN TO POST?
+When to post?
+-------------
If possible, posting your plans during the early stages can only be
helpful. Describe the problem being solved and any plans that have been
@@ -179,7 +188,8 @@ idea. The best thing to do in this situation is to proceed, keeping the
community informed as you go.
-3.5: GETTING OFFICIAL BUY-IN
+Getting official buy-in
+-----------------------
If your work is being done in a corporate environment - as most Linux
kernel work is - you must, obviously, have permission from suitably
diff --git a/Documentation/development-process/4.Coding b/Documentation/development-process/4.Coding
index 9a3ee77cefb1..9d5cef996f7f 100644
--- a/Documentation/development-process/4.Coding
+++ b/Documentation/development-process/4.Coding
@@ -1,4 +1,7 @@
-4: GETTING THE CODE RIGHT
+.. _development_coding:
+
+Getting the code right
+======================
While there is much to be said for a solid and community-oriented design
process, the proof of any kernel development project is in the resulting
@@ -12,9 +15,11 @@ will shift toward doing things right and the tools which can help in that
quest.
-4.1: PITFALLS
+Pitfalls
+---------
-* Coding style
+Coding style
+************
The kernel has long had a standard coding style, described in
Documentation/CodingStyle. For much of that time, the policies described
@@ -54,7 +59,8 @@ style (a line which becomes far less readable if split to fit within the
80-column limit, for example), just do it.
-* Abstraction layers
+Abstraction layers
+******************
Computer Science professors teach students to make extensive use of
abstraction layers in the name of flexibility and information hiding.
@@ -87,7 +93,8 @@ implement that functionality at a higher level. There is no value in
replicating the same code throughout the kernel.
-* #ifdef and preprocessor use in general
+#ifdef and preprocessor use in general
+**************************************
The C preprocessor seems to present a powerful temptation to some C
programmers, who see it as a way to efficiently encode a great deal of
@@ -113,7 +120,8 @@ easier to read, do not evaluate their arguments multiple times, and allow
the compiler to perform type checking on the arguments and return value.
-* Inline functions
+Inline functions
+****************
Inline functions present a hazard of their own, though. Programmers can
become enamored of the perceived efficiency inherent in avoiding a function
@@ -137,7 +145,8 @@ placement of "inline" keywords may not just be excessive; it could also be
irrelevant.
-* Locking
+Locking
+*******
In May, 2006, the "Devicescape" networking stack was, with great
fanfare, released under the GPL and made available for inclusion in the
@@ -151,7 +160,7 @@ This code showed a number of signs of having been developed behind
corporate doors. But one large problem in particular was that it was not
designed to work on multiprocessor systems. Before this networking stack
(now called mac80211) could be merged, a locking scheme needed to be
-retrofitted onto it.
+retrofitted onto it.
Once upon a time, Linux kernel code could be developed without thinking
about the concurrency issues presented by multiprocessor systems. Now,
@@ -169,7 +178,8 @@ enough to pick the right tool for the job. Code which shows a lack of
attention to concurrency will have a difficult path into the mainline.
-* Regressions
+Regressions
+***********
One final hazard worth mentioning is this: it can be tempting to make a
change (which may bring big improvements) which causes something to break
@@ -185,6 +195,8 @@ change if it brings new functionality to ten systems for each one it
breaks? The best answer to this question was expressed by Linus in July,
2007:
+::
+
So we don't fix bugs by introducing new problems. That way lies
madness, and nobody ever knows if you actually make any real
progress at all. Is it two steps forwards, one step back, or one
@@ -201,8 +213,8 @@ reason, a great deal of thought, clear documentation, and wide review for
user-space interfaces is always required.
-
-4.2: CODE CHECKING TOOLS
+Code checking tools
+-------------------
For now, at least, the writing of error-free code remains an ideal that few
of us can reach. What we can hope to do, though, is to catch and fix as
@@ -250,7 +262,7 @@ testing purposes. In particular, you should turn on:
There are quite a few other debugging options, some of which will be
discussed below. Some of them have a significant performance impact and
should not be used all of the time. But some time spent learning the
-available options will likely be paid back many times over in short order.
+available options will likely be paid back many times over in short order.
One of the heavier debugging tools is the locking checker, or "lockdep."
This tool will track the acquisition and release of every lock (spinlock or
@@ -263,7 +275,7 @@ occasion, deadlock. This kind of problem can be painful (for both
developers and users) in a deployed system; lockdep allows them to be found
in an automated manner ahead of time. Code with any sort of non-trivial
locking should be run with lockdep enabled before being submitted for
-inclusion.
+inclusion.
As a diligent kernel programmer, you will, beyond doubt, check the return
status of any operation (such as a memory allocation) which can fail. The
@@ -300,7 +312,7 @@ Documentation/coccinelle.txt for more information.
Other kinds of portability errors are best found by compiling your code for
other architectures. If you do not happen to have an S/390 system or a
Blackfin development board handy, you can still perform the compilation
-step. A large set of cross compilers for x86 systems can be found at
+step. A large set of cross compilers for x86 systems can be found at
http://www.kernel.org/pub/tools/crosstool/
@@ -308,7 +320,8 @@ Some time spent installing and using these compilers will help avoid
embarrassment later.
-4.3: DOCUMENTATION
+Documentation
+-------------
Documentation has often been more the exception than the rule with kernel
development. Even so, adequate documentation will help to ease the merging
@@ -364,7 +377,8 @@ out. Anything which might tempt a code janitor to make an incorrect
"cleanup" needs a comment saying why it is done the way it is. And so on.
-4.4: INTERNAL API CHANGES
+Internal API changes
+--------------------
The binary interface provided by the kernel to user space cannot be broken
except under the most severe circumstances. The kernel's internal
diff --git a/Documentation/development-process/5.Posting b/Documentation/development-process/5.Posting
index 8a48c9b62864..b511ddf7e82a 100644
--- a/Documentation/development-process/5.Posting
+++ b/Documentation/development-process/5.Posting
@@ -1,4 +1,7 @@
-5: POSTING PATCHES
+.. _development_posting:
+
+Posting patches
+===============
Sooner or later, the time comes when your work is ready to be presented to
the community for review and, eventually, inclusion into the mainline
@@ -11,7 +14,8 @@ SubmittingDrivers, and SubmitChecklist in the kernel documentation
directory.
-5.1: WHEN TO POST
+When to post
+------------
There is a constant temptation to avoid posting patches before they are
completely "ready." For simple patches, that is not a problem. If the
@@ -27,7 +31,8 @@ patches which are known to be half-baked, but those who do will come in
with the idea that they can help you drive the work in the right direction.
-5.2: BEFORE CREATING PATCHES
+Before creating patches
+-----------------------
There are a number of things which should be done before you consider
sending patches to the development community. These include:
@@ -52,7 +57,8 @@ As a general rule, putting in some extra thought before posting code almost
always pays back the effort in short order.
-5.3: PATCH PREPARATION
+Patch preparation
+-----------------
The preparation of patches for posting can be a surprising amount of work,
but, once again, attempting to save time here is not generally advisable
@@ -122,7 +128,8 @@ which takes quite a bit of time and thought after the "real work" has been
done. When done properly, though, it is time well spent.
-5.4: PATCH FORMATTING AND CHANGELOGS
+Patch formatting and changelogs
+-------------------------------
So now you have a perfect series of patches for posting, but the work is
not done quite yet. Each patch needs to be formatted into a message which
@@ -140,6 +147,8 @@ that end, each patch will be composed of the following:
subsystem name first, followed by the purpose of the patch. For
example:
+ ::
+
gpio: fix build on CONFIG_GPIO_SYSFS=n
- A blank line followed by a detailed description of the contents of the
@@ -192,6 +201,8 @@ been associated with the development of this patch. They are described in
detail in the SubmittingPatches document; what follows here is a brief
summary. Each of these lines has the format:
+::
+
tag: Full Name <email address> optional-other-stuff
The tags in common use are:
@@ -225,7 +236,8 @@ Be careful in the addition of tags to your patches: only Cc: is appropriate
for addition without the explicit permission of the person named.
-5.5: SENDING THE PATCH
+Sending the patch
+-----------------
Before you mail your patches, there are a couple of other things you should
take care of:
@@ -287,6 +299,8 @@ obvious maintainer, Andrew Morton is often the patch target of last resort.
Patches need good subject lines. The canonical format for a patch line is
something like:
+::
+
[PATCH nn/mm] subsys: one-line description of the patch
where "nn" is the ordinal number of the patch, "mm" is the total number of
diff --git a/Documentation/development-process/6.Followthrough b/Documentation/development-process/6.Followthrough
index 41d324a9420d..a173cd5f93d2 100644
--- a/Documentation/development-process/6.Followthrough
+++ b/Documentation/development-process/6.Followthrough
@@ -1,4 +1,7 @@
-6: FOLLOWTHROUGH
+.. _development_followthrough:
+
+Followthrough
+=============
At this point, you have followed the guidelines given so far and, with the
addition of your own engineering skills, have posted a perfect series of
@@ -16,7 +19,8 @@ standards. A failure to participate in this process is quite likely to
prevent the inclusion of your patches into the mainline.
-6.1: WORKING WITH REVIEWERS
+Working with reviewers
+----------------------
A patch of any significance will result in a number of comments from other
developers as they review the code. Working with reviewers can be, for
@@ -97,7 +101,8 @@ though, and not before all other alternatives have been explored. And bear
in mind, of course, that he may not agree with you either.
-6.2: WHAT HAPPENS NEXT
+What happens next
+-----------------
If a patch is considered to be a good thing to add to the kernel, and once
most of the review issues have been resolved, the next step is usually
@@ -177,7 +182,8 @@ it with the assumption that you will not be around to maintain it
afterward.
-6.3: OTHER THINGS THAT CAN HAPPEN
+Other things that can happen
+-----------------------------
One day, you may open your mail client and see that somebody has mailed you
a patch to your code. That is one of the advantages of having your code
diff --git a/Documentation/development-process/7.AdvancedTopics b/Documentation/development-process/7.AdvancedTopics
index 26dc3fa196e4..81d61c5d62dd 100644
--- a/Documentation/development-process/7.AdvancedTopics
+++ b/Documentation/development-process/7.AdvancedTopics
@@ -1,11 +1,15 @@
-7: ADVANCED TOPICS
+.. _development_advancedtopics:
+
+Advanced topics
+===============
At this point, hopefully, you have a handle on how the development process
works. There is still more to learn, however! This section will cover a
number of topics which can be helpful for developers wanting to become a
regular part of the Linux kernel development process.
-7.1: MANAGING PATCHES WITH GIT
+Managing patches with git
+-------------------------
The use of distributed version control for the kernel began in early 2002,
when Linus first started playing with the proprietary BitKeeper
@@ -114,6 +118,8 @@ radar. Kernel developers tend to get unhappy when they see that kind of
thing happening; putting up a git tree with unreviewed or off-topic patches
can affect your ability to get trees pulled in the future. Quoting Linus:
+::
+
You can send me patches, but for me to pull a git patch from you, I
need to know that you know what you're doing, and I need to be able
to trust things *without* then having to go and check every
@@ -141,7 +147,8 @@ format the request as other developers expect, and will also check to be
sure that you have remembered to push those changes to the public server.
-7.2: REVIEWING PATCHES
+Reviewing patches
+-----------------
Some readers will certainly object to putting this section with "advanced
topics" on the grounds that even beginning kernel developers should be
diff --git a/Documentation/development-process/8.Conclusion b/Documentation/development-process/8.Conclusion
index caef69022e9c..23ec7cbc2d2b 100644
--- a/Documentation/development-process/8.Conclusion
+++ b/Documentation/development-process/8.Conclusion
@@ -1,4 +1,7 @@
-8: FOR MORE INFORMATION
+.. _development_conclusion:
+
+For more information
+====================
There are numerous sources of information on Linux kernel development and
related topics. First among those will always be the Documentation
@@ -47,7 +50,8 @@ Documentation for git can be found at:
http://www.kernel.org/pub/software/scm/git/docs/user-manual.html
-9: CONCLUSION
+Conclusion
+==========
Congratulations to anybody who has made it through this long-winded
document. Hopefully it has provided a helpful understanding of how the
diff --git a/Documentation/development-process/development-process.rst b/Documentation/development-process/development-process.rst
new file mode 100644
index 000000000000..d431a1098875
--- /dev/null
+++ b/Documentation/development-process/development-process.rst
@@ -0,0 +1,27 @@
+A guide to the Kernel Development Process
+=========================================
+
+Contents:
+
+.. toctree::
+ :numbered:
+ :maxdepth: 2
+
+ 1.Intro
+ 2.Process
+ 3.Early-stage
+ 4.Coding
+ 5.Posting
+ 6.Followthrough
+ 7.AdvancedTopics
+ 8.Conclusion
+
+The purpose of this document is to help developers (and their managers)
+work with the development community with a minimum of frustration. It is
+an attempt to document how this community works in a way which is
+accessible to those who are not intimately familiar with Linux kernel
+development (or, indeed, free software development in general). While
+there is some technical material here, this is very much a process-oriented
+discussion which does not require a deep knowledge of kernel programming to
+understand.
+
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 16/29] Documentation/stable_api_nonsense.txt: convert it to ReST markup |
| Message-ID | <sj4Ma-4KI-45@gated-at.bofh.it> |
| In reply to | #1486354 |
Add markups for it to be properly parsed by Sphinx.
As people browsing this document may not notice that the source
file title is "stable_api_nonsense", I opted to use bold to
the rationale for this document. I also found it better to
add a note when it says that the nonsense applies only to the
kABI/kAPI, and not to uAPI.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/stable_api_nonsense.txt | 35 ++++++++++++++++++++++++-----------
1 file changed, 24 insertions(+), 11 deletions(-)
diff --git a/Documentation/stable_api_nonsense.txt b/Documentation/stable_api_nonsense.txt
index db3be892afb2..9187b4ef4bac 100644
--- a/Documentation/stable_api_nonsense.txt
+++ b/Documentation/stable_api_nonsense.txt
@@ -1,17 +1,24 @@
The Linux Kernel Driver Interface
+==================================
+
(all of your questions answered and then some)
Greg Kroah-Hartman <greg@kroah.com>
-This is being written to try to explain why Linux does not have a binary
-kernel interface, nor does it have a stable kernel interface. Please
-realize that this article describes the _in kernel_ interfaces, not the
-kernel to userspace interfaces. The kernel to userspace interface is
-the one that application programs use, the syscall interface. That
-interface is _very_ stable over time, and will not break. I have old
-programs that were built on a pre 0.9something kernel that still work
-just fine on the latest 2.6 kernel release. That interface is the one
-that users and application programmers can count on being stable.
+This is being written to try to explain why Linux **does not have a binary
+kernel interface, nor does it have a stable kernel interface**.
+
+.. note::
+
+ Please realize that this article describes the **in kernel** interfaces, not
+ the kernel to userspace interfaces.
+
+ The kernel to userspace interface is the one that application programs use,
+ the syscall interface. That interface is **very** stable over time, and
+ will not break. I have old programs that were built on a pre 0.9something
+ kernel that still work just fine on the latest 2.6 kernel release.
+ That interface is the one that users and application programmers can count
+ on being stable.
Executive Summary
@@ -33,7 +40,7 @@ to worry about the in-kernel interfaces changing. For the majority of
the world, they neither see this interface, nor do they care about it at
all.
-First off, I'm not going to address _any_ legal issues about closed
+First off, I'm not going to address **any** legal issues about closed
source, hidden source, binary blobs, source wrappers, or any other term
that describes kernel drivers that do not have their source code
released under the GPL. Please consult a lawyer if you have any legal
@@ -51,19 +58,23 @@ Binary Kernel Interface
Assuming that we had a stable kernel source interface for the kernel, a
binary interface would naturally happen too, right? Wrong. Please
consider the following facts about the Linux kernel:
+
- Depending on the version of the C compiler you use, different kernel
data structures will contain different alignment of structures, and
possibly include different functions in different ways (putting
functions inline or not.) The individual function organization
isn't that important, but the different data structure padding is
very important.
+
- Depending on what kernel build options you select, a wide range of
different things can be assumed by the kernel:
+
- different structures can contain different fields
- Some functions may not be implemented at all, (i.e. some locks
compile away to nothing for non-SMP builds.)
- Memory within the kernel can be aligned in different ways,
depending on the build options.
+
- Linux runs on a wide range of different processor architectures.
There is no way that binary drivers from one architecture will run
on another architecture properly.
@@ -105,6 +116,7 @@ As a specific examples of this, the in-kernel USB interfaces have
undergone at least three different reworks over the lifetime of this
subsystem. These reworks were done to address a number of different
issues:
+
- A change from a synchronous model of data streams to an asynchronous
one. This reduced the complexity of a number of drivers and
increased the throughput of all USB drivers such that we are now
@@ -166,6 +178,7 @@ very little effort on your part.
The very good side effects of having your driver in the main kernel tree
are:
+
- The quality of the driver will rise as the maintenance costs (to the
original developer) will decrease.
- Other developers will add features to your driver.
@@ -175,7 +188,7 @@ are:
changes require it.
- The driver automatically gets shipped in all Linux distributions
without having to ask the distros to add it.
-
+
As Linux supports a larger number of different devices "out of the box"
than any other operating system, and it supports these devices on more
different processor architectures than any other operating system, this
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 20/29] Documentation/SubmittingPatches: enrich the Sphinx output |
| Message-ID | <sj4Ma-4KI-29@gated-at.bofh.it> |
| In reply to | #1486354 |
Do a few changes to make the output look better:
- use bullets on trivial patches list;
- use monotonic font for tools name;
- use :manpage:`foo` for man pages;
- don't put all references to maintainer*html at the same line.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
Documentation/SubmittingPatches | 100 ++++++++++++++++++++++------------------
1 file changed, 55 insertions(+), 45 deletions(-)
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 04a4284d8ee4..352771b736cd 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -15,10 +15,10 @@ submitting code. If you are submitting a driver, also read
Documentation/SubmittingDrivers; for device tree binding patches, read
Documentation/devicetree/bindings/submitting-patches.txt.
-Many of these steps describe the default behavior of the git version
-control system; if you use git to prepare your patches, you'll find much
+Many of these steps describe the default behavior of the ``git`` version
+control system; if you use ``git`` to prepare your patches, you'll find much
of the mechanical work done for you, though you'll still need to prepare
-and document a sensible set of patches. In general, use of git will make
+and document a sensible set of patches. In general, use of ``git`` will make
your life as a kernel developer easier.
Creating and Sending your Change
@@ -29,7 +29,7 @@ Creating and Sending your Change
-------------------------------
If you do not have a repository with the current kernel source handy, use
-git to obtain one. You'll want to start with the mainline repository,
+``git`` to obtain one. You'll want to start with the mainline repository,
which can be grabbed with::
git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
@@ -48,13 +48,14 @@ in the next section), but that is the hard way to do kernel development.
If you must generate your patches by hand, use ``diff -up`` or ``diff -uprN``
to create patches. Git generates patches in this form by default; if
-you're using git, you can skip this section entirely.
+you're using ``git``, you can skip this section entirely.
All changes to the Linux kernel occur in the form of patches, as
-generated by diff(1). When creating your patch, make sure to create it
-in "unified diff" format, as supplied by the ``-u`` argument to diff(1).
+generated by :manpage:`diff(1)`. When creating your patch, make sure to
+create it in "unified diff" format, as supplied by the ``-u`` argument
+to :manpage:`diff(1)`.
Also, please use the ``-p`` argument which shows which C function each
-change is in - that makes the resultant diff a lot easier to read.
+change is in - that makes the resultant ``diff`` a lot easier to read.
Patches should be based in the root kernel source directory,
not in any lower subdirectory.
@@ -70,7 +71,7 @@ To create a patch for a single file, it is often sufficient to do::
diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
To create a patch for multiple files, you should unpack a "vanilla",
-or unmodified kernel source tree, and generate a diff against your
+or unmodified kernel source tree, and generate a ``diff`` against your
own source tree. For example::
MYSRC= /devel/linux
@@ -81,20 +82,20 @@ own source tree. For example::
linux-3.19-vanilla $MYSRC > /tmp/patch
``dontdiff`` is a list of files which are generated by the kernel during
-the build process, and should be ignored in any diff(1)-generated
+the build process, and should be ignored in any :manpage:`diff(1)`-generated
patch.
Make sure your patch does not include any extra files which do not
belong in a patch submission. Make sure to review your patch -after-
-generating it with diff(1), to ensure accuracy.
+generating it with :manpage:`diff(1)`, to ensure accuracy.
If your changes produce a lot of deltas, you need to split them into
individual patches which modify things in logical stages; see
:ref:`split_changes`. This will facilitate review by other kernel developers,
very important if you want your patch accepted.
-If you're using git, ``git rebase -i`` can help you with this process. If
-you're not using git, quilt <http://savannah.nongnu.org/projects/quilt>
+If you're using ``git``, ``git rebase -i`` can help you with this process. If
+you're not using ``git``, ``quilt`` <http://savannah.nongnu.org/projects/quilt>
is another popular alternative.
.. _describe_changes:
@@ -133,7 +134,7 @@ as you intend it to.
The maintainer will thank you if you write your patch description in a
form which can be easily pulled into Linux's source code management
-system, git, as a "commit log". See :ref:`explicit_in_reply_to`.
+system, ``git``, as a "commit log". See :ref:`explicit_in_reply_to`.
Solve only one problem per patch. If your description starts to get
long, that's a sign that you probably need to split up your patch.
@@ -156,7 +157,7 @@ its behaviour.
If the patch fixes a logged bug entry, refer to that bug entry by
number and URL. If the patch follows from a mailing list discussion,
give a URL to the mailing list archive; use the https://lkml.kernel.org/
-redirector with a Message-Id, to ensure that the links cannot become
+redirector with a ``Message-Id``, to ensure that the links cannot become
stale.
However, try to make your explanation understandable without external
@@ -181,13 +182,13 @@ there is no collision with your six-character ID now, that condition may
change five years from now.
If your patch fixes a bug in a specific commit, e.g. you found an issue using
-git-bisect, please use the 'Fixes:' tag with the first 12 characters of the
-SHA-1 ID, and the one line summary. For example::
+``git bisect``, please use the 'Fixes:' tag with the first 12 characters of
+the SHA-1 ID, and the one line summary. For example::
Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
-The following git-config settings can be used to add a pretty format for
-outputting the above style in the git log or git show commands::
+The following ``git config`` settings can be used to add a pretty format for
+outputting the above style in the ``git log`` or ``git show`` commands::
[core]
abbrev = 12
@@ -318,17 +319,17 @@ into the MAINTAINERS file for its current manager.
Trivial patches must qualify for one of the following rules:
- Spelling fixes in documentation
- Spelling fixes for errors which could break grep(1)
- Warning fixes (cluttering with useless warnings is bad)
- Compilation fixes (only if they are actually correct)
- Runtime fixes (only if they actually fix things)
- Removing use of deprecated functions/macros
- Contact detail and documentation fixes
- Non-portable code replaced by portable code (even in arch-specific,
- since people copy, as long as it's trivial)
- Any fix by the author/maintainer of the file (ie. patch monkey
- in re-transmission mode)
+- Spelling fixes in documentation
+- Spelling fixes for errors which could break :manpage:`grep(1)`
+- Warning fixes (cluttering with useless warnings is bad)
+- Compilation fixes (only if they are actually correct)
+- Runtime fixes (only if they actually fix things)
+- Removing use of deprecated functions/macros
+- Contact detail and documentation fixes
+- Non-portable code replaced by portable code (even in arch-specific,
+ since people copy, as long as it's trivial)
+- Any fix by the author/maintainer of the file (ie. patch monkey
+ in re-transmission mode)
@@ -341,8 +342,11 @@ developer to be able to "quote" your changes, using standard e-mail
tools, so that they may comment on specific portions of your code.
For this reason, all patches should be submitted by e-mail "inline".
-WARNING: Be wary of your editor's word-wrap corrupting your patch,
-if you choose to cut-n-paste your patch.
+
+.. warning::
+
+ Be wary of your editor's word-wrap corrupting your patch,
+ if you choose to cut-n-paste your patch.
Do not attach the patch as a MIME attachment, compressed or not.
Many popular e-mail applications will not always transmit a MIME
@@ -604,7 +608,7 @@ for more details.
------------------------------
This section describes how the patch itself should be formatted. Note
-that, if you have your patches stored in a git repository, proper patch
+that, if you have your patches stored in a ``git`` repository, proper patch
formatting can be had with ``git format-patch``. The tools cannot create
the necessary text, though, so read the instructions below anyway.
@@ -629,7 +633,7 @@ The canonical patch message body contains the following:
- Any additional comments not suitable for the changelog.
- - The actual patch (diff output).
+ - The actual patch (``diff`` output).
The Subject line format makes it very easy to sort the emails
alphabetically by subject line - pretty much any email reader will
@@ -647,13 +651,13 @@ series`` is an ordered sequence of multiple, related patches).
Bear in mind that the ``summary phrase`` of your email becomes a
globally-unique identifier for that patch. It propagates all the way
-into the git changelog. The ``summary phrase`` may later be used in
+into the ``git`` changelog. The ``summary phrase`` may later be used in
developer discussions which refer to the patch. People will want to
google for the ``summary phrase`` to read discussion regarding that
patch. It will also be the only thing that people may quickly see
when, two or three months later, they are going through perhaps
-thousands of patches using tools such as ``gitk`` or "git log
---oneline".
+thousands of patches using tools such as ``gitk`` or ``git log
+--oneline``.
For these reasons, the ``summary`` must be no more than 70-75
characters, and it must describe both what the patch changes, as well
@@ -704,18 +708,18 @@ The ``---`` marker line serves the essential purpose of marking for patch
handling tools where the changelog message ends.
One good use for the additional comments after the ``---`` marker is for
-a diffstat, to show what files have changed, and the number of
-inserted and deleted lines per file. A diffstat is especially useful
+a ``diffstat``, to show what files have changed, and the number of
+inserted and deleted lines per file. A ``diffstat`` is especially useful
on bigger patches. Other comments relevant only to the moment or the
maintainer, not suitable for the permanent changelog, should also go
here. A good example of such comments might be ``patch changelogs``
which describe what has changed between the v1 and v2 version of the
patch.
-If you are going to include a diffstat after the ``---`` marker, please
-use diffstat options ``-p 1 -w 70`` so that filenames are listed from
+If you are going to include a ``diffstat`` after the ``---`` marker, please
+use ``diffstat`` options ``-p 1 -w 70`` so that filenames are listed from
the top of the kernel source tree and don't use too much horizontal
-space (easily fit in 80 columns, maybe with some indentation). (git
+space (easily fit in 80 columns, maybe with some indentation). (``git``
generates appropriate diffstats by default.)
See more details on the proper patch format in the following
@@ -761,9 +765,9 @@ interest on a single line; it should look something like::
A pull request should also include an overall message saying what will be
included in the request, a ``git shortlog`` listing of the patches
-themselves, and a diffstat showing the overall effect of the patch series.
+themselves, and a ``diffstat`` showing the overall effect of the patch series.
The easiest way to get all this information together is, of course, to let
-git do it for you with the ``git request-pull`` command.
+``git`` do it for you with the ``git request-pull`` command.
Some maintainers (including Linus) want to see pull requests from signed
commits; that increases their confidence that the request actually came
@@ -775,7 +779,7 @@ signed by one or more core kernel developers. This step can be hard for
new developers, but there is no way around it. Attending conferences can
be a good way to find developers who can sign your key.
-Once you have prepared a patch series in git that you wish to have somebody
+Once you have prepared a patch series in ``git`` that you wish to have somebody
pull, create a signed tag with ``git tag -s``. This will create a new tag
identifying the last commit in the series and containing a signature
created with your private key. You will also have the opportunity to add a
@@ -803,10 +807,15 @@ Jeff Garzik, "Linux kernel patch submission format".
Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
<http://www.kroah.com/log/linux/maintainer.html>
+
<http://www.kroah.com/log/linux/maintainer-02.html>
+
<http://www.kroah.com/log/linux/maintainer-03.html>
+
<http://www.kroah.com/log/linux/maintainer-04.html>
+
<http://www.kroah.com/log/linux/maintainer-05.html>
+
<http://www.kroah.com/log/linux/maintainer-06.html>
NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
@@ -820,5 +829,6 @@ Linus Torvalds's mail on the canonical patch format:
Andi Kleen, "On submitting kernel patches"
Some strategies to get difficult or controversial changes in.
+
http://halobates.de/on-submitting-patches.pdf
--
2.7.4
[toc] | [prev] | [next] | [standalone]
| From | Mauro Carvalho Chehab <mchehab@s-opensource.com> |
|---|---|
| Date | 2016-09-19 13:20 +0200 |
| Subject | [PATCH v4 07/29] Documentation/applying-patches.txt: Update the information there |
| Message-ID | <sj4Mb-4KI-63@gated-at.bofh.it> |
| In reply to | #1486354 |
This document is old: it is from Kernel v2.6.12 days. Update it to the current status, and add a reference for the linux-next tree. Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com> --- Documentation/applying-patches.txt | 255 ++++++++++++++++--------------------- 1 file changed, 110 insertions(+), 145 deletions(-) diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt index 573eb3bee19e..0e873dbf5566 100644 --- a/Documentation/applying-patches.txt +++ b/Documentation/applying-patches.txt @@ -6,7 +6,7 @@ Original by: Jesper Juhl, August 2005 Last update: - 2006-01-05 + 2016-09-14 A frequently asked question on the Linux Kernel Mailing List is how to apply @@ -90,23 +90,23 @@ this: patch -p1 -i path/to/patch-x.y.z -If your patch file is compressed with gzip or bzip2 and you don't want to +If your patch file is compressed with gzip or xz and you don't want to uncompress it before applying it, then you can feed it to patch like this instead: :: - zcat path/to/patch-x.y.z.gz | patch -p1 - bzcat path/to/patch-x.y.z.bz2 | patch -p1 + xzcat path/to/patch-x.y.z.xz | patch -p1 + bzcat path/to/patch-x.y.z.gz | patch -p1 If you wish to uncompress the patch file by hand first before applying it (what I assume you've done in the examples below), then you simply run -gunzip or bunzip2 on the file -- like this: +gunzip or xz on the file -- like this: :: gunzip patch-x.y.z.gz - bunzip2 patch-x.y.z.bz2 + xz -d patch-x.y.z.xz Which will leave you with a plain text patch-x.y.z file that you can feed to patch via stdin or the ``-i`` argument, as you prefer. @@ -226,16 +226,16 @@ You can use the ``interdiff`` program (http://cyberelk.net/tim/patchutils/) to generate a patch representing the differences between two patches and then apply the result. -This will let you move from something like 2.6.12.2 to 2.6.12.3 in a single +This will let you move from something like 4.7.2 to 4.7.3 in a single step. The -z flag to interdiff will even let you feed it patches in gzip or bzip2 compressed form directly without the use of zcat or bzcat or manual decompression. -Here's how you'd go from 2.6.12.2 to 2.6.12.3 in a single step: +Here's how you'd go from 4.7.2 to 4.7.3 in a single step: :: - interdiff -z ../patch-2.6.12.2.bz2 ../patch-2.6.12.3.gz | patch -p1 + interdiff -z ../patch-4.7.2.gz ../patch-4.7.3.gz | patch -p1 Although interdiff may save you a step or two you are generally advised to do the additional steps since interdiff can get things wrong in some cases. @@ -257,21 +257,13 @@ The patches are available at http://kernel.org/ Most recent patches are linked from the front page, but they also have specific homes. -The 2.6.x.y (-stable) and 2.6.x patches live at +The 4.x.y (-stable) and 4.x patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/ + ftp://ftp.kernel.org/pub/linux/kernel/v4.x/ The -rc patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/testing/ - -The -git patches live at - - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/ - -The -mm kernels live at - - ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/ + ftp://ftp.kernel.org/pub/linux/kernel/v4.x/testing/ In place of ``ftp.kernel.org`` you can use ``ftp.cc.kernel.org``, where cc is a country code. This way you'll be downloading from a mirror site that's most @@ -280,53 +272,55 @@ less bandwidth used globally and less load on the main kernel.org servers -- these are good things, so do use mirrors when possible. -The 2.6.x kernels -================= +The 4.x kernels +=============== These are the base stable releases released by Linus. The highest numbered release is the most recent. If regressions or other serious flaws are found, then a -stable fix patch -will be released (see below) on top of this base. Once a new 2.6.x base +will be released (see below) on top of this base. Once a new 4.x base kernel is released, a patch is made available that is a delta between the -previous 2.6.x kernel and the new one. +previous 4.x kernel and the new one. -To apply a patch moving from 2.6.11 to 2.6.12, you'd do the following (note -that such patches do **NOT** apply on top of 2.6.x.y kernels but on top of the -base 2.6.x kernel -- if you need to move from 2.6.x.y to 2.6.x+1 you need to -first revert the 2.6.x.y patch). +To apply a patch moving from 4.6 to 4.7, you'd do the following (note +that such patches do **NOT** apply on top of 4.x.y kernels but on top of the +base 4.x kernel -- if you need to move from 4.x.y to 4.x+1 you need to +first revert the 4.x.y patch). Here are some examples: :: - # moving from 2.6.11 to 2.6.12 - $ cd ~/linux-2.6.11 # change to kernel source dir - $ patch -p1 < ../patch-2.6.12 # apply the 2.6.12 patch + # moving from 4.6 to 4.7 + + $ cd ~/linux-4.6 # change to kernel source dir + $ patch -p1 < ../patch-4.7 # apply the 4.7 patch $ cd .. - $ mv linux-2.6.11 linux-2.6.12 # rename source dir + $ mv linux-4.6 linux-4.7 # rename source dir + + # moving from 4.6.1 to 4.7 - # moving from 2.6.11.1 to 2.6.12 - $ cd ~/linux-2.6.11.1 # change to kernel source dir - $ patch -p1 -R < ../patch-2.6.11.1 # revert the 2.6.11.1 patch - # source dir is now 2.6.11 - $ patch -p1 < ../patch-2.6.12 # apply new 2.6.12 patch + $ cd ~/linux-4.6.1 # change to kernel source dir + $ patch -p1 -R < ../patch-4.6.1 # revert the 4.6.1 patch + # source dir is now 4.6 + $ patch -p1 < ../patch-4.7 # apply new 4.7 patch $ cd .. - $ mv linux-2.6.11.1 linux-2.6.12 # rename source dir + $ mv linux-4.6.1 linux-4.7 # rename source dir -The 2.6.x.y kernels -=================== +The 4.x.y kernels +================= -Kernels with 4-digit versions are -stable kernels. They contain small(ish) +Kernels with 3-digit versions are -stable kernels. They contain small(ish) critical fixes for security problems or significant regressions discovered -in a given 2.6.x kernel. +in a given 4.x kernel. 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 2.6.x.y kernel is available, then the highest numbered 2.6.x kernel is +If no 4.x.y kernel is available, then the highest numbered 4.x kernel is the current stable kernel. .. note:: @@ -334,25 +328,25 @@ the current stable kernel. The -stable team usually do make incremental patches available as well as patches against the latest mainline release, but I only cover the non-incremental ones below. The incremental ones can be found at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/incr/ + ftp://ftp.kernel.org/pub/linux/kernel/v4.x/incr/ -These patches are not incremental, meaning that for example the 2.6.12.3 -patch does not apply on top of the 2.6.12.2 kernel source, but rather on top -of the base 2.6.12 kernel source. +These patches are not incremental, meaning that for example the 4.7.3 +patch does not apply on top of the 4.7.2 kernel source, but rather on top +of the base 4.7 kernel source. -So, in order to apply the 2.6.12.3 patch to your existing 2.6.12.2 kernel -source you have to first back out the 2.6.12.2 patch (so you are left with a -base 2.6.12 kernel source) and then apply the new 2.6.12.3 patch. +So, in order to apply the 4.7.3 patch to your existing 4.7.2 kernel +source you have to first back out the 4.7.2 patch (so you are left with a +base 4.7 kernel source) and then apply the new 4.7.3 patch. Here's a small example: :: - $ cd ~/linux-2.6.12.2 # change to the kernel source dir - $ patch -p1 -R < ../patch-2.6.12.2 # revert the 2.6.12.2 patch - $ patch -p1 < ../patch-2.6.12.3 # apply the new 2.6.12.3 patch + $ cd ~/linux-4.7.2 # change to the kernel source dir + $ patch -p1 -R < ../patch-4.7.2 # revert the 4.7.2 patch + $ patch -p1 < ../patch-4.7.3 # apply the new 4.7.3 patch $ cd .. - $ mv linux-2.6.12.2 linux-2.6.12.3 # rename the kernel source dir + $ mv linux-4.7.2 linux-4.7.3 # rename the kernel source dir The -rc kernels =============== @@ -371,37 +365,40 @@ This is a good branch to run for people who want to help out testing development kernels but do not want to run some of the really experimental stuff (such people should see the sections about -git and -mm kernels below). -The -rc patches are not incremental, they apply to a base 2.6.x kernel, just -like the 2.6.x.y patches described above. The kernel version before the -rcN +The -rc patches are not incremental, they apply to a base 4.x kernel, just +like the 4.x.y patches described above. The kernel version before the -rcN suffix denotes the version of the kernel that this -rc kernel will eventually turn into. -So, 2.6.13-rc5 means that this is the fifth release candidate for the 2.6.13 -kernel and the patch should be applied on top of the 2.6.12 kernel source. +So, 4.8-rc5 means that this is the fifth release candidate for the 4.8 +kernel and the patch should be applied on top of the 4.7 kernel source. Here are 3 examples of how to apply these patches: :: - # first an example of moving from 2.6.12 to 2.6.13-rc3 - $ cd ~/linux-2.6.12 # change to the 2.6.12 source dir - $ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch + # first an example of moving from 4.7 to 4.8-rc3 + + $ cd ~/linux-4.7 # change to the 4.7 source dir + $ patch -p1 < ../patch-4.8-rc3 # apply the 4.8-rc3 patch $ cd .. - $ mv linux-2.6.12 linux-2.6.13-rc3 # rename the source dir + $ mv linux-4.7 linux-4.8-rc3 # rename the source dir + + # now let's move from 4.8-rc3 to 4.8-rc5 - # now let's move from 2.6.13-rc3 to 2.6.13-rc5 - $ cd ~/linux-2.6.13-rc3 # change to the 2.6.13-rc3 dir - $ patch -p1 -R < ../patch-2.6.13-rc3 # revert the 2.6.13-rc3 patch - $ patch -p1 < ../patch-2.6.13-rc5 # apply the new 2.6.13-rc5 patch + $ cd ~/linux-4.8-rc3 # change to the 4.8-rc3 dir + $ patch -p1 -R < ../patch-4.8-rc3 # revert the 4.8-rc3 patch + $ patch -p1 < ../patch-4.8-rc5 # apply the new 4.8-rc5 patch $ cd .. - $ mv linux-2.6.13-rc3 linux-2.6.13-rc5 # rename the source dir + $ mv linux-4.8-rc3 linux-4.8-rc5 # rename the source dir + + # finally let's try and move from 4.7.3 to 4.8-rc5 - # finally let's try and move from 2.6.12.3 to 2.6.13-rc5 - $ cd ~/linux-2.6.12.3 # change to the kernel source dir - $ patch -p1 -R < ../patch-2.6.12.3 # revert the 2.6.12.3 patch - $ patch -p1 < ../patch-2.6.13-rc5 # apply new 2.6.13-rc5 patch + $ cd ~/linux-4.7.3 # change to the kernel source dir + $ patch -p1 -R < ../patch-4.7.3 # revert the 4.7.3 patch + $ patch -p1 < ../patch-4.8-rc5 # apply new 4.8-rc5 patch $ cd .. - $ mv linux-2.6.12.3 linux-2.6.13-rc5 # rename the kernel source dir + $ mv linux-4.7.3 linux-4.8-rc5 # rename the kernel source dir The -git kernels @@ -415,100 +412,68 @@ Linus's tree. They are more experimental than -rc kernels since they are generated automatically without even a cursory glance to see if they are sane. --git patches are not incremental and apply either to a base 2.6.x kernel or -a base 2.6.x-rc kernel -- you can see which from their name. -A patch named 2.6.12-git1 applies to the 2.6.12 kernel source and a patch -named 2.6.13-rc3-git2 applies to the source of the 2.6.13-rc3 kernel. +-git patches are not incremental and apply either to a base 4.x kernel or +a base 4.x-rc kernel -- you can see which from their name. +A patch named 4.7-git1 applies to the 4.7 kernel source and a patch +named 4.8-rc3-git2 applies to the source of the 4.8-rc3 kernel. Here are some examples of how to apply these patches: :: - # moving from 2.6.12 to 2.6.12-git1 - $ cd ~/linux-2.6.12 # change to the kernel source dir - $ patch -p1 < ../patch-2.6.12-git1 # apply the 2.6.12-git1 patch - $ cd .. - $ mv linux-2.6.12 linux-2.6.12-git1 # rename the kernel source dir - - # moving from 2.6.12-git1 to 2.6.13-rc2-git3 - $ cd ~/linux-2.6.12-git1 # change to the kernel source dir - $ patch -p1 -R < ../patch-2.6.12-git1 # revert the 2.6.12-git1 patch - # we now have a 2.6.12 kernel - $ patch -p1 < ../patch-2.6.13-rc2 # apply the 2.6.13-rc2 patch - # the kernel is now 2.6.13-rc2 - $ patch -p1 < ../patch-2.6.13-rc2-git3 # apply the 2.6.13-rc2-git3 patch - # the kernel is now 2.6.13-rc2-git3 - $ cd .. - $ mv linux-2.6.12-git1 linux-2.6.13-rc2-git3 # rename source dir + # moving from 4.7 to 4.7-git1 + $ cd ~/linux-4.7 # change to the kernel source dir + $ patch -p1 < ../patch-4.7-git1 # apply the 4.7-git1 patch + $ cd .. + $ mv linux-4.7 linux-4.7-git1 # rename the kernel source dir -The -mm kernels -=============== + # moving from 4.7-git1 to 4.8-rc2-git3 -These are experimental kernels released by Andrew Morton. + $ cd ~/linux-4.7-git1 # change to the kernel source dir + $ patch -p1 -R < ../patch-4.7-git1 # revert the 4.7-git1 patch + # we now have a 4.7 kernel + $ patch -p1 < ../patch-4.8-rc2 # apply the 4.8-rc2 patch + # the kernel is now 4.8-rc2 + $ patch -p1 < ../patch-4.8-rc2-git3 # apply the 4.8-rc2-git3 patch + # the kernel is now 4.8-rc2-git3 + $ cd .. + $ mv linux-4.7-git1 linux-4.8-rc2-git3 # rename source dir -The -mm tree serves as a sort of proving ground for new features and other -experimental patches. -Once a patch has proved its worth in -mm for a while Andrew pushes it on to -Linus for inclusion in mainline. +The -mm patches and the linux-next tree +======================================= -Although it's encouraged that patches flow to Linus via the -mm tree, this -is not always enforced. +The -mm patches are experimental patches released by Andrew Morton. -Subsystem maintainers (or individuals) sometimes push their patches directly -to Linus, even though (or after) they have been merged and tested in -mm (or -sometimes even without prior testing in -mm). +In the past, -mm tree were used to also test subsystem patches, but this +function is now done via the +:ref:`linux-next <https://www.kernel.org/doc/man-pages/linux-next.html>` +tree. The Subsystem maintainers push their patches first to linux-next, +and, during the merge window, sends them directly to Linus. -You should generally strive to get your patches into mainline via -mm to -ensure maximum testing. +The -mm patches serve as a sort of proving ground for new features and other +experimental patches that aren't merged via a subsystem tree. +Once such patches has proved its worth in -mm for a while Andrew pushes +it on to Linus for inclusion in mainline. -This branch is in constant flux and contains many experimental features, a +The linux-next tree is daily updated, and includes the -mm patches. +Both are in constant flux and contains many experimental features, a lot of debugging patches not appropriate for mainline etc., and is the most experimental of the branches described in this document. -These kernels are not appropriate for use on systems that are supposed to be +These patches are not appropriate for use on systems that are supposed to be stable and they are more risky to run than any of the other branches (make sure you have up-to-date backups -- that goes for any experimental kernel but -even more so for -mm kernels). +even more so for -mm patches or using a Kernel from the linux-next tree). -These kernels in addition to all the other experimental patches they contain -usually also contain any changes in the mainline -git kernels available at -the time of release. +Testing of -mm patches and linux-next is greatly appreciated since the whole +point of those are to weed out regressions, crashes, data corruption bugs, +build breakage (and any other bug in general) before changes are merged into +the more stable mainline Linus tree. -Testing of -mm kernels is greatly appreciated since the whole point of the -tree is to weed out regressions, crashes, data corruption bugs, build -breakage (and any other bug in general) before changes are merged into the -more stable mainline Linus tree. - -But testers of -mm should be aware that breakage in this tree is more common -than in any other tree. - -The -mm kernels are not released on a fixed schedule, but usually a few -mm -kernels are released in between each -rc kernel (1 to 3 is common). - -The -mm kernels apply to either a base 2.6.x kernel (when no -rc kernels -have been released yet) or to a Linus -rc kernel. - -Here are some examples of applying the -mm patches: - -:: - - # moving from 2.6.12 to 2.6.12-mm1 - $ cd ~/linux-2.6.12 # change to the 2.6.12 source dir - $ patch -p1 < ../2.6.12-mm1 # apply the 2.6.12-mm1 patch - $ cd .. - $ mv linux-2.6.12 linux-2.6.12-mm1 # rename the source appropriately - - # moving from 2.6.12-mm1 to 2.6.13-rc3-mm3 - $ cd ~/linux-2.6.12-mm1 - $ patch -p1 -R < ../2.6.12-mm1 # revert the 2.6.12-mm1 patch - # we now have a 2.6.12 source - $ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch - # we now have a 2.6.13-rc3 source - $ patch -p1 < ../2.6.13-rc3-mm3 # apply the 2.6.13-rc3-mm3 patch - $ cd .. - $ mv linux-2.6.12-mm1 linux-2.6.13-rc3-mm3 # rename the source dir +But testers of -mm and linux-next should be aware that breakages are +more common than in any other tree. This concludes this list of explanations of the various kernel trees. -- 2.7.4
[toc] | [prev] | [next] | [standalone]
Page 1 of 2 [1] 2 Next page →
Back to top | Article view | linux.kernel
csiph-web