Kernel Janitor Project FAQ

Table of Contents

  1. What is the Kernel Janitor Project?
  2. Who started this project?
  3. Where is the project web site?
  4. Where do I start and what is this "TODO" file that I keep hearing about?
  5. Who maintains the TODO file?
  6. How do I subscribe to the mailing list?
  7. Where do I send my patches?
  8. How do I divide my patches?
  9. Where can I get more information?


1. What is the Kernel Janitor Project?

To quote the original announcement of the project on the linux-kernel mailing list:
"The Kernel Janitor's Project grew out of our search for things to help in the development of the Linux kernel, and learning from other patches submitted by more experiences people, we saw that some of the patches indicated error patterns that could exist in other parts of the kernel."

While other hackers are fine-tuning memory management or adding new device drivers, the members of the Kernel Janitor project clean up existing code. As the kernel evolves, drivers need to updated to make use of the new functionality that is offered. Bugs that are found in one driver can also be found in similar drivers (it is not uncommon for code to be shared or blatantly copied from one driver to another). Some parts the kernel are unmaintained and need to be brought up to date.

The Kernel Janitor Project aims to do all of these little cleanup tasks in order to improve the Linux kernel. It may not be pretty, but it's necessary.

2. Who started this project?

The project was started by Arnaldo Carvolho de Melo (acme) when he put together an unofficial TODO list for things to fix or clean up in the Linux kernel. After some people started sending in suggestions for other items to add to the list, he checked his httpd logs and found out that lots of people were accessing his TODO file. It was therefore concluded that this might be a useful project.

Other major contributors to the project (as in they have write access to the TODO file) are Dave Jones and Jeff Garzik. Anyone is welcome to contribute to the project, however.

3. Where is the project web site?

Like many free software projects, the Kernel Janitor Project is hosted on Sourceforge, at http://sourceforge.net/projects/kernel-janitor.

The project home page, located at http://kernel-janitor.sourceforge.net also provides a few other useful links.

4. Where do I start and what is this "TODO" file that I keep hearing about?

The best place to start is by looking at the TODO file in CVS. After that, the mailing -discuss mailing list is another good place to start looking (see below).

The TODO file is a central part of the project. It contains a list of problems that can be fixed throughout the kernel. As the name implies, it is a list of things "To Do". These include optimizations, making sure return values are checked, replacing obsolete function calls with more recent ones, and so on.

The TODO file is maintained in CVS. The latest version can be found at http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/kernel-janitor/kernel-janitor.

There are also two other important files located there: the README and DONE files. The README file provides a quick introduction to the project and the DONE file lists tasks that have been completed (and therefore removed from the TODO file).

5. Who maintains the TODO file?

The TODO file is maintained by Arnaldo Carvolho de Melo (acme), Dave Jones (davej) and Jeff Garzik (jgarzik). At this time, they are the main contributors so they have write access to the file. Should you want something included in the TODO file that they have overlooked, mention it to them on the mailing list.

6. How do I subscribe to the mailing list?

There are two mailing lists for this project: kernel-janitor-discuss and kernel-janitor-commits. You probably want to subscribe to the -discuss mailing list, since that is where problems are discussed and where patches are posted. You can subscribe to the -discuss list by going to the subscription page at http://lists.sourceforge.net/lists/listinfo/kernel-janitor-discuss and entering your e-mail address and a password. You will then be sent a message to confirm your subscription, to which you can just reply (with the confirmation message quoted in your reply). You can also unsubscribe from the same page.

The kernel-janitor-commits list has been largely inactive for some time. It basically announces when new versions of files have been uploaded to the Sourceforge CVS directory for the project. The subscription page for this list is located at http://lists.sourceforge.net/lists/listinfo/kernel-janitor-commits.

The archives for both lists can be accessed from http://sourceforge.net/mail/?group_id=22207.

7. Where do I send my patches?

Patches to the Linux kernel that fix problems listed in the TODO file should be sent to the -discuss mailing list. It is also a good idea to send the patch to the maintainer of that particular section of the kernel.

If you don't know who maintains a particular section of the kernel, the best place to start looking is the MAINTAINERS file in the kernel source tree (/usr/src/linux/MAINTAINERS, for example). If you can't find an answer in that file, ask on the -discuss list when you post your patch.

8. How do I divide my patches?

Although there are no definitive guidelines for breaking up patches into manageable chunks, the rule of thumb seems to be "one patch per file changed." This is useful for many reasons. For one, there are many different maintainers for different parts of the kernel. Sending one big patch to a lot of maintainers (most of which doesn't apply to their code) won't go over too well. If the patch is split up to only alter a single file, a single maintainer can evaluate the patch and reject it if necessary.

Even if the patches all apply to the same maintainer, he or she might not accept every single patch. Dividing up the work into multiple patches can make it a lot quicker for them to filter through the fixes and evaluate each patch individually.

9. Where can I get more information?

Here are some other useful resources: