Releasing to Linux kernel using patches and emails

From OMAPpedia

(Difference between revisions)
Jump to: navigation, search
m (Reverted edits by BelindaBride (talk) to last revision by BenBailey)
m
Line 34: Line 34:
If you want to bypass the check (e.g. if the failure is intended), use the -n flag for commit to ignore the checks.  Just be sure that you still resolve any failures that were correct, and there really wasn’t a better proper way to write your code without checkpatch errors.  Now there is a whole set of discussion about the 80 character limit that sometime forces less understandable code (you can read about the pros/cons [http://lkml.org/lkml/2009/12/15/490] and find a patch [http://lkml.org/lkml/2009/12/15/508] to checkpatch to make this optional)  BTW, Linus prefers [http://lkml.org/lkml/2009/12/17/208] in many cases to ignore the 80-char-limit warnings.
If you want to bypass the check (e.g. if the failure is intended), use the -n flag for commit to ignore the checks.  Just be sure that you still resolve any failures that were correct, and there really wasn’t a better proper way to write your code without checkpatch errors.  Now there is a whole set of discussion about the 80 character limit that sometime forces less understandable code (you can read about the pros/cons [http://lkml.org/lkml/2009/12/15/490] and find a patch [http://lkml.org/lkml/2009/12/15/508] to checkpatch to make this optional)  BTW, Linus prefers [http://lkml.org/lkml/2009/12/17/208] in many cases to ignore the 80-char-limit warnings.
-
But wait!  You can do even more.  Since you are already modifying files, why not run checkpatch on the whole file (and not just on the lines you are changing)?  To see if there are any already existing checkpatch errors in the files that you modified, set up these two bash aliases that will run checkpatch on the whole files that are about to be committed (just run ‘chkp’):
+
But wait!  You can do even more.  Since you are already modifying files, why not run checkpatch on the whole file (and not just on the <span class="plainlinks">[http://www.proposable.com <span style="color:black;font-weight:normal; text-decoration:none!important; background:none!important; text-decoration:none;">proposal software</span>] lines you are changing)?  To see if there are any already existing checkpatch errors in the files that you modified, set up these two bash aliases that will run checkpatch on the whole files that are about to be committed (just run ‘chkp’):
  alias gitd='git rev-parse --show-cdup'
  alias gitd='git rev-parse --show-cdup'

Revision as of 19:52, 29 July 2011

Contents

How to submit patches

OMAP platform linux mailing list linux-omap@vger.kernel.org can be used for patch submissions and discussions. Click here to subscribe to the list or/and get more information.

We recommend the use of git-format-patch and git-send-email to generate and submit patches.

More detailed information...


Introduction: This page gathers some useful information for releasing (or proposing for release) some code into the Linux kernel.

Note that for TI folks, a presentation is available here. Also look at here

Writing clean code

Linux Documentation

The following Linux documentation must be read before anything:

Checking tools

checkpatch.pl

scripts/checkpatch.pl is a script that facilitates better kernel code, and can be used to check many coding style rules.

This script applies on patch files by default, but can also process complete source files using the -f option. To get a list of options, run

checkpatch.pl -h

The attached script (File:Run-checkpatch.tar.gz) is an example used to call easily the checkpatch.pl script diamond solitaire engagement rings on a series of files (to run periodically during your development for example).

You can also set up GIT to run checkpatch automatically before each commit (and reject it on failure). You need to link building copy the attached script (File:Pre-commit.tar.gz) into your GIT repository under $GIT_DIR/hooks directory (normally as .git/hooks/pre-commit). This script also runs git diff --check, plus as an added benefit it sets file permissions for common files (c, h, makefile, README) to 0644, and executables (directories, shell scripts) to 0755. This is a common issue when editing files in Windows.

If you want to bypass the check (e.g. if the failure is intended), use the -n flag for commit to ignore the checks. Just be sure that you still resolve any failures that were correct, and there really wasn’t a better proper way to write your code without checkpatch errors. Now there is a whole set of discussion about the 80 character limit that sometime forces less understandable code (you can read about the pros/cons [1] and find a patch [2] to checkpatch to make this optional) BTW, Linus prefers [3] in many cases to ignore the 80-char-limit warnings.

But wait! You can do even more. Since you are already modifying files, why not run checkpatch on the whole file (and not just on the proposal software lines you are changing)? To see if there are any already existing checkpatch errors in the files that you modified, set up these two bash aliases that will run checkpatch on the whole files that are about to be committed (just run ‘chkp’):

alias gitd='git rev-parse --show-cdup'
alias chkp='`gitd`scripts/checkpatch.pl -f `git diff --name-only HEAD | awk -v i=$(gitd) "{print i\\$0}"`'

Note: it is always recommended to run checkpatch.pl with --strict to get better warnings.

sparse

sparse is a static code analysis tool that shall be run on all source files heading a kernel release.

Luckily, sparse is integrated into the kernel build-system and can be easily invoked.

Example for a single file:

make C=2 drivers/hsi/hsi.o

Example for a complete folder with some filtering on some error messages:

make C=2 drivers/hsi/ 2>&1 | grep -v __cold__

GIT patch creation

Useful links:

Subject: [PATCH $version $n/$total] $subsystem: one-line summary

(keep the one-line summary < 50 chars)

GIT setup

Before you do commits to generate patches, ensure you have the right email ID and name configured for git to use.

% git config --global user.name "My Name"
% git config --global user.email "user@domain.com"

Alternatively, edit ~/.gitconfig

 [user]
   name = My Name
   email = user@domain.com

Also, in order to have a nice thread format:

% git config sendemail.chainreplyto false

if you modify files with windows, samba may change the permission mode of the file. if you want git not to take this into account you can use:

% git config core.filemode false


GIT commands

Patch files are generated from commits (1 patch per commit).

A typical command for generating patch files looks like this:

git format-patch  master~4..master~2 --cover-letter --numbered -s -o patch-folder/

=> This will generate the diff patches between master~4 and master~2 version (2 patches), plus add some diff information (--cover-letter), add the patch number vending machines in the subject (1/2, 2/2), and output the patch files to the 'patch-folder' folder. Note that a patch 0/0 file will also be created to host a summary of the changes.

scripts/checkpatch.pl can be run on the files in the patch-folder to check (last chance!) that the format is correct.

The patch files must be hand-edited to replace some fields.

GIT useful helper script

Sending patch emails with GIT

Sending emails can be done through any email client, but it's much easier to do it from git, and it avoids any garbage generated by the email client.

This is supported by git-send-mail module. It can be installed this way:

sudo apt-get install git-email

To follow-up on the above example, here is how to send the previously generated patches:

git send-email --from "My Name <me@myaddress.com>" --envelope-sender "My Name <me@myaddress.com>" --to somelist@somewhere.com patch-folder

--from ensures that the email comes from the right person, the --envelope-sender is usually needed for many opensource mailing lists to accept emails(emails bounce/never get distributed otherwise)

NOTE: using an alias is a better option when using this every time:

alias gsend='git send-email --from "My Name <me@myaddress.com>" --envelope-sender "My Name <me@myaddress.com>" '

Useful links

setting-up email forwarding

Documentation/email-clients.txt

GIT send-emails tricks (email threading, cc-cmd, ...)

Note on git commit comments

You must have seen that the git comments are used to populate the patch file header in the format-patch phase:

... but pay attention that the comment will be integrated to the email sent by git-send-email only if there is a blank (empty) line between the 1st line comment (used as subject) and the rest of the comment lines.

Example of a commit comment:

This is the 1st line, that will be used as patch subject


This is the 3rd line of comment (intentionally left 2nd line empty so that this part of comments are integrated into the emails).

Suggestions for Commit messages: Commit messages are informative information for reviewers and maintainers. Remember: the patch once submitted has a long way to go through various maintainers and mailing list members before reaching kernel.org. You need to put yourself in the shoes of maintainers and reviewers who may or may not be familiar with all the internal details after a few months of time, but still need to understand the motivation for a change.


A commit message is structured:

  1. What is the problem this patch is trying to solve - e.g. why is the existing code not correct
  2. The strategy by which this patch attempts to solve the issue - remember people can read code, so giving "introducing variable x solves issue" - instead describe the gist of how you solved the issue
  3. What is the impact of the change when there are dependent modules - e.g. if you change an function entry which may be used by others modules you may want to document it here, rather than get the other person discover it when he/she builds their module
  4. Optionally, you may state what testing you may have done to ensure the issue is solved.

Some of the above points might be self evident and could be skipped.. but it is usually a good idea to be descriptive enough.Again, it is a fine balance between informative and going overboard, community members and maintainers are usually kind enough to help guide a patch in.

Read this and this for more detailed rationale.

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox