change system file

hc

2024-10-09 244b2c5ca8b14627e4a17755e5922221e121c771

 kernel/Documentation/process/howto.rst
..
..
@@ -1,3 +1,5 @@
1
+.. _process_howto:
2
+
1
3
 HOWTO do Linux kernel development
2
4
 =================================
3
5
 
..
..
@@ -57,12 +59,13 @@
57
59
 Legal Issues
58
60
 ------------
59
61
 
60
-The Linux kernel source code is released under the GPL.  Please see the
61
-file, COPYING, in the main directory of the source tree, for details on
62
-the license.  If you have further questions about the license, please
63
-contact a lawyer, and do not ask on the Linux kernel mailing list.  The
64
-people on the mailing lists are not lawyers, and you should not rely on
65
-their statements on legal matters.
62
+The Linux kernel source code is released under the GPL.  Please see the file
63
+COPYING in the main directory of the source tree. The Linux kernel licensing
64
+rules and how to use `SPDX <https://spdx.org/>`_ identifiers in source code are
65
+described in :ref:`Documentation/process/license-rules.rst <kernel_licensing>`.
66
+If you have further questions about the license, please contact a lawyer, and do
67
+not ask on the Linux kernel mailing list.  The people on the mailing lists are
68
+not lawyers, and you should not rely on their statements on legal matters.
66
69
 
67
70
 For common questions and answers about the GPL, please see:
68
71
 
..
..
@@ -120,7 +123,7 @@
120
123
 		https://www.ozlabs.org/~akpm/stuff/tpp.txt
121
124
 
122
125
 	"Linux kernel patch submission format"
123
-		http://linux.yyz.us/patch-format.html
126
+		https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html
124
127
 
125
128
   :ref:`Documentation/process/stable-api-nonsense.rst <stable_api_nonsense>`
126
129
     This file describes the rationale behind the conscious decision to
..
..
@@ -222,7 +225,7 @@
222
225
 self-referential, indexed webpage format. An excellent up-to-date
223
226
 repository of the kernel code may be found at:
224
227
 
225
-	http://lxr.free-electrons.com/
228
+	https://elixir.bootlin.com/
226
229
 
227
230
 
228
231
 The development process
..
..
@@ -232,23 +235,21 @@
232
235
 main kernel "branches" and lots of different subsystem-specific kernel
233
236
 branches.  These different branches are:
234
237
 
235
-  - main 4.x kernel tree
236
-  - 4.x.y -stable kernel tree
237
-  - 4.x -git kernel patches
238
-  - subsystem specific kernel trees and patches
239
-  - the 4.x -next kernel tree for integration tests
238
+  - Linus's mainline tree
239
+  - Various stable trees with multiple major numbers
240
+  - Subsystem-specific trees
241
+  - linux-next integration testing tree
240
242
 
241
-4.x kernel tree
242
-~~~~~~~~~~~~~~~
243
+Mainline tree
244
+~~~~~~~~~~~~~
243
245
 
244
-4.x kernels are maintained by Linus Torvalds, and can be found on
245
-https://kernel.org in the pub/linux/kernel/v4.x/ directory.  Its development
246
-process is as follows:
246
+The mainline tree is maintained by Linus Torvalds, and can be found at
247
+https://kernel.org or in the repo.  Its development process is as follows:
247
248
 
248
-  - As soon as a new kernel is released a two weeks window is open,
249
+  - As soon as a new kernel is released a two week window is open,
249
250
     during this period of time maintainers can submit big diffs to
250
251
     Linus, usually the patches that have already been included in the
251
-    -next kernel for a few weeks.  The preferred way to submit big changes
252
+    linux-next for a few weeks.  The preferred way to submit big changes
252
253
     is using git (the kernel's source management tool, more information
253
254
     can be found at https://git-scm.com/) but plain patches are also just
254
255
     fine.
..
..
@@ -275,41 +276,31 @@
275
276
 	released according to perceived bug status, not according to a
276
277
 	preconceived timeline."*
277
278
 
278
-4.x.y -stable kernel tree
279
-~~~~~~~~~~~~~~~~~~~~~~~~~
279
+Various stable trees with multiple major numbers
280
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
280
281
 
281
282
 Kernels with 3-part versions are -stable kernels. They contain
282
283
 relatively small and critical fixes for security problems or significant
283
-regressions discovered in a given 4.x kernel.
284
+regressions discovered in a given major mainline release. Each release
285
+in a major stable series increments the third part of the version
286
+number, keeping the first two parts the same.
284
287
 
285
288
 This is the recommended branch for users who want the most recent stable
286
289
 kernel and are not interested in helping test development/experimental
287
290
 versions.
288
291
 
289
-If no 4.x.y kernel is available, then the highest numbered 4.x
290
-kernel is the current stable kernel.
291
-
292
-4.x.y are maintained by the "stable" team <stable@vger.kernel.org>, and
292
+Stable trees are maintained by the "stable" team <stable@vger.kernel.org>, and
293
293
 are released as needs dictate.  The normal release period is approximately
294
294
 two weeks, but it can be longer if there are no pressing problems.  A
295
295
 security-related problem, instead, can cause a release to happen almost
296
296
 instantly.
297
297
 
298
-The file Documentation/process/stable-kernel-rules.rst in the kernel tree
299
-documents what kinds of changes are acceptable for the -stable tree, and
300
-how the release process works.
298
+The file :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rules>`
299
+in the kernel tree documents what kinds of changes are acceptable for
300
+the -stable tree, and how the release process works.
301
301
 
302
-4.x -git patches
303
-~~~~~~~~~~~~~~~~
304
-
305
-These are daily snapshots of Linus' kernel tree which are managed in a
306
-git repository (hence the name.) These patches are usually released
307
-daily and represent the current state of Linus' tree.  They are more
308
-experimental than -rc kernels since they are generated automatically
309
-without even a cursory glance to see if they are sane.
310
-
311
-Subsystem Specific kernel trees and patches
312
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
302
+Subsystem-specific trees
303
+~~~~~~~~~~~~~~~~~~~~~~~~
313
304
 
314
305
 The maintainers of the various kernel subsystems --- and also many
315
306
 kernel subsystem developers --- expose their current state of
..
..
@@ -333,19 +324,19 @@
333
324
 accepted, or rejected.  Most of these patchwork sites are listed at
334
325
 https://patchwork.kernel.org/.
335
326
 
336
-4.x -next kernel tree for integration tests
337
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
327
+linux-next integration testing tree
328
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
338
329
 
339
-Before updates from subsystem trees are merged into the mainline 4.x
340
-tree, they need to be integration-tested.  For this purpose, a special
330
+Before updates from subsystem trees are merged into the mainline tree,
331
+they need to be integration-tested.  For this purpose, a special
341
332
 testing repository exists into which virtually all subsystem trees are
342
333
 pulled on an almost daily basis:
343
334
 
344
335
 	https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
345
336
 
346
-This way, the -next kernel gives a summary outlook onto what will be
337
+This way, the linux-next gives a summary outlook onto what will be
347
338
 expected to go into the mainline kernel at the next merge period.
348
-Adventurous testers are very welcome to runtime-test the -next kernel.
339
+Adventurous testers are very welcome to runtime-test the linux-next.
349
340
 
350
341
 
351
342
 Bug Reporting
..
..
@@ -357,7 +348,8 @@
357
348
 
358
349
 	https://bugzilla.kernel.org/page.cgi?id=faq.html
359
350
 
360
-The file admin-guide/reporting-bugs.rst in the main kernel source directory has a good
351
+The file :ref:`admin-guide/reporting-bugs.rst <reportingbugs>`
352
+in the main kernel source directory has a good
361
353
 template for how to report a possible kernel bug, and details what kind
362
354
 of information is needed by the kernel developers to help track down the
363
355
 problem.
..
..
@@ -368,10 +360,10 @@
368
360
 
369
361
 One of the best ways to put into practice your hacking skills is by fixing
370
362
 bugs reported by other people. Not only you will help to make the kernel
371
-more stable, you'll learn to fix real world problems and you will improve
372
-your skills, and other developers will be aware of your presence. Fixing
373
-bugs is one of the best ways to get merits among other developers, because
374
-not many people like wasting time fixing other people's bugs.
363
+more stable, but you'll also learn to fix real world problems and you will
364
+improve your skills, and other developers will be aware of your presence.
365
+Fixing bugs is one of the best ways to get merits among other developers,
366
+because not many people like wasting time fixing other people's bugs.
375
367
 
376
368
 To work in the already reported bug reports, go to https://bugzilla.kernel.org.
377
369
 
..
..
@@ -423,7 +415,7 @@
423
415
 writing at the top of the mail.
424
416
 
425
417
 If you add patches to your mail, make sure they are plain readable text
426
-as stated in Documentation/process/submitting-patches.rst.
418
+as stated in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
427
419
 Kernel developers don't want to deal with
428
420
 attachments or compressed patches; they may want to comment on
429
421
 individual lines of your patch, which works only that way. Make sure you
..
..
@@ -605,7 +597,7 @@
605
597
 ChangeLog section of the document:
606
598
 
607
599
   "The Perfect Patch"
608
-      http://www.ozlabs.org/~akpm/stuff/tpp.txt
600
+      https://www.ozlabs.org/~akpm/stuff/tpp.txt
609
601
 
610
602
 
611
603
 All of these things are sometimes very hard to do. It can take years to