Commit 5969fbf3 authored by Lukas Bulwahn's avatar Lukas Bulwahn Committed by Jonathan Corbet
Browse files

docs: submit-checklist: structure by category 



While going through the submit checklist, the list order seemed rather
random, probably just by historical coincidences of always adding yet the
next point someone thought of at the end of the list.

Structure and order them by the category of such activity,
reviewing, documenting, checking with tools, building and testing.

As the diff of the reordering is large:
Review code now includes previous points 1, 5 and 22.
Review Kconfig includes previous 6, 7 and 8.
Documenting includes previous 11, 15, 16, 17, 18 and 23.
Checking with tools includes previous 5, 9 and 10.
Building includes previous 2, 3, 20 and 24.
Testing includes previous 12, 13, 14, 19 and 21.

Previous point 4 (compile for ppc64) was merged into point 3 (build for
many architectures), as it was just a further note to cross-compiling.

Previous point 5 was split into one in review and one in checking
to have every previous point in the right category.
Point 11 was shortened, as building documentation is mentioned already
in Build your code, 1d.

A note that was presented visually much too aggressive in the HTML view was
turned into a simple "Note that..." sentence in the enumeration.

The recommendation to test with the -mm patchset (previous 21, now
testing, point 5) was updated to the current state of affairs to test with
a recent tag of linux-next.

Note that the previous first point still remains the first list even after
reordering. Randy confirmed that it was important to Stephen Rothwell to
keep 'include what you use' to be the first in the list.

While at it, replace the reference to the obsolete CONFIG_DEBUG_SLAB with
CONFIG_SLUB_DEBUG.

Reviewed-by: default avatarRandy Dunlap <rdunlap@infradead.org>
Tested-by: default avatarRandy Dunlap <rdunlap@infradead.org>
Signed-off-by: default avatarLukas Bulwahn <lukas.bulwahn@gmail.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Message-ID: <20240229030743.9125-2-lukas.bulwahn@gmail.com>
parent 78129672

Documentation/process/submit-checklist.rst

+84 −73
Original line number Diff line number Diff line
@@ -11,110 +11,121 @@ These are all above and beyond the documentation that is provided in 
and elsewhere regarding submitting Linux kernel patches.





*Review your code:*



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:



  a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and

     ``=n``.  No ``gcc`` warnings/errors, no linker warnings/errors.



  b) Passes ``allnoconfig``, ``allmodconfig``



  c) Builds successfully when using ``O=builddir``



  d) Any Documentation/ changes build successfully without new warnings/errors.

     Use ``make htmldocs`` or ``make pdfdocs`` to check the build and

     fix any issues.

2) Check your patch for general style as detailed in

   :ref:`Documentation/process/coding-style.rst <codingstyle>`.



3) Builds on multiple CPU architectures by using local cross-compile tools

   or some other build farm.

3) 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.



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

   :ref:`Documentation/process/coding-style.rst <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.

*Review Kconfig changes:*



6) Any new or modified ``CONFIG`` options do not muck up the config menu and

1) Any new or modified ``CONFIG`` options do not muck up the config menu and

   default to off unless they meet the exception criteria documented in

   ``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value.



7) All new ``Kconfig`` options have help text.

2) All new ``Kconfig`` options have help text.



8) Has been carefully reviewed with respect to relevant ``Kconfig``

   combinations.  This is very hard to get right with testing -- brainpower

3) 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.

*Provide documentation:*



10) Use ``make checkstack`` and fix any problems that it finds.

1) Include :ref:`kernel-doc <kernel_doc>` to document global kernel APIs.

   (Not required for static functions, but OK there also.)



    .. note::

2) All new ``/proc`` entries are documented under ``Documentation/``



       ``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.

3) All new kernel boot parameters are documented in

   ``Documentation/admin-guide/kernel-parameters.rst``.



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.

4) All new module parameters are documented with ``MODULE_PARM_DESC()``



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.

5) 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.



13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and

    ``CONFIG_PREEMPT.``

6) If any ioctl's are added by the patch, then also update

   ``Documentation/userspace-api/ioctl/ioctl-number.rst``.



14) All codepaths have been exercised with all lockdep features enabled.



15) All new ``/proc`` entries are documented under ``Documentation/``

*Check your code with tools:*



16) All new kernel boot parameters are documented in

    ``Documentation/admin-guide/kernel-parameters.rst``.

1) 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.



17) All new module parameters are documented with ``MODULE_PARM_DESC()``

2) Check cleanly with sparse.



18) 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.

3) Use ``make checkstack`` and fix any problems that it finds.

   Note that ``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.



19) 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.

*Build your code:*



20) Newly-added code has been compiled with ``gcc -W`` (use

    ``make KCFLAGS=-W``).  This will generate lots of noise, but is good

    for finding bugs like "warning: comparison between signed and unsigned".

1) Builds cleanly:



  a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and

     ``=n``.  No ``gcc`` warnings/errors, no linker warnings/errors.



21) 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.

  b) Passes ``allnoconfig``, ``allmodconfig``



22) 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.

  c) Builds successfully when using ``O=builddir``



23) If any ioctl's are added by the patch, then also update

    ``Documentation/userspace-api/ioctl/ioctl-number.rst``.

  d) Any Documentation/ changes build successfully without new warnings/errors.

     Use ``make htmldocs`` or ``make pdfdocs`` to check the build and

     fix any issues.



24) If your modified source code depends on or uses any of the kernel

2) Builds on multiple CPU architectures by using local cross-compile tools

   or some other build farm. Note that ppc64 is a good architecture for

   cross-compilation checking because it tends to use ``unsigned long`` for

   64-bit quantities.



3) Newly-added code has been compiled with ``gcc -W`` (use

   ``make KCFLAGS=-W``).  This will generate lots of noise, but is good

   for finding bugs like "warning: comparison between signed and unsigned".



4) 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_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``).





*Test your code:*



1) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``,

   ``CONFIG_SLUB_DEBUG``, ``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.



2) Has been build- and runtime tested with and without ``CONFIG_SMP`` and

   ``CONFIG_PREEMPT.``



3) All codepaths have been exercised with all lockdep features enabled.



4) 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.



5) Tested with the most recent tag of linux-next to make sure that it still

   works with all of the other queued patches and various changes in the VM,

   VFS, and other subsystems.