Документация для современного API монтирования файловых систем Linux отсутствовала шесть лет

Ключевой системный код не меняется так же быстро, как модные фреймворки, и это хорошо, ведь он должен быть стабильным и отлаженным. Однако иногда задержки могут становиться абсурдными, как в случае с документацией для современного API монтирования файловых систем Linux. Как отмечает Phoronix, информация появилась в стандартной документации man-pages (руководствах) только спустя более шести лет ожидания.

История такова: в 2019 году Linux получил новый API для монтирования файловых систем, где основные вызовы «fsconfig», «fsmount» и «fsopen» заменили старый монолитный «mount». Это упростило жизнь разработчикам, предложив более чистый код, лучшую обработку ошибок и понятные сообщения вместо загадочного «mount failed».

Разработчик Дэвид Хауэллс написал черновики man-страниц ещё в 2020 году, но они так и не были добавлены в официальный пакет, так как сопровождающие не хотели включать потенциально неполные или неточные черновики. Хауэллс, по-видимому, не смог завершить работу, и никто другой за неё не взялся.

В последующие годы разработчикам, желавшим использовать новую систему, приходилось копаться в исходном коде ядра, искать обсуждения в списке рассылки или читать десятки патчей. В лучшем случае нужную информацию можно было найти на сторонних сайтах.

Ещё одной причиной, по которой никто не взялся за написание новых man-страниц, стал устаревший стандартизированный формат Groff, которому уже 35 лет. Он настолько нечитаем для человека, что, как шутят, его мог бы написать сам Ктулху.

В 2024 году эксперт по документации Кристиан Браунер, заявив, что «годы написания на Groff утомили меня», создал собственный репозиторий с версиями страниц на Markdown, наконец-то предоставив разработчикам единое место для поиска нужной информации. И только в октябре 2025 года официальный пакет man-pages наконец включил эти страницы.

Вполне вероятно, что отсутствие документации могло способствовать долгим задержкам во внедрении нового API драйверами файловых систем. Старый добрый Ext4 начал использовать его только в 2022 году, CIFS (SMB) — в 2023, Btrfs присоединился к вечеринке в 2024, а реализация для F2FS (файловой системы для флеш-памяти) всё ещё в процессе. Новые man-страницы ещё не попали в распространённые дистрибутивы, так что пока они доступны только пользователям rolling-релизов.

ИИ: Эта история — отличный пример того, как даже в мире open-source критически важная техническая документация может годами оставаться в тени. Хорошо, что энтузиасты вроде Браунера берут инициативу в свои руки, но шестилетний пробел — серьёзный срок для такого фундаментального API.

Источник: Tomshardware.com