Memory-management documentation and development process

As the 2023 Linux Storage, Filesystem, Memory-Management and BPF Summit neared its conclusion, two sessions were held in the memory-management track on process-oriented topics. Mike Rapoport ran a session on memory-management documentation (or the lack thereof), while Andrew Morton talked about the state of the subsystem's development process in general. Both sessions were relatively brief and did not foreshadow substantial changes to come.

Documentation

Rapoport started by saying that documentation has become an annual topic. There has been some big progress since last year's session, he said: Matthew Wilcox had added a table of contents to the memory-management documentation and Rapoport had contributed "a half chapter". This major step forward was greeted with applause from the group. Taking a more serious tone, Rapoport asked for ideas that might lead to a better progress report next year.

Your editor felt the need to point out that, despite the existence of thousands of kernel developers who are paid to contribute code, there is not a single person paid to contribute to the documentation. Many developers try, and a fair amount of documentation work gets done, but it almost always has to be wedged in around the "real" work that people are paid to do. As long as that situation persists, it is going to be hard to see major improvements to the documentation. Matthew Wilcox commented that this is an example of the sort of "endemic corporate brokenness" that we see every day.

Steve Rostedt suggested refusing to accept patches that do not come with documentation; Rapoport answered that this approach would not help with the large amount of documentation debt the community has now. Rostedt said that some sort of "we'll take this patch after you document that" policy could be tried, but Pasha Tatashin pointed out that not everybody is a good writer, and the results from such a policy might not be to the community's liking.

Lorenzo Stoakes said that writers also have to be engineers to do the job properly. Vlastimil Babka pointed out that companies like to have nice technical blogs, and that perhaps some of the energy that goes in that direction could be put into creating documentation. SeongJae Park suggested using ChatGPT. But nobody seemed to have any ideas that would substantially improve the situation.

As the session came to its end, Rapoport was asked where the documentation is most in need of improvement; he answered that potential contributors should find an interesting empty spot in the current table of contents and fill it in.

Since the end of the conference, Stoakes, who is working on a book about Linux memory management, has offered to contribute parts of it to the kernel's documentation. That discussion has just begun, but it may well lead to some significant contributions in the near future.

The state of the community

The final scheduled session in the memory-management track was the traditional discussion with maintainer Andrew Morton about the state of the community as a whole. He didn't have much to say. Everything that he proposed last year, including a move to using Git and changing how patches are handled on their way to the mainline, is working as intended. The mm-stable subtree, perhaps, is the least successful part, just because patches take a long time to stabilize. In response, he is becoming more active about hurrying people along. He has also started putting some of the less-finished patches into mm-stable to give them more stability.

When asked if he planned to kill mm-stable, the answer was "no", but he'll try to move stuff out of the unstable tree more quickly. There is a lot that goes into the stable tree during the last week of the development cycle, which is not ideal, he said.

Michal Hocko said that he likes how the process has changed over the last year. It is much more transparent and a step in the right direction. Nobody else had much to add, so the session came to a close after just a few minutes.

Index entries for this article
Kernel	Documentation
Kernel	Memory management/Documentation
Conference	Storage, Filesystem, Memory-Management and BPF Summit/2023

---

to post comments