Re: [PATCH] docs: add guidelines for submitting new filesystems

[Matthew Wilcox <willy@infradead.org>]

Thanks for getting this discussion started.  Some thoughts inline ...

On Fri, Apr 17, 2026 at 04:25:03PM +0200, Amir Goldstein wrote:
> +Do You Need a New In-Kernel Filesystem?
> +---------------------------------------
> +
> +Before proposing a new in-kernel filesystem, consider whether one of the
> +alternatives might be more appropriate.
> +
> + - If an existing in-kernel filesystem covers the same use case, improving it
> +   is generally preferred over adding a new implementation.  The kernel
> +   community favors incremental improvement over parallel implementations.
> +
> + - If the filesystem serves a niche audience or has a small user base, a FUSE
> +   (Filesystem in Userspace) implementation may be a better fit.  FUSE
> +   filesystems avoid the long-term kernel maintenance commitment and can be
> +   developed and released on their own schedule.
> +
> + - If kernel-level performance, reliability, or integration is genuinely
> +   required, make the case explicitly.  Explain who the users are, what the
> +   use case is, and why a FUSE implementation would not be sufficient.

It may also be worth linking to
https://en.wikipedia.org/wiki/GVfs as an alternative to writing
an in-kernel filesystem or a FUSE filesystem.  Very much depends what
one's goals are.

> +Technical Requirements
> +----------------------
> +
> +New filesystems are expected to use current kernel interfaces and practices.
> +Submitting a filesystem built on outdated APIs creates an immediate
> +maintenance debt and is likely to face pushback during review.
> +
> +Use modern VFS interfaces
> +  New filesystems should use iomap rather than buffer heads for block mapping
> +  and I/O, folios rather than raw page operations for page cache management,
> +  and the filesystem context API (``fs_context``) for the mount path.  See
> +  ``Documentation/filesystems/iomap/index.rst`` for iomap documentation and
> +  ``Documentation/filesystems/mount_api.rst`` for the mount API.
> +
> +Avoid deprecated interfaces
> +  Do not use interfaces listed in
> +  :ref:`Documentation/process/deprecated.rst <deprecated>`.  If the
> +  filesystem depends on an interface that is being phased out, plan for
> +  conversion before submission.

Maybe these are one section rather than two?

I'd add "If it's a network filesystem, consider using netfs, or be
prepared to explain why it's a bad fit for you".

Similarly if you have a block filesystem, and need functionality not
provided by iomap, be prepared to explain why adding that functionality
to iomap is infeasible.

> +Provide userspace utilities
> +  A ``mkfs`` tool is expected so that the filesystem can be created and used
> +  by testers and users.  A ``fsck`` tool is strongly recommended; while not
> +  strictly required for every filesystem type, the ability to verify
> +  consistency and repair corruption is an important part of a mature
> +  filesystem.
> +
> +Be testable
> +  The filesystem must be testable in a meaningful way.  The
> +  `fstests <https://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git>`_
> +  framework (also known as xfstests) is the standard testing infrastructure
> +  for Linux filesystems and its use is highly recommended.  At a minimum,
> +  there must be a credible and documented way to test the filesystem and
> +  detect regressions.  When submitting, include a summary of test results
> +  indicating which tests pass, fail, or are not applicable.
> +
> +Provide documentation
> +  A documentation file under ``Documentation/filesystems/`` describing the
> +  filesystem, its on-disk format, mount options, and any notable design
> +  decisions is recommended.

I kind of want a section on "no weird ioctls".  Anything you want to
implement beyond ioctls already implemented by other filesystems,
you need to bring to linux-fsdevel as a separate proposal from "please
merge my filesystem".  Almost anything implemented by f2fs is a good
example here.

> +Community and Maintainership Expectations
> +-----------------------------------------
> +
> +Merging a filesystem is a long-term commitment.  The kernel community
> +needs confidence that the filesystem will be actively maintained after it
> +is merged.
> +
> +Identified maintainer
> +  The submission must include a ``MAINTAINERS`` entry with at least one
> +  maintainer (``M:``), a mailing list (``L:``), and a git tree (``T:``).
> +  The maintainer is expected to be the primary point of contact for the
> +  filesystem going forward.

Preferably two maintainers, although even that wasn't enough to save
bcachefs.

> +Submission Process
> +------------------
> +
> +Send patches to the linux-fsdevel mailing list
> +(``linux-fsdevel@vger.kernel.org``).  CC the relevant VFS maintainers as
> +listed in the ``MAINTAINERS`` file under ``FILESYSTEMS (VFS and infrastructure)``.
> +
> +Expect thorough review.  Filesystem code interacts deeply with the VFS, memory
> +management, and block layers, so reviewers will examine the code carefully.
> +Address all review feedback and be prepared for multiple revision cycles.
> +
> +It may be appropriate to mark the filesystem as experimental in its Kconfig
> +help text for the first few releases to set expectations while the code
> +stabilizes in-tree.

I'd like something here about how to structure a submission.  It's
neither acceptable to send one big patch containing your entire
filesystem, nor do we want to see the entire history of development over
the last eight years.

Instead split it up by topic.  Superblock, inode, directory handling,
address_space, ...

> +Ongoing Obligations
> +-------------------
> +
> +Merging is not the finish line.  Maintaining a filesystem in the kernel is an
> +ongoing commitment.
> +
> + - Adapt to VFS infrastructure changes.  The VFS layer evolves continuously;
> +   maintainers are expected to keep up with conversions such as folio
> +   migration, iomap adoption, and mount API updates.
> +
> + - Maintain test coverage.  As test suites evolve, the filesystem's test
> +   results should be kept current.
> +
> + - Handle security issues promptly.  Filesystems parse complex on-disk
> +   structures from potentially untrusted media and must treat security
> +   reports with urgency.
> +
> + - Filesystems that become unmaintained -- where the maintainer stops
> +   responding, infrastructure changes go unadapted, and testing becomes
> +   impossible -- are candidates for deprecation and eventual removal from
> +   the kernel.

Interact with other filesystem maintainers.  They are not your enemy
although they may compete with you for users.  There are opportunities
to share code, share approaches to fixing problems and share features.
It's inappropriate to hide away on your own filesystem list and pop up
once per kernel cycle with a set of patches that nobody's seen before.