docs-rst: add documents to development-process

Add several documents to the development-process ReST book.

As we don't want renames, use symlinks instead, keeping those
documents on their original place.

Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

1 files changed, 0 insertions, 465 deletions

diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt
deleted file mode 100644
index 3395da13d415..000000000000
--- a/Documentation/applying-patches.txt
+++ /dev/null
@@ -1,465 +0,0 @@
-.. _applying_patches:
-
-Applying Patches To The Linux Kernel
-++++++++++++++++++++++++++++++++++++
-
-Original by:
-	Jesper Juhl, August 2005
-
-Last update:
-	2016-09-14
-
-
-A frequently asked question on the Linux Kernel Mailing List is how to apply
-a patch to the kernel or, more specifically, what base kernel a patch for
-one of the many trees/branches should be applied to. Hopefully this document
-will explain this to you.
-
-In addition to explaining how to apply and revert patches, a brief
-description of the different kernel trees (and examples of how to apply
-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``
-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
-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
-(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
-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).
-
-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
-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
-know of more than one way to use patch, then you can stop reading this
-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 xz and you don't want to
-uncompress it before applying it, then you can feed it to patch like this
-instead::
-
-	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 xz on the file -- like this::
-
-	gunzip patch-x.y.z.gz
-	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.
-
-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``
-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
-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.
-
-If patch encounters something that doesn't look quite right it has two
-options. It can either refuse to apply the changes and abort or it can try
-to find a way to make the patch apply with a few minor changes.
-
-One example of something that's not 'quite right' that patch will attempt to
-fix up is if all the context matches, the lines being changed match, but the
-line numbers are different. This can happen, for example, if the patch makes
-a change in the middle of the file but for some reasons a few lines have
-been added or removed near the beginning of the file. In that case
-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**.
-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
-read this file to see exactly what change couldn't be applied, so you can
-go fix it up by hand if you wish.
-
-If you don't have any third-party patches applied to your kernel source, but
-only patches from kernel.org and you apply the patches in the correct order,
-and have made no modifications yourself to the source files, then you should
-never see a fuzz or reject message from patch. If you do see such messages
-anyway, then there's a high risk that either your local source tree or the
-patch file is corrupted in some way. In that case you should probably try
-re-downloading the patch and if things are still not OK then you'd be advised
-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
-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
-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
-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
-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
-content that couldn't be changed.
-
-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.
-
-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
-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
-two lines that had been split.
-
-As I already mentioned above, these errors should never happen if you apply
-a patch from kernel.org to the correct version of an unmodified source tree.
-So if you get these errors with kernel.org patches then you should probably
-assume that either your patch file or your tree is broken and I'd advise you
-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.
-
-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 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 4.7.2 to 4.7.3 in a single step::
-
-	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.
-
-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
-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
-the patch contains a given regular expression.
-
-
-Where can I download the patches?
-=================================
-
-The patches are available at http://kernel.org/
-Most recent patches are linked from the front page, but they also have
-specific homes.
-
-The 4.x.y (-stable) and 4.x patches live at
-
-	ftp://ftp.kernel.org/pub/linux/kernel/v4.x/
-
-The -rc patches live at
-
-	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
-likely geographically closer to you, resulting in faster downloads for you,
-less bandwidth used globally and less load on the main kernel.org servers --
-these are good things, so do use mirrors when possible.
-
-
-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 4.x base
-kernel is released, a patch is made available that is a delta between the
-previous 4.x kernel and the new one.
-
-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 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-4.6 linux-4.7	# rename source dir
-
-	# moving from 4.6.1 to 4.7
-
-	$ 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-4.6.1 linux-4.7	# rename source dir
-
-
-The 4.x.y kernels
-=================
-
-Kernels with 3-digit versions are -stable kernels. They contain small(ish)
-critical fixes for security problems or significant regressions discovered
-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 4.x.y kernel is available, then the highest numbered 4.x kernel is
-the current stable kernel.
-
-.. 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/v4.x/incr/
-
-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 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-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-4.7.2 linux-4.7.3	# rename the kernel source dir
-
-The -rc kernels
-===============
-
-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.
-
-These kernels are not stable and you should expect occasional breakage if
-you intend to run them. This is however the most stable of the main
-development branches and is also what will eventually turn into the next
-stable kernel, so it is important that it be tested by as many people as
-possible.
-
-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 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, 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 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-4.7 linux-4.8-rc3		# rename the source dir
-
-	# now let's move from 4.8-rc3 to 4.8-rc5
-
-	$ 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-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
-
-	$ 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-4.7.3 linux-4.8-rc5		# rename the kernel source dir
-
-
-The -git kernels
-================
-
-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
-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 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 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
-
-	# moving from 4.7-git1 to 4.8-rc2-git3
-
-	$ 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 patches and the linux-next tree
-=======================================
-
-The -mm patches are experimental patches released by Andrew Morton.
-
-In the past, -mm tree were used to also test subsystem patches, but this
-function is now done via the
-`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.
-
-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.
-
-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 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 patches or using a Kernel from the linux-next tree).
-
-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.
-
-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.
-I hope you are now clear on how to apply the various patches and help testing
-the kernel.
-
-Thank you's to Randy Dunlap, Rolf Eike Beer, Linus Torvalds, Bodo Eggert,
-Johannes Stezenbach, Grant Coady, Pavel Machek and others that I may have
-forgotten for their reviews and contributions to this document.
-