First Contribution¶

1. Preparing your tools¶

We assume here that you've already installed the dependencies detailed in the boot tutorial.

1.0. Fetching the new dependencies¶

1.1. Update your kernel¶

We will work on the staging tree, that contains code that is not considered ready for merging into the main portion of the kernel due to various reasons (i.e. not meeting the project's quality standards yet).

You can see all the remotes you have simply by running the git remote -v command.

You can fetch the current staging branches with the following:

git fetch staging

Then create your own branch from staging/staging-next:

git checkout -b first-patch staging/staging-next

1.2. Setup git and email¶

To be able to send Linux kernel patches, you'll need to configure:

• Your identity (name + email)
• Your text editor of choice: Vim (vim), VS Code (code), ...
• Your email settings (so that you can send email patches with git)

Inside your kernel repository folder, edit the .git/config file (or create it if it doesn't exit) and add the following fields (remember to fill them with your own info):

[user]
  email = <your-email-address>
  name = <your-name>
[core]
  editor = <your-favorite-editor>
[sendemail]
  smtpServer = <your-smtp-server>
  smtpServerPort = <your-smtp-port>
  smtpEncryption = tls
  smtpUser = "<your-email-address>"
  smtpPass = "<your-email-password>"

Here are some example [sendemail] setups for the two most common use cases: a Gmail account and a generic email account:

[sendemail]
    smtpServer = smtp.gmail.com
    smtpServerPort = 587
    smtpEncryption = tls
    smtpUser = "your.user@gmail.com"
    smtpPass = "your.password"

[sendemail]
    smtpServer = smtp.purelymail.com
    smtpServerPort = 587
    smtpEncryption = tls
    smtpUser = "your.user@lkcamp.dev"
    smtpPass = "your.password"

1.3 Setup text editor¶

Linux kernel developers have very stringent guidelines for coding style. You can setup your editor to follow them.

filetype plugin indent on  " make sure it will automatically indent your files
syntax on                  " highlight syntax
set title                  " show the file name you are working on

set tabstop=8
set softtabstop=8
set shiftwidth=8
set noexpandtab

    sudo pacman -S clangd

    sudo dnf install clang clang-tools-extra

    sudo apt install clangd

2. Find a good first contribution¶

To ensure all contributions follow the guidelines for coding style, the developers created a script called checkpatch.pl.

Some drivers don't follow these rules or are simply not ready yet. These drivers are located on drivers/staging folder.

In this folder you can find some drivers to clean up.

find drivers/staging -name TODO

Now you can find some coding style to fix on one of these drivers (for example sm750fb driver).

perl scripts/checkpatch.pl -f drivers/staging/sm750fb/*

3. Making a contribution¶

First, we'll choose a modification that won't require testing the module.

3.1 Writing a good commit message¶

Most importantly you must always sign your commits, you can do that by adding -s flag when committing. It's a good practice to indicate the tree and driver in which you are making changes, take a look at the commit below for example.

You can add and commit your changes:

git add <the_file_you_modified>
git commit -v -s

Let's be sure our commit follows the coding style.

perl scripts/checkpatch.pl -g <your_commit_id>

3.2 Sending the commit¶

Search for the maintainer's email, in this case use the mailing lists:

git show <your_commit_id> | perl scripts/get_maintainer.pl --nokeywords --nogit --nogit-fallback --norolestats --separator=','

Check how the patch would be sent:

git send-email --annotate --suppress-cc=all --to="<lists>","<maintainers>","~lkcamp/patches@lists.sr.ht" --dry-run <commit_id>^

Now, send your first patch to the public mailing lists:

git send-email --annotate --suppress-cc=all --to="<lists>","<maintainers>","~lkcamp/patches@lists.sr.ht" <commit_id>^

Congrats! You just sent your first patch to the kernel \o/

Now you just need to wait for someone on the community to review your patch.

4. Got feedback? Sending a second version of a patch¶

More often than not, the kernel community will give feedback on how to improve your patch. It is very common for patches not to be accepted in their first version. When this happens, you will need to make the modifications required to fix the problems pointed out by your reviewers, and then send a second version (v2) of your patch.

4.0 Update your tree¶

First of all, remember to fetch the modifications from remote:

git fetch staging

Now you have to rebase your tree to the last accepted commit. Normally this tree will be the -next, but if there are commits on -testing tree, you can rebase this last:

git rebase -i staging/staging-testing

4.1 Modifying your commit¶

Make the modifications required and add them to your staging tree:

git add <the_file_you_changed>

Add the changes to your first commit. If your commit is the last one in the tree, it's possible to just amend the last commit and include the newly staged changes:

git commit --amend

In the commit message, after the — cut off, add the changes made in this version:

<commit message>

Signed-off-by: Your name <your.email@domain.com>
---
Changes in v2:
    - first change
    - second change

The notes after the — cut off will not be recorded in the permanent git log.

4.2 Sending a v2¶

Make a V2 from your patch:

git format-patch <commit_id>^ -v2

The previous command will provide a .patch with a [PATCH v2] header. This header is important so the maintainers can keep track of your patch's versions.

Test your email send:

git send-email <your_patch>.patch --suppress-cc=all --to="<lists>","<maintainers>","~lkcamp/patches@lists.sr.ht" --dry-run

5. (extra) Sending more contributions¶

5.1. Testing your changes¶

You never know if your changes will end up breaking the kernel. Even if you're only doing simple stuff, like fixing a variable name (checkpatch: Avoid CamelCase) or removing a parenthesis (checkpatch: Unnecessary parentheses), you should always test the changes you make before sending them to the community.

You must, at the very least, for every change (i.e. every commit):

• Rebuild the kernel, confirm that it compiles and make sure there are no new compilation warnings introduced by your changes
• Test if it boots on QEMU

After making your changes (and preferably before commiting), you have to test them:

Now you should build the modules with your VM as target (you will need to mount it to run this command):

sudo mount ../my_disk.raw ../mnt_partition
sudo make INSTALL_MOD_PATH=../mnt_partition modules_install
sudo umount ../mnt_partition

Now you should build and boot, as learnt on workshop 1 - section 2.

Check for errors in the kernel log after booting:

dmesg

Load module and check the logs:

modprobe <module name>
dmesg
lsmod | grep <module name>

Remove it and check the logs again:

modprobe -r <module name>
dmesg
lsmod | grep <module name>

Any problems booting? Any error messages related to your module? Any problems loading or removing it?

If not, then you can go ahead and send the v2 for your patch. :)

Just repeat section 3.

5.2 Patch Series¶

A patch should do one thing and one thing only. This helps reviewers and makes it easier to find where bugs were introduced when investigating kernel regressions. If you have more than one thing that you would like to do, you will need to split the changes into multiple commits and send them as a patch series.

Patch series are two or more commits that will be submitted together in the same e-mail batch. It is common to add a cover letter to a patch series to give an explanation of what the patch series does.

You can use format-patch to generate *.patch files for all commits, plus the cover letter:

git format-patch -N <commit_id last one>^ --cover-letter -o path/to/dir

Now you can edit the cover letter.

When everything is done, you may test your email send (all patches will be sent in the same command git send-email).

git send-email path/to/dir/ *.patch --suppress-cc=all --to="<lists>","<maintainers>","~lkcamp/patches@lists.sr.ht" --dry-run