"I'll just take this opportunity to ask people that when they send bug-fixes, please try to make the subject line and message make sense for a *reader*, not for yourself (or even to me, although if it's readable to some generic person, it's hopefully readable to me too!)," Linus Torvalds explained in response to a recent bugfix. He went on to provide some general rules:

"1)if it's not fairly generic, specify the area (architecture, subsystem, driver) that the fix is for in the subject line. [...] 2) don't use commit names in the subject line - and while it's great to use them in the body of the explanation, even there you don't want to assume that people read it from within git. [...] 3) write the commit message for an outsider, and use whitespace. The third-most common fixup I end up doing (after the above two) is to split things up into shorter paragraphs, after somebody wrote a good changelog entry, but made it one large unreadable blob of text."

Linus added, "I end up editing just about half of all the commit messages of stuff I get in email (except for Andrew's stuff, since Andrew largely does the same kinds of cleanups anyway, so I only need to edit up a small percentage of the patches he forwards). I'd like it to be *much* less than that, so I thought I should speak up since I had an example of this."

"For SysRq, we can get [a] hot key list from Documentation/sysrq.txt, but in most of cases, the user can't access it [when] using SysRq to debug, so it is better for SysRq to provide online help for the users," Yi Yang noted, explaining the need for his patch to improve SysReq's built in help. He continued, "in addition, that function has a big loop with another big loop embedded which is very inefficient".

The general reaction was that the changes were unnecessary. Valdis Kletnieks pointed out, "you're optimizing code that hopefully never gets executed, and even if it does, you have the optimization *backwards*. If you're worried about the efficiency, trim it down to output 3 lines - do you realize how many instructions it takes in the VGA and fb drivers to actually *output* all these lines?" He added that people using SysRq for debugging usually fall into two classes and don't require lengthy online help, "1) he has been told 'recreate the problem, hit alt-sysreq-cokebottle, and send me the results', or 2) he's already read the file in Documentation/ and just needs a reminder."

When asked how to best refer to kernels between official releases and release candidates, Linus Torvalds pointed to his automated git snapshots. "I still call them 'nightly snapshots', but they do in fact happen twice a day if there have been changes, so that's not technically correct," he noted. The latest snapshot is 2.6.23-git15, "this is an exact name, because you can go to kernel.org and look up the exact commit ID that was used to generate it (there's an 'ID' file associated with each snapshot there)." For git users, he suggested using the "git describe" command to get the git name, with the current head being named v2.6.23-6562-g8add244. He went on to explain that the name "tells you three things: (a) it's based on 2.6.23 (b) there's been 6562 commits since 2.6.23 and (c) the top-of-tree abbreviated commit is '8add244'."

When asked about the previously discussed usage of "-rc0" and other similar proposed naming conventions, Linus replied:

"Please don't use those names. They don't actually tell anything about where in the cycle it is, and as you can see above, there's been 6500+ commits since 2.6.23, so saying '2.6.23-rc0' or similar really isn't very helpful if anybody actually cares about just where in the release cycle you are."

In a short discussion following a patch titled "fix abdhid mismerge", Al Viro noted troubles in tracking down the changeset that caused the problem, "what's the right way to trace the things like that? Linus?" Linus Torvalds, as the original author of git, replied, "in general, I'm afraid that merge errors are simply not very easy to find." He then offered some general tips for tracking down mis-merges, noting, "if anybody can come up with a better way to find these kinds of mis-merges, I'd love to hear about it." In regards to this particular case, he explained:

"'-c' is for regular combined merges: any file that was modified in both parents will show up as a combination of the diffs of both sides, while a file that was taken in its *entirety* is ignored.

"In this case that's exactly what you wanted. It's just too noisy to necessarily be the default, and you can still have a silent mis-merge if the merger picked *only* one side.

But in general, I suspect that '-c' is often a good thing to try if you cannot find the cause of some change in a regular commit, and suspect a merge error."

"The kernel newbies community often gets inquiries from CS students who need a project for their studies and would like to do something with the Linux kernel, but would also like their code to be useful to the community afterwards," explained Rik van Riel in a posting titled "WANTED: kernel projects for CS students". He offered a link to a Kernel Newbies wiki page titled "KernelProjects" adding, "if you have ideas on what projects would be useful, please add them to this page (or email me)". Rik explained that he was assembling a list of projects on that page that meet the following criteria:

"Are self contained enough that the students can implement the project by themselves, since that is often a university requirement; are self contained enough that Linux could merge the code (maybe with additional changes) after the student has been working on it for a few months; are large enough to qualify as a student project, luckily there is flexibility here since we get inquiries for anything from 6 week projects to 6 month projects."

"Last month, at the kernel summit, there was discussion of putting a Reviewed-by: tag onto patches to document the oversight they had received on their way into the mainline," began Jonathan Corbet in an effort to define the meaning of the recently introduced reviewed-by tag. He continued, "that tag has made an occasional appearance since then, but there has not yet been a discussion of what it really means. So it has not yet brought a whole lot of value to the process."

In the continued discussion, it was requested that all commit tags be defined, prompting Jonathan to update his documentation to include Signed-off-by, Acked-by, Cc, and Tested-by along with his documentation for Reviewed-by. He offered the following definition for the new Reviewed-by tag:

"The patch has been reviewed and found acceptible according to the Reviewer's Statement as found at the bottom of this file. A Reviewed-by tag is a statement of opinion that the patch is an appropriate modification of the kernel without any remaining serious technical issues. Any interested reviewer (who has done the work) can offer a Reviewed-by tag for a patch."

Recent efforts to add additional details to Documentation/CodingStyle prompted Linus Torvalds to reply, "I'm not very happy with this." He explained:

"'CodingStyle' should be about the big issues, not about details. Yes, we've messed that up over the years, but let's not continue that. In other words, I'd suggest *removing* lines from CodingStyle, not adding them. The file has already gone from a 'good general principles' to 'lots of stupid details'. Let's not make it worse."

Erez Zadok pointed out, "there's a lot of good value in having all those details, as it helps people standardize on more common practices, including details. I think removing all those details may only increase the amount-of less-accepted code to be posted, resulting in more lkml people having to repeat themselves on what not to do." He went on to ask, "would you prefer if CodingStyle was reorganized or even split into (1) general principles and (2) details? Perhaps we need a CodingStylePrinciples and a CodingStyleDetails?" Linus responded favorably, "I'm certainly ok with the split into two files. What I'm not ok with is really important stuff (indentation), and then mixing in silly rules (`parenthesis are bad in printk's`?)"

Randy Dunlap sent a patch to the Linux kernel mailing list described as adding "info about various email clients and their applicability in being used to send Linux kernel patches." The first revision generated quite a bit of discussion, quickly resulting in a second version, and eventually a third version that Andrew Morton referred to as "soon to be merged". In addition to some general suggestions about emailing patches, it also offers some specific configuration suggestions for a number of popular email clients. It begins:

"Patches for the Linux kernel are submitted via email, preferably as inline text in the body of the email. Some maintainers accept attachments, but then the attachments should have content-type 'text/plain'. However, attachments are generally frowned upon because it makes quoting portions of the patch more difficult in the patch review process.

"Email clients that are used for Linux kernel patches should send the patch text untouched. For example, they should not modify or delete tabs or spaces, even at the beginning or end of lines."

Some entertaining lguest documentation discussed in an earlier story was merged into the mainline kernel with the commit message, "the netfilter code had very good documentation: the Netfilter Hacking HOWTO. Noone ever read it. So this time I'm trying something different, using a bit of Knuthiness." Both Netfliter and lguest, as well as the documentation for both, were written by Rusty Russell. He describes the lguest driver as, "a simple hypervisor for Linux on Linux. Unlike kvm it doesn't need VT/SVM hardware. Unlike Xen it's simply 'modprobe and go'. Unlike both, it's 5000 lines and self-contained."

Downloading the 2.6.23-rc2 kernel and looking in the "drivers/lguest/" directory I found a simple README that kicks off an interesting documentation process, beginning, "welcome, friend reader, to lguest." It goes on to note, "I can't think of many 5000-line projects which offer both such capability and glimpses of future potential; it is an exciting time to be delving into the source!" At the end of the included README is a hint as to how to find the rest of the documentation, which is embedded inline within all the lguest files. Read on to begin the exploration into lguest and its documentation.

Yasunori Goto posted some documentation for memory hotplugging which can be used to increase or decrease the amount of memory available to a live kernel. The documentation explains that this functionality is useful for virtualization and capacity on demand solutions, as well as for physically adding and removing RAM from NUMA-nodes. The document itself, "is about memory hotplug including how-to-use and current status. Because Memory Hotplug is still under development, contents of this text will be changed often."

It goes on to explain that there are two phases of memory hotplug, the physical memory hotplug phase, and the logical memory hotplug phase. "The first phase is to communicate [the] hardware/firmware and make/erase environment for hotplugged memory. When memory is hotplugged, the kernel recognizes new memory, makes new memory management tables, and makes sysfs files for new memory's operation." The second phase "is to change memory state into available/unavailable for users. [The] amount of memory from [the] user's view is changed by this phase." Hotplugging memory requires it to be brought online or offline using the sysfs files created during the physical memory hotplug phase, though the process can be automated with udev scripts. Setting memory as offline is not guaranteed to work as it's not always possible to free memory, such as if it contains nonmigratable pages. The documentation also notes that support for physically removing memory from a node is not yet completed.

"Lguest is an adventure, with you, the reader, as Hero," began some documentation for lguest recently submitted by Rusty Russell. The documentation continued, "but be warned; this is an arduous journey of several hours or more! And as we know, all true Heroes are driven by a Noble Goal. Thus I offer a Beer (or equivalent) to anyone I meet who has completed this documentation. So get comfortable and keep your wits about you (both quick and humorous). Along your way to the Noble Goal, you will also gain masterly insight into lguest, and hypervisors and x86 virtualization in general."

Andrew Morton noted that he would consider the documentation patches for inclusion in the 2.6.23 kernel, to which Rusty replied, "indeed, no code changes, and I feel strongly that it should go into 2.6.23 because it's *fun*. And (as often complained) there's not enough poetry in the kernel." Linus Torvalds quipped, "there's a reason for that," going on to rhyme, "there once was a lad from Braidwood, with a wife and a hatred for FUD, he hacked kernels for fun, couldn't get them to run, but he always felt that he should." He added, "so when you say 'there's not enough poetry', next time you'll know why. You *really* don't want want poetry." This led to numerous additional poetic submissions about which Rusty noted, "there was a poetic infection, which distorted the kernel's direction, the code got no time, as they all tried to rhyme, and it shipped needing lots of correction."

Two new documentation directories were merged into the upcoming 2.6.23 mainline kernel, containing translations of the HOWTO and stable_api_nonsense.txt documents in Japanese and Chinese. Greg KH explained, "here are some patches that add some translations of some procedural documentation files to the Documentation/ tree." Regarding some of the concerns that were expressed with merging translated documentation into the mainline kernel tarball, Greg noted, "these files change _very_ slowly over time, and are quite easy to keep up to date by the translators." He added:

"I know that kernel development is in English, but translations of a small subset of documentation files that go over procedures and how to get involved in the community is something that I feel is important and will bring in more developers in the end. Having these files in the kernel tree is a good way to keep a central location that all can see and easily find, instead of hiding them away on different web sites that might be harder to update by anyone who needs to do so."

Following a recent patch that translated Documentation/HOWTO into Japanese [story], a new patch offered a translation of the same document into Chinese. Li Yang noted, "currently Chinese involvement in Linux kernel is very low, especially [compared to China's large] population base. Language could be the main obstacle. Hopefully this document will help more Chinese to contribute to Linux kernel."

Linux creator Linus Torvalds noted that he was happy to see translations, "I think that the policies and processes parts of the documentation are things that make total sense to encourage translation of, because it's entirely possible that those are interesting and valid even to the people who aren't necessarily directly involved in the actual coding, and may well be relevant to managers etc who may not be _directly_ involed with the rest of the kernel developers." He then noted that he didn't see any reason to include the translations with the kernel proper, "that said, I don't think that merging the result into the standard kernel makes sense - like it or not, right now English ends up being required to be part of actually getting things into the 'standard' kernel, and as such, at _some_ point there has to be a connection point that switches over to English, and trying to make the translations be an in-kernel thing is thus kind of pointless." Rob Landley noted that he has started putting together a documentation site on which he will include these translations, "send me translations (preferably in HTML format), and I'll put 'em up. (I've already got the one that started this thread.)"