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

[Jaegeuk Kim <jaegeuk@kernel.org>]

On 04/17, Matthew Wilcox wrote:
> 
> 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.

I disagree to this. As a filesystem developer, I belive ioctl provides a way
to tune the filesystem-specific features which are not supported by all the
other filesystems.

> 
> > +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.
>