wiki:PatchQualityLevels

Clean

  • Patch name includes "create" if it creates a new file.
  • Patch name includes "rename" if its been decided that this file is named wrong.
  • Patch name includes "breakup" if it should really be two (2) or more patches.
  • Patch name includes "one-way" if it has effects even when the (CONFIG_TMIG or CONFIG_OPENMOSIX) option is turned off. This excludes the config system itself, header includes, and new files.
  • Patch name includes "one-way" if it creates a header file whos inclusion by kernel code is not dependent on the CONFIG_TMIG option.
  • Patch name includes "broken" if it is "obviously" broken. Includes, but is not limited to, code marked "STUB", "FIXME", or "XXX" or incomplete code.
  • Patch name includes "cleanup" if it:
    • contains dead or 2.4-only code.
    • has incorrect whitespace.
    • has poor variable names.
    • is missing comments in assembly.
    • is missing /* CONFIG_OPTION */ after a #endif matching a #ifdef CONFIG_OPTION
  • Patch name includes "final" if it is the last patch in a patch set to touch some file.
  • Patch has to have a commentary, either part of a larger commentary in /notes, or stand alone in a .notes file in the same directory as the patch.
  • there must be a note in the commentary if:
    • A function is only called from a few places.
    • A function fails to check passed in pointers against NULL.
    • A function fails to perform cleanup in case of errors.
    • A function uses printk() directly.
    • A function contains STUB, FIXME, or incomplete code. Don't forget to rename to patch to include "broken".
    • A function invokes OMBUG with a prefix on its output. OMBUG() adds the "[OMBUG]" prefix to it's output, the caller does not need to provide a similar prefix.
  • Classify the patch into classes (from bottom of page) in the comments in the series file and the commentary.

Patches believed to be CLEAN are placed in the linuxpmi/clean directory.

Bronze

  • Must be CLEAN.
  • Single-duty patches. That is, no patch with "breakup" in the name can be bronze.
  • (Mostly) clean patches. All the changes implied by "cleanup" in the name of the patch need to be complete. dead code should be in a separate patch file.
  • A 'first sweep' should be done to remove any FIXMEs that can be easily removed.
  • The commentary about patches should be tracked in a .notes file, next to the patch in the same directory.
    • the patch number and classes should not be present in the commentary. patch number goes in the patch's filename, classes go in the series file.
  • The 'original' commentary should be updated with anything we learn while making the 'Bronze' commentary.
  • In-code comments are correct, that is they reflect the current patch. Rewrite as needed.
  • "#ifdef CONFIG_OPTION" has a matching "#endif /* CONFIG_OPTION */".
  • OMBUG() text should be unique. You should be able to grep the source for the message and discover the line that reported the error.

Patches believed to be BRONZE MUST be placed in the linuxpmi/bronze directory, and MUST be added to the series file.

Silver

  • Must be BRONZE.
  • All FIXMEs are removed.
  • The 'original' commentary should be updated with anything we learn while making the 'Silver' commentary. Bronze commentaries do not require updating.
  • Assembly code has a high comment-to-code ratio. Assembly is becoming a lost art and needs more documentation than other code.
  • All functions have kdoc.
  • Use EXPORT_SYMBOL_GPL instead of EXPORT_SYMBOL after verifying GPL license in header.
  • Replace printk() calls with appropriate OM_DEBUG macro or remove entirely.
  • Patches are sequenced to maximize locality. E.g. patches to the same file will be as close to one another as possible.

Patches believed to be SILVER are placed in the linuxpmi/silver directory, and MAY be added to the series file.

Gold

  • Must be SILVER.
  • All newly created files will have a header describing it's purpose and why the functions defined in the file are there and not somewhere else.
  • kcom.h is included before prototype.h
  • If code is removed by a later patch, change both patches to remove the code in the earlier one only.
  • Header dependencies commented. each header we add should have a list of what its including in the comments above it.
  • All functions comment what context they are called in, specifically any assumption about the caller and kernel state they make.
  • All functions comment whether they are preemptable or not. in an atomic state? calling schedule?
  • Each error condition should print an error message. Any function that can return error codes should perform minimalist error recovery.
  • All messages are printed though macros (e.g. OMDEBUG, OMBUG, etc.) instead of direct invocation.
  • No resource leaks.
  • Variables will follow kernel naming conventions.
  • Function that manipulate lists will use proper spinlocking.
  • mm->realusers is manipulated atomically.
  • All defines added to header will be commented.
  • Patches will comply with Kernel Precedents, Security Rules, and Userspace Interfacing Rules.
  • Kernel threads should not directly lock spinlocks, but employ helper functions to do the locking.
  • If the CONFIG_OPENMOSIX is turned off, the patches do nothing.

Patches believed to be GOLD are placed in the linuxpmi/gold directory.

Platinum

  • Must be GOLD.
  • Patches are ordered so that dependencies are applied before the patches that depend on them.
  • Before a header is included, there's a comment explaining what variables/functions/macros are required from that header.
  • Merge patches that modify the same file into a single patch, without violating the single-duty patch guideline above.
  • Make sure the correct file is being patched.
  • Locate and preferably merge with it's "twin", the patch that handles the other (local vs. remote) side.
  • Locate and preferable merge with other patches that are closely related and preforming the same duty.
  • If a function performs argument checking or acquires kernel resources and does "real" work, break that function along those lines.
  • Drop dead code.

Patches believed to be PLAT are placed in the linuxpmi/plat directory.

Classes

Class Description
ARCH_X86_32 code only used on the i386 architecture.
ARCH_X86_64 code only used on the AMD64 architecture.
ARCH_X86 code used by both the i386 and the AMD64 architecture, and no others.
ARCH_PPC code only used on the PPC architecture.
config part of the Kconfig system, that the kernel uses to build.
local adds functionality that is only accessible locally, on the "home" node.
tmig_ldt_stub code for reporting an error if we try to receive a process with an LDT on the home node.
tmig_local required to allow a task from another node to run on this node.
tmig_int required to abstract processes into serializeable components.
tmig_remote required to allow a task to execute on another node, or if the code in question is required to move a task to another node.
tmig_remotefile required to allow a task executing on another node remote file access
tmig_remotedentry required to allow a task executing on another node remote dentry access
tmig_remotemem required to allow a task executing on another node remote memory access
tmig_socket socket abstraction code
tmig_syscall part of the system call redirection system
tmig_task PMI specific wrappers of the process handling system
tmig_task_int code for handling PMI specific processes
Last modified 8 years ago Last modified on Sep 26, 2013, 8:39:13 PM