Linux Kernel – Contributing – Part I
Linux Kernel
Contributing
Part I
Created by Luis Ibanez / @luisibanez
Linus in Kernel mailing list...
“ So at one level I absolutely _hate_ trivial patches: they take time and effort to merge, and individually the patch itself is often not really obviously "worth it"... ”Linus in Kernel mailing list...
“ ...But at the same time, I think the trivial patches are among the most important ones - exactly because they are the "entry" patches for every new developer. ”Working with Friends ?
Learn how to share a terminal
You may want to use
TMUX
Log with your friends
into the same server...
Pick one of you
to host the session
The host types...
tmux -S /tmp/joyfulsession
chmod 777 /tmp/joyfulsession
The friends type...
tmux -S /tmp/joyfulsession attach
At this point
you will be sharing...
the same screen
and
the same keyboard
Coordinate
who
is typing
be nice
and
stay calm !
The
Beginning...
The Kernel Community
Uses Git
You may want to
first follow
these two Git tutorials
Now that you know
Git basics,
we can start...
Getting the Kernel
Source Code
Configure Git
Identify yourself...
git config --global user.email “myemail@gmail.com”
git config --global user.name “My Name”
Configure Git
Configure it to be able to send email using an SMTP relay
for example, gmail:
git config --global sendemail.smtpencryption tls
git config --global sendemail.smtpserver smtp.gmail.com
git config --global sendemail.smtpuser myemail@gmail.com
git config --global sendemail.smtpserverport 587
You could also use other SMTP relays...
Clone the Repository...
git clone git://git.kernel.org/pub/scm/linux/kernel/git/davem/net-next.git
Enter the Directory ...
cd net-next
Create a branch...
git branch tutorial-devel
Checkout that new branch...
git branch tutorial-devel
Review Process
The Kernel Community has set up a review process by which a patch is authored by one developer, and then reviewed by other more experienced developers
Review Process
The role of developers is specified
by text in the Git commit messages
Typical Roles
The role of developers is specified
by text in the Git commit messages.
Typical Roles
Signed-off-by:
Reviewed-by:
Tested-by:
Suggested-by:
Reported-by:
Signed Off By
The primary developer uses the “Signed-off-by:” line
Signed-off-by:
provided by the “--signoff” flag
passed to git (shown later)
Easy Patches
Let's start with some easy patches...
printk()
print() is the standard function
to print messages from the Kernel code.
printk()
Recently, a standard was adopted
to add priority levels
in all printk() calls
printk()
There are about 10,000
printk() calls in the Kernel
printk()
Presently there are many examples of
printk("my message %d\n", int_arg);
The accepted standard now is
to use printk() with a leading argument.
printk(KERN_INFO "my message %d\n", int_arg);
printk() levels
KERN_DEBUG
KERN_INFO
KERN_NOTICE
KERN_WARNING
KERN_ERR
KERN_CRIT
KERN_ALERT
KERN_EMERGENCY
Follow Examples
From the netdev mailing list:
http://patchwork.ozlabs.org/project/netdev/list
see what other people are submitting
netdev
The netdev mailing list is one of
a few that use the patchwork software
to track patches semi-automatically.
It is run by Dave Miller
Let's Patch!
Navigate
Go into a directory,
for example:
cd net-next/drivers/net/ethernet
Find Candidates
Search for printk() expressions
with the grep command:
git grep printk
Compare
Compare the lines from printk() with levels:
amd/am79c961a.c: printk(KERN_INFO "%s", version);
to those without levels:
amd/7990.c: printk ("TX rings:\n");
Edit
Use your favorite text editor to open the file
for example:
vim amd/7990.c
Modify
Inspect the printk() lines
and decide what LEVEL to insert
Save
Save your modifications
and quit your text editor
Stage
Stage your modifications
with the git command
git add amd/7990.c
Commit
Commit your modifications
with the git command
git commit
Commit Message
Follow the model of other commit messages
from the netdev mailing list
Commit Message
For example
drivers/net: use module_pcmcia_driver() in pcmcia drivers
Use the new module_pcmcia_driver() macro to remove the boilerplate
module init/exit code in the pcmcia drivers.
Signed-off-by: H Hartley Sweeten <hsweeten@visionengravers.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
copied from commit
fdd3f29eddd1b7c26b3b42e3633afcb22a28fcb3
Commit Message
- The first line is the subject of the patch
- It is followed by paragraphs describing the details
- It ends with signed-off lines
Commit Message
If you are working in group,
use "Reviewed-by:" lines with
the names of your team members.
Generate
Generate the patch with the following commands
cd ~/net-next
git format-patch --subject-prefix "PATCH net-next" --signoff master
This will create a file starting with "0001-"
email the patch to yourself:
git send-email -to another_one@email.com 0001-patchfile
Use an alternate email account,
since by default
git CCs your address in ~/.gitconfig
Multiple Files?
If you changed multiple files as part of a single patch,
put them in a directory to make the submission easier:
mkdir mypatches
cd mypatches
git format-patch --signoff --subject-prefix net-next master
cd ..
git send-email patches -to myself@gmail.com
Choose the "all" option when prompted
Submit
Submit the patch by emailing it
to the proper maintainer.
For example, for net-dev:
git send-email -to netdev@vger.kernel.org 0001-patchfile
Submit
Consult the source tree MAINTAINERS file
to find where you should submit the patch.