HOWTO: Create and submit your first Linux kernel patch using GIT

Orgion:

http://www.cnblogs.com/linuxkernel/archive/2011/03/27/1997001.html

=======================================Added by Joseph ==============================

Maybe helpful:

1. Check the current branch

 # git branch

2. Create a new local branch

#git branch eagle_new

3. check to the new local branch you created

#git checkout eagle_new

4. Configure

  list the configure info

  #git config -l

set your user name and emali

  #git config --global user.name "Yang Honggang (Joseph)"
  #git config --global user.email  eagle.rtlinux@gmail.com

5. see the log

 #git log

6.  recover to a commit point // !!!your local modification will lost

 # git reset  --hard commitID

======================================================================

这个文章用自己第一次提交patch的经历详细介绍了用git提交patch的步骤，值得学习。

From : http://linux.koolsolutions.com/2011/02/26/howto-create-and-submit-your-first-linux-kernel-patch/

 

After working with Linux (mostly as an advanced user) for years, I decided to post my firstLinux kernel patch(although trivial but hey you need to start somewhere!) and I wasthrilled when it first got accepted by the Subsystem maintainer andthen ultimately it trickled into mainline kernel.

What follows is a step-by-step guide on how to submit a Linux kernel patchand hope that it gets accepted into the mainline kernel. This HOW-TO isbased on an actual patch that I wrote and submitted and which gotaccepted into mainline kernel yesterday. The guide mostly highlightsthe mechanics of sending patches and not necessarily technical designaspects of Linux kernel.

Step 1: Install Git Tools

Thefirst thing we need to do is to make sure that we have necessary toolsto create and submit our Linux kernel patch. I am using my Debian Lennysystem for this HOW-TO.

# apt-get update
# apt-get install git git-email gitk

Additionally it is a good idea to configure some few parameters that Git will use when it generates your patch:

# git config --add user.name "Kushal Koolwal"
# git config --add user.email "kushalkoolwal@gmail.com"

Step 2: Clone Linus’ Git Tree

Thenext thing you may want to do is to clone Linus’s Git tree preferablyon your Linux machine. Make sure you have enough space (at least 2GB)before you clone the tree. At the time of this writing the total sizeof the tree was around 950+ MB.

debian:~# cd /usr/src/
debian:/usr/src/# git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6 mylinux-2.6

Nowwait for 30 minutes or so, depending on your Internet connection speed,before the entire tree gets downloaded into your directory mylinux-2.6(directory will be created automatically since you have specified inthe command). Any patchwork should always be done against this tree tomake sure that your changes might not conflict with changes made byother developers.

debian:/usr/src/# cd mylinux-2.6
debian:/usr/src/mylinux-2.6# ls
archCOPYING  crypto drivers fs init  Kbuild   kernel  MAINTAINERS  mm  README samples  security  tools  virt block  CREDITS  Documentation firmware  include  ipc   Kconfig  lib  Makefile net  REPORTING-BUGS scripts  sound     usr
debian:/usr/src/mylinux-2.6#

From here onwards all the work will be done in /usr/src/mylinux-2.6 directory.

Step 3: Now create a local branch to make your changes

By default when you clone the Git tree you are in the master branch.

# git branch
* master
#

The * above indicates your current branch.

Let’s create a new branch my MenlowRebootFix in which we will do our code changes:

# git branch MenlowRebootFix

Then you need to checkout the above newly created branch:

# git checkout MenlowRebootFix

Confirm that you are in the above branch:

# git branch
*MenlowRebootFix
master
#

Step 4: Make your changes

Now I am going to make changes to the arch/x86/kernel/reboot.c file. After you made your changes to the file and saved it give the following command:

# git commit -a

The above command will open a text editor in the same window on your terminal screen (my default text editor isnano) like this:

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch Test1
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       modified:   arch/x86/kernel/reboot.c
#

Nowwe will enter our commit log message. Be very careful what you type inthe log message because these messages will become part of Linux Gittree commit log and people will be searching your commit based on thesemessages. Here is what I typed in and here is what my final editorwindow looked it:

x86: Fix reboot problem on VersaLogic Menlow boards
VersaLogic Menlow based boards hang on reboot unless reboot=bios is used. Add quirk to reboot through the BIOS.
Tested on at least four boards.
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
# On branch Test1
# Changes to be committed:
#   (use "git reset HEAD <file>..." to unstage)
#
#       modified:   arch/x86/kernel/reboot.c
#

Nowthe text in blue color will become your main subject line of the patchthat you will email and will also become the identifier in the Gitcommit log.

Note: It is very importantthat you first type the name of the subsystem to which your patchbelongs to. In my case since I am modifying the reboot.c file in thex86 architecture directory, I begin by subject line withx86:.

Afterthat you need to leave one empty line. and then type a briefdescription about your change (in maroon color) which will become thechangelog of the Git commit log.

Do not worry about the text in orange color that begins with #. Those will be ignored by Git commit.

Note: Ifyou don’t leave one empty line between your subject and description ,your description will become part of the subject line and it will beall mess.

Step 5: Generate your patch

Sonow you have commit your patch in your local Git repository, it is timeto generate the patch that we will email to the respective maintainersand mailing lists. To generate patch simply give the following command:

# git format-patch -s -n master..MenlowRebootFix

This should create a file 0001-x86-Fix-reboot-problem-on-VersaLogic-Menlow-boards.patch in your current directory whose content will be:

From 04056e508c996b023857f8076da7fb54096d10e9 Mon Sep 17 00:00:00 2001
From: Kushal Koolwal <kushalkoolwal@gmail.com>
Date: Sat, 19 Feb 2011 13:14:03 -0800
Subject: [PATCH 1/1] x86: Fix reboot problem on VersaLogic Menlow boards.
VersaLogic Menlow based boards hang on reboot unless reboot=bios is used.

Add quirk to reboot through the BIOS.
Tested on at least four boards.

Signed-off-by: Kushal Koolwal <kushalkoolwal@gmail.com>
—
arch/x86/kernel/reboot.c |    8 ++++++++
1 files changed, 8 insertions(+), 0 deletions(-)
diff –git a/arch/x86/kernel/reboot.c b/arch/x86/kernel/reboot.c
index fc7aae1..715037c 100644
— a/arch/x86/kernel/reboot.c
+++ b/arch/x86/kernel/reboot.c
@@ -285,6 +285,14 @@ static struct dmi_system_id __initdata reboot_dmi_table[] = {
DMI_MATCH(DMI_BOARD_NAME, “P4S800″),
},
},
+       {       /* Handle problems with rebooting on VersaLogic Menlow boards */
+               .callback = set_bios_reboot,
+               .ident = “VersaLogic Menlow based board”,
+               .matches = {
+                       DMI_MATCH(DMI_BOARD_VENDOR, “VersaLogic Corporation”),
+                       DMI_MATCH(DMI_BOARD_NAME, “VersaLogic Menlow board”),
+               },
+       },
{ }
};
–
1.7.2.3

Note how the name of the file was picked from your first line of the Git commit log. Also the option-n adds the patch number [PATCH 1/1] to your subject and the-soption adds the Signed-off-by: line. The email that is picked in the signed off line is picked from your Git’s configuration that you set inStep 1.

Step 6: Check your patch for errors

Nextwe need to make sure that the patch we are trying to submit does notcontain any obvious errors like white spaces, exceeding 80 columnlimit, etc. There is a perl script calledcheckpath.pl that is provided with the kernel sources for this purpose:

# scripts/checkpatch.pl 0001-x86-Fix-reboot-problem-on-VersaLogic-Menlow-boards.patch

and you should see something like this:

Output:

total: 0 errors, 0 warnings, 14 lines checked
0001-x86-Fix-reboot-problem-on-VersaLogic-Menlow-boards.patch has no obvious style problems and is ready for submission.

There are other scripts also provided inside the kernel source to fix/clean your patch like:

scripts/cleanfile
scripts/cleanpatch

Step 7: Test your patch

Againit is very important that you apply your patch to the Linus’ Git tree,compile it and test it before sending your patch upstream.

# git checkout master
# patch -p1 0001-x86-Fix-reboot-problem-on-VersaLogic-Menlow-boards.patch
# make-kpkg --append-to-version=test-patch kernel_image kernel_headers

Step 8: Get the list of people to submit patch to

Assumingyour patch compiled, worked the way you want it to and your test emailslooked good the next step is to get the list of concern people to whomyou should email your patch. There are two methods to do that:

Method 1: Use the script provided in the kernel source

# scripts/get_maintainer.pl 0001-x86-Fix-reboot-problem-on-VersaLogic-Menlow-boards.patch

Output:

Thomas Gleixner <tglx@linutronix.de> (maintainer:X86 ARCHITECTURE...)
Ingo Molnar <mingo@redhat.com> (maintainer:X86 ARCHITECTURE...,commit_signer:5/8=62%)
"H. Peter Anvin" <hpa@zytor.com> (maintainer:X86 ARCHITECTURE...,commit_signer:3/8=38%)
x86@kernel.org (maintainer:X86 ARCHITECTURE...)
Don Zickus <dzickus@redhat.com> (commit_signer:2/8=25%)
Peter Zijlstra <a.p.zijlstra@chello.nl> (commit_signer:2/8=25%)
Borislav Petkov <bp@alien8.de> (commit_signer:1/8=12%)
linux-kernel@vger.kernel.org (open list)
#

Method 2: Refer to the MAINTAINERS file

The other method is to refer to the MAINTAINERS file that is provide inside the kernel source tree. You need to at least email your patch to all of the people who have“M” before their name.

Note: Alsoyou need to email your patch to at least one mailing list. If you arenot able find any mailing list, based on the above two methods, that isconcerned with the subsystem against which you are trying to submityour patch, then you should at least email to Linux Kernel Mailing List(linux-kernel@vger.kernel.org).

Step 9: Test Email your patch

Althoughyou could use any email client and SMTP host that you want and haveaccess to, I found that using Gmail was the best since a lot of kerneldevelopers use that. Now it is very important that you first test yourpatch by sending it your own email addresses (possible different emailaccount with different mail providers). I use the following:

gitsend-email --smtp-encryption=tls --smtp-server=smtp.gmail.com--smtp-user=kushalkoolwal@gmail.com --smtp-server-port=587 --to"KKoolwal <myname@koolsolutions.com>" --to "Kushal Koolwal<myname@yahoo.com>" --cc "KK <myname@hotmail.com>"0001-x86-Fix-reboot-problem-on-VersaLogic-Menlow-boards.patch

After you hit enter, it will ask for your Gmail account password which you need to enter in order to actually send the email.

Now check email accounts listed above to verify if you got the email and everything looks good for submission.

Step 10: Finally Email your patch

If everything looks right then you finally email your patch based on the list of people you found inStep 8. This is what I actually ended up using:

#git send-email --smtp-encryption=tls --smtp-server=smtp.gmail.com--smtp-user=kushalkoolwal@gmail.com --smtp-server-port=587 --from"Kushal Koolwal <kushalkoolwal@gmail.com>" --to "Thomas Gleixner<tglx@linutronix.de>" --to "Ingo Molnar <mingo@redhat.com>"--to "H. Peter Anvin <hpa@zytor.com>" --to "x86@kernel.org" --cc"linux-kernel@vger.kernel.org"0001-x86-Fix-reboot-problem-on-VersaLogic-Menlow-boards.patch

Here is that commit log of the acceptance of my patch by Ingo Molnar which then trickled from Ingo Molnar’s tree to Stephen Rothwell’s linux-next tree and finally into Linus Torvald’s mainline Linux kernel tree.

That’s it! Good luck with your first patch!