[PATCH] docs: add guidelines for submitting new filesystems

[PATCH] docs: add guidelines for submitting new filesystems

[Amir Goldstein]

This document is motivated by the ongoing maintenance burden that
abandoned and untestable filesystems impose on VFS developers, blocking
infrastructure changes such as folio conversions and iomap migration.

This week alone, two new filesystems were proposed on linux-fsdevel
(VMUFAT and FTRFS), highlighting the need for documented guidelines
that new filesystem authors can refer to before submission.

Multiple recent discussions on linux-fsdevel have touched on the
criteria for merging new filesystems and for deprecating old ones,
covering topics such as modern VFS interface adoption, testability,
userspace utilities, maintainer commitment, and user base viability.

Add Documentation/filesystems/adding-new-filesystems.rst describing
the technical requirements and community expectations for merging a
new filesystem into the kernel.  The guidelines cover:
- Alternatives to consider before proposing a new in-kernel filesystem
- Technical requirements: modern VFS interfaces (iomap, folios,
  fs_context mount API), testability, and userspace utilities
- Community expectations: identified maintainers, demonstrated
  commitment, sustained backing, and a clear user base
- Ongoing obligations after merging, including the risk of deprecation
  for unmaintained filesystems

Link: https://lore.kernel.org/linux-fsdevel/20260411151155.321214-1-adrianmcmenamin@gmail.com/
Link: https://lore.kernel.org/linux-fsdevel/20260413142357.515792-1-aurelien@hackers.camp/
Link: https://lore.kernel.org/linux-fsdevel/yndtg2jbj55fzd2kkhsmel4pp5ll5xfvfiaqh24tdct3jiqosd@jzbfzf3rrxrd/
Link: https://lore.kernel.org/linux-fsdevel/20260124091742.GA43313@macsyma.local/
Link: https://lore.kernel.org/lkml/20260111140345.3866-1-linkinjeon@kernel.org/
Cc: Christian Brauner <brauner@kernel.org>
Cc: Alexander Viro <viro@zeniv.linux.org.uk>
Cc: Jan Kara <jack@suse.cz>
Cc: Theodore Tso <tytso@mit.edu>
Cc: Christoph Hellwig <hch@lst.de>
Cc: Darrick J. Wong <djwong@kernel.org>
Cc: Matthew Wilcox <willy@infradead.org>
Assisted-by: Cursor:claude-4-opus
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
---

Hi folks,

I am posting this patch as a placeholder for a TOPIC discussion at LSFMM.
This is a reoccurring topic on fsdevel and in LSFMM, but I think it is
worth having, because I do not think we have made a significant progress
in solving the vfs maintenance burden problem.

As much as I hate manifests and even more so discussions about
manifests, I think that having a document like this will at least save
us some time in writing the bounce emails.

Please try not to make this a discussion about a legal document!

Note that LLM has helped me collect the relevant discussions and
articulate our collective feedbacks into a summary.

Note that same LLM makes it much easier for random people to
submit new filesystems, so we may need to work harder in the near
future on push backs...

Thanks,
Amir.


 .../filesystems/adding-new-filesystems.rst    | 167 ++++++++++++++++++
 Documentation/filesystems/index.rst           |   1 +
 2 files changed, 168 insertions(+)
 create mode 100644 Documentation/filesystems/adding-new-filesystems.rst

diff --git a/Documentation/filesystems/adding-new-filesystems.rst b/Documentation/filesystems/adding-new-filesystems.rst
new file mode 100644
index 0000000000000..2e59b7127c05f
--- /dev/null
+++ b/Documentation/filesystems/adding-new-filesystems.rst
@@ -0,0 +1,167 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _adding_new_filesystems:
+
+Adding New Filesystems
+======================
+
+This document describes what is involved in adding a new filesystem to the
+Linux kernel, over and above the normal submission advice in
+:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` and
+:ref:`Documentation/process/submit-checklist.rst <submitchecklist>`.
+
+Every filesystem merged into the kernel becomes the collective responsibility
+of the VFS maintainers and the wider filesystem development community.
+Experience has shown that filesystems which become unmaintained impose a
+significant and ongoing burden: they are hard or impossible to test, they
+block infrastructure changes because someone must update or preserve old APIs
+for code that nobody is actively looking after, and they accumulate unfixed
+bugs.  The requirements and expectations described here are informed by this
+experience and are intended to ensure that new filesystems enter the kernel
+on a sustainable footing.
+
+
+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.
+
+
+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.
+
+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.
+
+
+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.
+
+Demonstrated commitment
+  A track record of maintaining kernel code -- for example, in other
+  subsystems -- significantly strengthens the case for a new filesystem.
+  Maintainers who are already known and trusted within the community face
+  less friction during review.
+
+Sustained backing
+  Major filesystems in Linux have organizational or corporate support behind
+  their development.  Filesystems that depend entirely on volunteer effort
+  face higher scrutiny about their long-term viability.
+
+Responsiveness
+  The maintainer is expected to respond to bug reports, address review
+  feedback, and adapt the filesystem to VFS infrastructure changes such as
+  folio conversions, iomap migration, and mount API updates.  Unresponsive
+  maintainership is one of the primary reasons filesystems end up on the
+  path to deprecation.
+
+User base
+  Clearly describe who the users of this filesystem are and the scale of the
+  user base.  Filesystems with a very small or unclear user base face a
+  harder path to acceptance and a higher risk of future deprecation.
+
+A practical way to demonstrate many of the qualities above is to maintain the
+filesystem out-of-tree for a period before requesting a merge.  This shows
+sustained commitment, builds a visible user base, and gives reviewers
+confidence that the code and its maintainer will persist after merging.
+That said, it is recognized that for some filesystems the user base grows
+significantly only after upstreaming, so a compelling case for expected
+adoption can substitute for a large existing user base.
+
+
+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.
+
+
+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.
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index f4873197587df..10e40cc9cbc9d 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -42,6 +42,7 @@ algorithms work.
    caching/index
 
    porting
+   adding-new-filesystems
 
 Filesystem support layers
 =========================
-- 
2.53.0

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

[Matthew Wilcox]

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.

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

[Amir Goldstein]

On Fri, Apr 17, 2026 at 5:36 PM Matthew Wilcox <willy@infradead.org> 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.

I rather not.
Feels like saying FUSE is enough of a code name for
You may not need a kernel fs
I don't feel it is our place to guide people more than that...

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

Very good feedback!

Pushed commit with the changes v1->v2 to:
https://github.com/amir73il/linux/commits/vfs-docs/
so you can review the incorporated changes.

GitHub also displays the doc in a ReSTy way that could be nicer for doc review:
https://github.com/amir73il/linux/blob/vfs-docs/Documentation/filesystems/adding-new-filesystems.rst

Feel free to comment on github if you have editorial fixes to suggest
before I post v2.

Thanks,
Amir.

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

[Jaegeuk Kim]

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

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

[Amir Goldstein]

On Fri, Apr 17, 2026 at 7:20 PM Jaegeuk Kim <jaegeuk@kernel.org> wrote:
>
> On 04/17, Matthew Wilcox wrote:
> >
...
> > 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.
>

Jaegeuk,

Note that, despite Matthew's unhidden opinion about "weird ioctls",
the proposed clause does not say that they are not allowed.

The section refers to the way to submit a new filesystem for review
and requests that special ioctls will be clearly submitted separately.
Here is how I have added it in my work branch:

 - Structure the submission logically.  It is neither acceptable to send one
   large patch containing the entire filesystem, nor is a replay of the full
   development history helpful to reviewers.  Instead, split the series by
   topic -- for example: superblock and mount handling, inode operations,
   directory operations, address space operations, and so on -- so that each
   patch is reviewable in isolation.

 - Separate any filesystem-specific ioctls into their own patches with
   dedicated justification.  Interfaces beyond those already common across
   other filesystems will receive additional scrutiny because they are hard
   to maintain and may conflict with future generic interfaces.

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

Thanks,
Amir.

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

[Matthew Wilcox]

On Fri, Apr 17, 2026 at 04:25:03PM +0200, Amir Goldstein wrote:
> +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.

Perhaps we need a section on fuzzing?  Maybe something like this:

Fuzzing
  Filesystems in the Linux kernel are subjected to various fuzzing
  activities, by academic researchers, syzbot and malicious actors.
  Your filesystem will need to be robust against not just random
  syscalls but also fuzzed (corrupted) filesystem images (for block
  based filesystems) and crafted hostile network messages (for network
  filesystems).  It should react appropriately to such attacks,
  by repairing or reporting a corrupted filesystem, but not hanging
  executing BUG() or WARN() statements or otherwise corrupting the kernel.

Happy for you to reword that.

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

[Jaegeuk Kim]

On 04/18, Amir Goldstein wrote:
> On Fri, Apr 17, 2026 at 7:20 PM Jaegeuk Kim <jaegeuk@kernel.org> wrote:
> >
> > On 04/17, Matthew Wilcox wrote:
> > >
> ...
> > > 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.
> >
> 
> Jaegeuk,
> 
> Note that, despite Matthew's unhidden opinion about "weird ioctls",
> the proposed clause does not say that they are not allowed.
> 
> The section refers to the way to submit a new filesystem for review
> and requests that special ioctls will be clearly submitted separately.
> Here is how I have added it in my work branch:
> 
>  - Structure the submission logically.  It is neither acceptable to send one
>    large patch containing the entire filesystem, nor is a replay of the full
>    development history helpful to reviewers.  Instead, split the series by
>    topic -- for example: superblock and mount handling, inode operations,
>    directory operations, address space operations, and so on -- so that each
>    patch is reviewable in isolation.
> 
>  - Separate any filesystem-specific ioctls into their own patches with
>    dedicated justification.  Interfaces beyond those already common across
>    other filesystems will receive additional scrutiny because they are hard
>    to maintain and may conflict with future generic interfaces.
> 
>  - 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.

Thanks, those are all reasonable to me, as I did quite similarly in 2012,
https://lwn.net/Articles/518718/.

Some useful tips before submission might be helpful:
1) find a company sponsorship for long-term maintenance support
2) present key differentiating features to filesystem/kernel leads (e.g., Ted)
3) check any patent/copyright violation
4) share the results of xfstests/fsstress/power-off recovery test/code coverage

Thanks,

> 
> Thanks,
> Amir.

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

[Amir Goldstein]

On Sat, Apr 18, 2026 at 11:32 PM Matthew Wilcox <willy@infradead.org> wrote:
>
> On Fri, Apr 17, 2026 at 04:25:03PM +0200, Amir Goldstein wrote:
> > +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.
>
> Perhaps we need a section on fuzzing?  Maybe something like this:
>
> Fuzzing
>   Filesystems in the Linux kernel are subjected to various fuzzing
>   activities, by academic researchers, syzbot and malicious actors.
>   Your filesystem will need to be robust against not just random
>   syscalls but also fuzzed (corrupted) filesystem images (for block
>   based filesystems) and crafted hostile network messages (for network
>   filesystems).  It should react appropriately to such attacks,
>   by repairing or reporting a corrupted filesystem, but not hanging
>   executing BUG() or WARN() statements or otherwise corrupting the kernel.
>
> Happy for you to reword that.

Too long for me :)

I've included a mention of the fuzzing reality in the obligation for
handling security reports:

 - Handle security issues promptly.  Filesystems parse complex on-disk
   structures from potentially untrusted media and must treat security
   reports with urgency.  Expect the filesystem to be subjected to fuzzing
   of both syscalls and filesystem images.  The filesystem must handle
   corrupted input gracefully without hanging or crashing the kernel.

Thanks,
Amir.

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

[Amir Goldstein]

On Sun, Apr 19, 2026 at 12:18 AM Jaegeuk Kim <jaegeuk@kernel.org> wrote:
>
> On 04/18, Amir Goldstein wrote:
> > On Fri, Apr 17, 2026 at 7:20 PM Jaegeuk Kim <jaegeuk@kernel.org> wrote:
> > >
> > > On 04/17, Matthew Wilcox wrote:
> > > >
> > ...
> > > > 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.
> > >
> >
> > Jaegeuk,
> >
> > Note that, despite Matthew's unhidden opinion about "weird ioctls",
> > the proposed clause does not say that they are not allowed.
> >
> > The section refers to the way to submit a new filesystem for review
> > and requests that special ioctls will be clearly submitted separately.
> > Here is how I have added it in my work branch:
> >
> >  - Structure the submission logically.  It is neither acceptable to send one
> >    large patch containing the entire filesystem, nor is a replay of the full
> >    development history helpful to reviewers.  Instead, split the series by
> >    topic -- for example: superblock and mount handling, inode operations,
> >    directory operations, address space operations, and so on -- so that each
> >    patch is reviewable in isolation.
> >
> >  - Separate any filesystem-specific ioctls into their own patches with
> >    dedicated justification.  Interfaces beyond those already common across
> >    other filesystems will receive additional scrutiny because they are hard
> >    to maintain and may conflict with future generic interfaces.
> >
> >  - 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.
>
> Thanks, those are all reasonable to me, as I did quite similarly in 2012,
> https://lwn.net/Articles/518718/.
>
> Some useful tips before submission might be helpful:
> 1) find a company sponsorship for long-term maintenance support
> 2) present key differentiating features to filesystem/kernel leads (e.g., Ted)
> 3) check any patent/copyright violation
> 4) share the results of xfstests/fsstress/power-off recovery test/code coverage
>

Good checklist!

I believe that the document already captures those guidelines,
except for the copyright one which is not filesystem specific.

Thanks,
Amir.

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

[Jan Kara]

On Sat 18-04-26 22:32:49, Matthew Wilcox wrote:
> On Fri, Apr 17, 2026 at 04:25:03PM +0200, Amir Goldstein wrote:
> > +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.
> 
> Perhaps we need a section on fuzzing?  Maybe something like this:
> 
> Fuzzing
>   Filesystems in the Linux kernel are subjected to various fuzzing
>   activities, by academic researchers, syzbot and malicious actors.
>   Your filesystem will need to be robust against not just random
>   syscalls but also fuzzed (corrupted) filesystem images (for block
>   based filesystems) and crafted hostile network messages (for network
>   filesystems).  It should react appropriately to such attacks,
>   by repairing or reporting a corrupted filesystem, but not hanging
>   executing BUG() or WARN() statements or otherwise corrupting the kernel.

Well, as much as I agree this is the goal, our current in-kernel
filesystems (even the well supported ones) aren't meeting these goals.
Dealing with maliciously corrupted media simply isn't an attack vector
filesystem developers (including me) consider particularly severe. So sure
fuzzing results must be reviewed as syzbot sometimes finds issues where
unpriviledged user on totally correct filesystem manages to corrupt it,
corrupt memory, or do other nasty things but in particular the reproducers
based on corrupted images are in "good to fix" category only.

								Honza
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR

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

[Jan Kara]

On Fri 17-04-26 16:25:03, Amir Goldstein wrote:
> + - Handle security issues promptly.  Filesystems parse complex on-disk
> +   structures from potentially untrusted media and must treat security
> +   reports with urgency.

I've commented on this in reply to Matthew. I agree syzbot results must be
reviewed and identified security issues treated in a timely manner. However
dealing with maliciously corrupted on-disk data isn't (IMO) a serious
attack vector. Even current well maintained filesystems (e.g. ext4 and
others) have some issues in this area so it seems unfair to ask this from a
new filesystem.

								Honza
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR

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

[Amir Goldstein]

On Mon, Apr 20, 2026 at 4:37 PM Jan Kara <jack@suse.cz> wrote:
>
> On Fri 17-04-26 16:25:03, Amir Goldstein wrote:
> > + - Handle security issues promptly.  Filesystems parse complex on-disk
> > +   structures from potentially untrusted media and must treat security
> > +   reports with urgency.
>
> I've commented on this in reply to Matthew. I agree syzbot results must be
> reviewed and identified security issues treated in a timely manner. However
> dealing with maliciously corrupted on-disk data isn't (IMO) a serious
> attack vector. Even current well maintained filesystems (e.g. ext4 and
> others) have some issues in this area so it seems unfair to ask this from a
> new filesystem.
>

This is what I posted in v2:

 - Handle security issues promptly.  Filesystems parse complex on-disk
   structures from potentially untrusted media and must treat security
   reports with urgency.  Expect the filesystem to be subjected to fuzzing
   of both syscalls and filesystem images.  The filesystem must handle
   corrupted input gracefully without hanging or crashing the kernel.

Are you saying that ext4 and others do not react to crash reports from
image fuzzing which result in crash/hang?

Can you suggest a more relaxed clause or should I remove it altogether?

Thanks,
Amir.

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

[Darrick J. Wong]

On Mon, Apr 20, 2026 at 08:14:58PM +0200, Amir Goldstein wrote:
> On Mon, Apr 20, 2026 at 4:37 PM Jan Kara <jack@suse.cz> wrote:
> >
> > On Fri 17-04-26 16:25:03, Amir Goldstein wrote:
> > > + - Handle security issues promptly.  Filesystems parse complex on-disk
> > > +   structures from potentially untrusted media and must treat security
> > > +   reports with urgency.
> >
> > I've commented on this in reply to Matthew. I agree syzbot results must be
> > reviewed and identified security issues treated in a timely manner. However
> > dealing with maliciously corrupted on-disk data isn't (IMO) a serious
> > attack vector. Even current well maintained filesystems (e.g. ext4 and
> > others) have some issues in this area so it seems unfair to ask this from a
> > new filesystem.
> >
> 
> This is what I posted in v2:
> 
>  - Handle security issues promptly.  Filesystems parse complex on-disk
>    structures from potentially untrusted media and must treat security
>    reports with urgency.  Expect the filesystem to be subjected to fuzzing
>    of both syscalls and filesystem images.  The filesystem must handle
>    corrupted input gracefully without hanging or crashing the kernel.
> 
> Are you saying that ext4 and others do not react to crash reports from
> image fuzzing which result in crash/hang?

I think it's more that nearly every filesystem has severe resource
constraints w.r.t. developer time, so reports from automated fuzzers are
assigned idle priority.

> Can you suggest a more relaxed clause or should I remove it altogether?

I think that what you've got there is a good expectation.  Each
filesystem implementation should have a mechanism to handle corruptions
with grace, and (presumably) new fuzz reports will result in patches
that use that graceful mechanism, whatever it is.

Anyone who wants specific response times to fuzzer reports can enter a
contract with a company or hire any of the many recently laid off
kernel people (or AISLOPFAFO) to provide SLA-like support.

--D

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

[Jan Kara]

On Mon 20-04-26 20:14:58, Amir Goldstein wrote:
> On Mon, Apr 20, 2026 at 4:37 PM Jan Kara <jack@suse.cz> wrote:
> >
> > On Fri 17-04-26 16:25:03, Amir Goldstein wrote:
> > > + - Handle security issues promptly.  Filesystems parse complex on-disk
> > > +   structures from potentially untrusted media and must treat security
> > > +   reports with urgency.
> >
> > I've commented on this in reply to Matthew. I agree syzbot results must be
> > reviewed and identified security issues treated in a timely manner. However
> > dealing with maliciously corrupted on-disk data isn't (IMO) a serious
> > attack vector. Even current well maintained filesystems (e.g. ext4 and
> > others) have some issues in this area so it seems unfair to ask this from a
> > new filesystem.
> >
> 
> This is what I posted in v2:
> 
>  - Handle security issues promptly.  Filesystems parse complex on-disk
>    structures from potentially untrusted media and must treat security
>    reports with urgency.  Expect the filesystem to be subjected to fuzzing
>    of both syscalls and filesystem images.  The filesystem must handle
>    corrupted input gracefully without hanging or crashing the kernel.
> 
> Are you saying that ext4 and others do not react to crash reports from
> image fuzzing which result in crash/hang?

We are reacting to them, but not with such an urgency this paragraph seems
to suggest :).

> Can you suggest a more relaxed clause or should I remove it altogether?

I definitely want to keep a clause like this. Maybe I'd just reformulate it
like:

  - Handle security issues promptly.  Both those reported by ordinary users
    as well as those reported by fuzzing tools. Expect that your filesystem
    will be subject to syscall fuzzing as well as filesystem image fuzzing.
    Dealing with maliciously corrupted filesystem images is not generally
    considered a high severity security issue but still it is considered a
    quality-of-implementation issue that should be fixed.

								Honza
-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR

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

[Amir Goldstein]

On Tue, Apr 21, 2026 at 12:16 PM Jan Kara <jack@suse.cz> wrote:
>
> On Mon 20-04-26 20:14:58, Amir Goldstein wrote:
> > On Mon, Apr 20, 2026 at 4:37 PM Jan Kara <jack@suse.cz> wrote:
> > >
> > > On Fri 17-04-26 16:25:03, Amir Goldstein wrote:
> > > > + - Handle security issues promptly.  Filesystems parse complex on-disk
> > > > +   structures from potentially untrusted media and must treat security
> > > > +   reports with urgency.
> > >
> > > I've commented on this in reply to Matthew. I agree syzbot results must be
> > > reviewed and identified security issues treated in a timely manner. However
> > > dealing with maliciously corrupted on-disk data isn't (IMO) a serious
> > > attack vector. Even current well maintained filesystems (e.g. ext4 and
> > > others) have some issues in this area so it seems unfair to ask this from a
> > > new filesystem.
> > >
> >
> > This is what I posted in v2:
> >
> >  - Handle security issues promptly.  Filesystems parse complex on-disk
> >    structures from potentially untrusted media and must treat security
> >    reports with urgency.  Expect the filesystem to be subjected to fuzzing
> >    of both syscalls and filesystem images.  The filesystem must handle
> >    corrupted input gracefully without hanging or crashing the kernel.
> >
> > Are you saying that ext4 and others do not react to crash reports from
> > image fuzzing which result in crash/hang?
>
> We are reacting to them, but not with such an urgency this paragraph seems
> to suggest :).
>
> > Can you suggest a more relaxed clause or should I remove it altogether?
>
> I definitely want to keep a clause like this. Maybe I'd just reformulate it
> like:
>
>   - Handle security issues promptly.  Both those reported by ordinary users
>     as well as those reported by fuzzing tools. Expect that your filesystem
>     will be subject to syscall fuzzing as well as filesystem image fuzzing.
>     Dealing with maliciously corrupted filesystem images is not generally
>     considered a high severity security issue but still it is considered a
>     quality-of-implementation issue that should be fixed.
>

I can take this version, but tbh feels like debating this clause misses
the main goal of the doc, so I'd rather go with something a lot shorter:

- Handle security issues and regression promptly.  Both those reported
  by ordinary users as well as those reported by test bots.

IMO, getting into more details doesn't really add much value to the
prospect reader of the doc before submitting a new filesystem nor to
the filesystem reviewer.

Thanks,
Amir.

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

[Christian Brauner]

On Fri, Apr 17, 2026 at 04:25:03PM +0200, Amir Goldstein wrote:
> This document is motivated by the ongoing maintenance burden that
> abandoned and untestable filesystems impose on VFS developers, blocking
> infrastructure changes such as folio conversions and iomap migration.
> 
> This week alone, two new filesystems were proposed on linux-fsdevel
> (VMUFAT and FTRFS), highlighting the need for documented guidelines
> that new filesystem authors can refer to before submission.
> 
> Multiple recent discussions on linux-fsdevel have touched on the
> criteria for merging new filesystems and for deprecating old ones,
> covering topics such as modern VFS interface adoption, testability,
> userspace utilities, maintainer commitment, and user base viability.
> 
> Add Documentation/filesystems/adding-new-filesystems.rst describing
> the technical requirements and community expectations for merging a
> new filesystem into the kernel.  The guidelines cover:
> - Alternatives to consider before proposing a new in-kernel filesystem
> - Technical requirements: modern VFS interfaces (iomap, folios,
>   fs_context mount API), testability, and userspace utilities
> - Community expectations: identified maintainers, demonstrated
>   commitment, sustained backing, and a clear user base
> - Ongoing obligations after merging, including the risk of deprecation
>   for unmaintained filesystems
> 
> Link: https://lore.kernel.org/linux-fsdevel/20260411151155.321214-1-adrianmcmenamin@gmail.com/
> Link: https://lore.kernel.org/linux-fsdevel/20260413142357.515792-1-aurelien@hackers.camp/
> Link: https://lore.kernel.org/linux-fsdevel/yndtg2jbj55fzd2kkhsmel4pp5ll5xfvfiaqh24tdct3jiqosd@jzbfzf3rrxrd/
> Link: https://lore.kernel.org/linux-fsdevel/20260124091742.GA43313@macsyma.local/
> Link: https://lore.kernel.org/lkml/20260111140345.3866-1-linkinjeon@kernel.org/
> Cc: Christian Brauner <brauner@kernel.org>
> Cc: Alexander Viro <viro@zeniv.linux.org.uk>
> Cc: Jan Kara <jack@suse.cz>
> Cc: Theodore Tso <tytso@mit.edu>
> Cc: Christoph Hellwig <hch@lst.de>
> Cc: Darrick J. Wong <djwong@kernel.org>
> Cc: Matthew Wilcox <willy@infradead.org>
> Assisted-by: Cursor:claude-4-opus
> Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> ---

I'm all on board with this. I think this is worth doing and I think we
need a better process than the "just send it and see what sticks" model
and throw the whole community off the cliff at the same time.

> Hi folks,
> 
> I am posting this patch as a placeholder for a TOPIC discussion at LSFMM.
> This is a reoccurring topic on fsdevel and in LSFMM, but I think it is
> worth having, because I do not think we have made a significant progress
> in solving the vfs maintenance burden problem.
> 
> As much as I hate manifests and even more so discussions about
> manifests, I think that having a document like this will at least save
> us some time in writing the bounce emails.
> 
> Please try not to make this a discussion about a legal document!
> 
> Note that LLM has helped me collect the relevant discussions and
> articulate our collective feedbacks into a summary.
> 
> Note that same LLM makes it much easier for random people to
> submit new filesystems, so we may need to work harder in the near
> future on push backs...
> 
> Thanks,
> Amir.
> 
> 
>  .../filesystems/adding-new-filesystems.rst    | 167 ++++++++++++++++++
>  Documentation/filesystems/index.rst           |   1 +
>  2 files changed, 168 insertions(+)
>  create mode 100644 Documentation/filesystems/adding-new-filesystems.rst
> 
> diff --git a/Documentation/filesystems/adding-new-filesystems.rst b/Documentation/filesystems/adding-new-filesystems.rst
> new file mode 100644
> index 0000000000000..2e59b7127c05f
> --- /dev/null
> +++ b/Documentation/filesystems/adding-new-filesystems.rst
> @@ -0,0 +1,167 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _adding_new_filesystems:
> +
> +Adding New Filesystems
> +======================
> +
> +This document describes what is involved in adding a new filesystem to the
> +Linux kernel, over and above the normal submission advice in
> +:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` and
> +:ref:`Documentation/process/submit-checklist.rst <submitchecklist>`.
> +
> +Every filesystem merged into the kernel becomes the collective responsibility
> +of the VFS maintainers and the wider filesystem development community.
> +Experience has shown that filesystems which become unmaintained impose a
> +significant and ongoing burden: they are hard or impossible to test, they
> +block infrastructure changes because someone must update or preserve old APIs
> +for code that nobody is actively looking after, and they accumulate unfixed
> +bugs.  The requirements and expectations described here are informed by this
> +experience and are intended to ensure that new filesystems enter the kernel
> +on a sustainable footing.
> +
> +
> +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.
> +
> +
> +Technical Requirements
> +----------------------
> +
> +New filesystems are expected to use current kernel interfaces and practices.

We can be stronger here and use "must" use current kernel interfaces and
practices. There's no need to accept a new filesystem if it would in any
way needlessly prolong the existency of legacy internal apis.

> +Submitting a filesystem built on outdated APIs creates an immediate
> +maintenance debt and is likely to face pushback during review.

"Submitting a filesystem built on outdated APIs creates an unacceptable
maintenance debt."

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

I think we can compile a list of must-haves.

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

Tbh, I'd rather have at least two but given past experiences but
probably not something we need to consistently enforce here.

> +
> +Demonstrated commitment
> +  A track record of maintaining kernel code -- for example, in other
> +  subsystems -- significantly strengthens the case for a new filesystem.
> +  Maintainers who are already known and trusted within the community face
> +  less friction during review.
> +
> +Sustained backing
> +  Major filesystems in Linux have organizational or corporate support behind
> +  their development.  Filesystems that depend entirely on volunteer effort
> +  face higher scrutiny about their long-term viability.
> +
> +Responsiveness
> +  The maintainer is expected to respond to bug reports, address review
> +  feedback, and adapt the filesystem to VFS infrastructure changes such as
> +  folio conversions, iomap migration, and mount API updates.  Unresponsive
> +  maintainership is one of the primary reasons filesystems end up on the
> +  path to deprecation.
> +
> +User base
> +  Clearly describe who the users of this filesystem are and the scale of the
> +  user base.  Filesystems with a very small or unclear user base face a
> +  harder path to acceptance and a higher risk of future deprecation.
> +
> +A practical way to demonstrate many of the qualities above is to maintain the
> +filesystem out-of-tree for a period before requesting a merge.  This shows
> +sustained commitment, builds a visible user base, and gives reviewers
> +confidence that the code and its maintainer will persist after merging.
> +That said, it is recognized that for some filesystems the user base grows
> +significantly only after upstreaming, so a compelling case for expected
> +adoption can substitute for a large existing user base.
> +
> +
> +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.
> +
> +
> +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.
> diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
> index f4873197587df..10e40cc9cbc9d 100644
> --- a/Documentation/filesystems/index.rst
> +++ b/Documentation/filesystems/index.rst
> @@ -42,6 +42,7 @@ algorithms work.
>     caching/index
>  
>     porting
> +   adding-new-filesystems
>  
>  Filesystem support layers
>  =========================
> -- 
> 2.53.0
> 

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

[Amir Goldstein]

On Tue, Apr 21, 2026 at 1:27 PM Christian Brauner <brauner@kernel.org> wrote:
>
> On Fri, Apr 17, 2026 at 04:25:03PM +0200, Amir Goldstein wrote:
> > This document is motivated by the ongoing maintenance burden that
> > abandoned and untestable filesystems impose on VFS developers, blocking
> > infrastructure changes such as folio conversions and iomap migration.
> >
> > This week alone, two new filesystems were proposed on linux-fsdevel
> > (VMUFAT and FTRFS), highlighting the need for documented guidelines
> > that new filesystem authors can refer to before submission.
> >
> > Multiple recent discussions on linux-fsdevel have touched on the
> > criteria for merging new filesystems and for deprecating old ones,
> > covering topics such as modern VFS interface adoption, testability,
> > userspace utilities, maintainer commitment, and user base viability.
> >
> > Add Documentation/filesystems/adding-new-filesystems.rst describing
> > the technical requirements and community expectations for merging a
> > new filesystem into the kernel.  The guidelines cover:
> > - Alternatives to consider before proposing a new in-kernel filesystem
> > - Technical requirements: modern VFS interfaces (iomap, folios,
> >   fs_context mount API), testability, and userspace utilities
> > - Community expectations: identified maintainers, demonstrated
> >   commitment, sustained backing, and a clear user base
> > - Ongoing obligations after merging, including the risk of deprecation
> >   for unmaintained filesystems
> >
> > Link: https://lore.kernel.org/linux-fsdevel/20260411151155.321214-1-adrianmcmenamin@gmail.com/
> > Link: https://lore.kernel.org/linux-fsdevel/20260413142357.515792-1-aurelien@hackers.camp/
> > Link: https://lore.kernel.org/linux-fsdevel/yndtg2jbj55fzd2kkhsmel4pp5ll5xfvfiaqh24tdct3jiqosd@jzbfzf3rrxrd/
> > Link: https://lore.kernel.org/linux-fsdevel/20260124091742.GA43313@macsyma.local/
> > Link: https://lore.kernel.org/lkml/20260111140345.3866-1-linkinjeon@kernel.org/
> > Cc: Christian Brauner <brauner@kernel.org>
> > Cc: Alexander Viro <viro@zeniv.linux.org.uk>
> > Cc: Jan Kara <jack@suse.cz>
> > Cc: Theodore Tso <tytso@mit.edu>
> > Cc: Christoph Hellwig <hch@lst.de>
> > Cc: Darrick J. Wong <djwong@kernel.org>
> > Cc: Matthew Wilcox <willy@infradead.org>
> > Assisted-by: Cursor:claude-4-opus
> > Signed-off-by: Amir Goldstein <amir73il@gmail.com>
> > ---
>
> I'm all on board with this. I think this is worth doing and I think we
> need a better process than the "just send it and see what sticks" model
> and throw the whole community off the cliff at the same time.
>
> > Hi folks,
> >
> > I am posting this patch as a placeholder for a TOPIC discussion at LSFMM.
> > This is a reoccurring topic on fsdevel and in LSFMM, but I think it is
> > worth having, because I do not think we have made a significant progress
> > in solving the vfs maintenance burden problem.
> >
> > As much as I hate manifests and even more so discussions about
> > manifests, I think that having a document like this will at least save
> > us some time in writing the bounce emails.
> >
> > Please try not to make this a discussion about a legal document!
> >
> > Note that LLM has helped me collect the relevant discussions and
> > articulate our collective feedbacks into a summary.
> >
> > Note that same LLM makes it much easier for random people to
> > submit new filesystems, so we may need to work harder in the near
> > future on push backs...
> >
> > Thanks,
> > Amir.
> >
> >
> >  .../filesystems/adding-new-filesystems.rst    | 167 ++++++++++++++++++
> >  Documentation/filesystems/index.rst           |   1 +
> >  2 files changed, 168 insertions(+)
> >  create mode 100644 Documentation/filesystems/adding-new-filesystems.rst
> >
> > diff --git a/Documentation/filesystems/adding-new-filesystems.rst b/Documentation/filesystems/adding-new-filesystems.rst
> > new file mode 100644
> > index 0000000000000..2e59b7127c05f
> > --- /dev/null
> > +++ b/Documentation/filesystems/adding-new-filesystems.rst
> > @@ -0,0 +1,167 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +.. _adding_new_filesystems:
> > +
> > +Adding New Filesystems
> > +======================
> > +
> > +This document describes what is involved in adding a new filesystem to the
> > +Linux kernel, over and above the normal submission advice in
> > +:ref:`Documentation/process/submitting-patches.rst <submittingpatches>` and
> > +:ref:`Documentation/process/submit-checklist.rst <submitchecklist>`.
> > +
> > +Every filesystem merged into the kernel becomes the collective responsibility
> > +of the VFS maintainers and the wider filesystem development community.
> > +Experience has shown that filesystems which become unmaintained impose a
> > +significant and ongoing burden: they are hard or impossible to test, they
> > +block infrastructure changes because someone must update or preserve old APIs
> > +for code that nobody is actively looking after, and they accumulate unfixed
> > +bugs.  The requirements and expectations described here are informed by this
> > +experience and are intended to ensure that new filesystems enter the kernel
> > +on a sustainable footing.
> > +
> > +
> > +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.
> > +
> > +
> > +Technical Requirements
> > +----------------------
> > +
> > +New filesystems are expected to use current kernel interfaces and practices.
>
> We can be stronger here and use "must" use current kernel interfaces and
> practices. There's no need to accept a new filesystem if it would in any
> way needlessly prolong the existency of legacy internal apis.
>

Sure.

> > +Submitting a filesystem built on outdated APIs creates an immediate
> > +maintenance debt and is likely to face pushback during review.
>
> "Submitting a filesystem built on outdated APIs creates an unacceptable
> maintenance debt."
>

Agreed.

> > +
> > +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.
>
> I think we can compile a list of must-haves.
>

I think that's a case of less is more.
Getting the doc merged with minimal guidelines does the job IMO.
Adding more will not add much value IMO.

> > +
> > +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.
> > +
> > +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.
> > +
> > +
> > +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.
>
> Tbh, I'd rather have at least two but given past experiences but
> probably not something we need to consistently enforce here.
>

Absolutely. Matthew already commented and I fixed in v2.

Feel free to review the latest rev on github:
https://github.com/amir73il/linux/blob/vfs-docs/Documentation/filesystems/adding-new-filesystems.rst

Thanks,
Amir.

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

[Jan Kara]

On Tue 21-04-26 13:17:34, Amir Goldstein wrote:
> On Tue, Apr 21, 2026 at 12:16 PM Jan Kara <jack@suse.cz> wrote:
> > I definitely want to keep a clause like this. Maybe I'd just reformulate it
> > like:
> >
> >   - Handle security issues promptly.  Both those reported by ordinary users
> >     as well as those reported by fuzzing tools. Expect that your filesystem
> >     will be subject to syscall fuzzing as well as filesystem image fuzzing.
> >     Dealing with maliciously corrupted filesystem images is not generally
> >     considered a high severity security issue but still it is considered a
> >     quality-of-implementation issue that should be fixed.
> >
> 
> I can take this version, but tbh feels like debating this clause misses
> the main goal of the doc, so I'd rather go with something a lot shorter:
> 
> - Handle security issues and regression promptly.  Both those reported
>   by ordinary users as well as those reported by test bots.
> 
> IMO, getting into more details doesn't really add much value to the
> prospect reader of the doc before submitting a new filesystem nor to
> the filesystem reviewer.

Agreed. Your shorter version conveys the idea and the details aren't that
useful. So the short version is fine.

								Honza

-- 
Jan Kara <jack@suse.com>
SUSE Labs, CR

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

[Darrick J. Wong]

On Tue, Apr 21, 2026 at 02:08:13PM +0200, Jan Kara wrote:
> On Tue 21-04-26 13:17:34, Amir Goldstein wrote:
> > On Tue, Apr 21, 2026 at 12:16 PM Jan Kara <jack@suse.cz> wrote:
> > > I definitely want to keep a clause like this. Maybe I'd just reformulate it
> > > like:
> > >
> > >   - Handle security issues promptly.  Both those reported by ordinary users
> > >     as well as those reported by fuzzing tools. Expect that your filesystem
> > >     will be subject to syscall fuzzing as well as filesystem image fuzzing.
> > >     Dealing with maliciously corrupted filesystem images is not generally
> > >     considered a high severity security issue but still it is considered a
> > >     quality-of-implementation issue that should be fixed.
> > >
> > 
> > I can take this version, but tbh feels like debating this clause misses
> > the main goal of the doc, so I'd rather go with something a lot shorter:
> > 
> > - Handle security issues and regression promptly.  Both those reported
> >   by ordinary users as well as those reported by test bots.
> > 
> > IMO, getting into more details doesn't really add much value to the
> > prospect reader of the doc before submitting a new filesystem nor to
> > the filesystem reviewer.
> 
> Agreed. Your shorter version conveys the idea and the details aren't that
> useful. So the short version is fine.

I still want

"The filesystem must handle corrupted input gracefully without hanging
or crashing the kernel."

to be part of this.  Not screwing over a running system is important,
The guidelines ought to make that explicit.

--D

> 
> 								Honza
> 
> -- 
> Jan Kara <jack@suse.com>
> SUSE Labs, CR

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

[Amir Goldstein]

On Tue, Apr 21, 2026 at 8:10 PM Darrick J. Wong <djwong@kernel.org> wrote:
>
> On Tue, Apr 21, 2026 at 02:08:13PM +0200, Jan Kara wrote:
> > On Tue 21-04-26 13:17:34, Amir Goldstein wrote:
> > > On Tue, Apr 21, 2026 at 12:16 PM Jan Kara <jack@suse.cz> wrote:
> > > > I definitely want to keep a clause like this. Maybe I'd just reformulate it
> > > > like:
> > > >
> > > >   - Handle security issues promptly.  Both those reported by ordinary users
> > > >     as well as those reported by fuzzing tools. Expect that your filesystem
> > > >     will be subject to syscall fuzzing as well as filesystem image fuzzing.
> > > >     Dealing with maliciously corrupted filesystem images is not generally
> > > >     considered a high severity security issue but still it is considered a
> > > >     quality-of-implementation issue that should be fixed.
> > > >
> > >
> > > I can take this version, but tbh feels like debating this clause misses
> > > the main goal of the doc, so I'd rather go with something a lot shorter:
> > >
> > > - Handle security issues and regression promptly.  Both those reported
> > >   by ordinary users as well as those reported by test bots.
> > >
> > > IMO, getting into more details doesn't really add much value to the
> > > prospect reader of the doc before submitting a new filesystem nor to
> > > the filesystem reviewer.
> >
> > Agreed. Your shorter version conveys the idea and the details aren't that
> > useful. So the short version is fine.
>
> I still want
>
> "The filesystem must handle corrupted input gracefully without hanging
> or crashing the kernel."
>
> to be part of this.  Not screwing over a running system is important,
> The guidelines ought to make that explicit.

Agree.

 - Handle security issues and regression promptly.  Both those reported
   by ordinary users and those reported by test bots and fuzzing tools.
   The filesystem must handle corrupted input gracefully without hanging
   or crashing the kernel.

Thanks,
Amir.

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

[Darrick J. Wong]

On Tue, Apr 21, 2026 at 09:42:23PM +0200, Amir Goldstein wrote:
> On Tue, Apr 21, 2026 at 8:10 PM Darrick J. Wong <djwong@kernel.org> wrote:
> >
> > On Tue, Apr 21, 2026 at 02:08:13PM +0200, Jan Kara wrote:
> > > On Tue 21-04-26 13:17:34, Amir Goldstein wrote:
> > > > On Tue, Apr 21, 2026 at 12:16 PM Jan Kara <jack@suse.cz> wrote:
> > > > > I definitely want to keep a clause like this. Maybe I'd just reformulate it
> > > > > like:
> > > > >
> > > > >   - Handle security issues promptly.  Both those reported by ordinary users
> > > > >     as well as those reported by fuzzing tools. Expect that your filesystem
> > > > >     will be subject to syscall fuzzing as well as filesystem image fuzzing.
> > > > >     Dealing with maliciously corrupted filesystem images is not generally
> > > > >     considered a high severity security issue but still it is considered a
> > > > >     quality-of-implementation issue that should be fixed.
> > > > >
> > > >
> > > > I can take this version, but tbh feels like debating this clause misses
> > > > the main goal of the doc, so I'd rather go with something a lot shorter:
> > > >
> > > > - Handle security issues and regression promptly.  Both those reported
> > > >   by ordinary users as well as those reported by test bots.
> > > >
> > > > IMO, getting into more details doesn't really add much value to the
> > > > prospect reader of the doc before submitting a new filesystem nor to
> > > > the filesystem reviewer.
> > >
> > > Agreed. Your shorter version conveys the idea and the details aren't that
> > > useful. So the short version is fine.
> >
> > I still want
> >
> > "The filesystem must handle corrupted input gracefully without hanging
> > or crashing the kernel."
> >
> > to be part of this.  Not screwing over a running system is important,
> > The guidelines ought to make that explicit.
> 
> Agree.
> 
>  - Handle security issues and regression promptly.  Both those reported
>    by ordinary users and those reported by test bots and fuzzing tools.
>    The filesystem must handle corrupted input gracefully without hanging
>    or crashing the kernel.

How about
"...without corrupting memory, hanging, or crashing the kernel."

--D

> 
> Thanks,
> Amir.

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

[Amir Goldstein]

On Tue, Apr 21, 2026 at 10:15 PM Darrick J. Wong <djwong@kernel.org> wrote:
>
> On Tue, Apr 21, 2026 at 09:42:23PM +0200, Amir Goldstein wrote:
> > On Tue, Apr 21, 2026 at 8:10 PM Darrick J. Wong <djwong@kernel.org> wrote:
> > >
> > > On Tue, Apr 21, 2026 at 02:08:13PM +0200, Jan Kara wrote:
> > > > On Tue 21-04-26 13:17:34, Amir Goldstein wrote:
> > > > > On Tue, Apr 21, 2026 at 12:16 PM Jan Kara <jack@suse.cz> wrote:
> > > > > > I definitely want to keep a clause like this. Maybe I'd just reformulate it
> > > > > > like:
> > > > > >
> > > > > >   - Handle security issues promptly.  Both those reported by ordinary users
> > > > > >     as well as those reported by fuzzing tools. Expect that your filesystem
> > > > > >     will be subject to syscall fuzzing as well as filesystem image fuzzing.
> > > > > >     Dealing with maliciously corrupted filesystem images is not generally
> > > > > >     considered a high severity security issue but still it is considered a
> > > > > >     quality-of-implementation issue that should be fixed.
> > > > > >
> > > > >
> > > > > I can take this version, but tbh feels like debating this clause misses
> > > > > the main goal of the doc, so I'd rather go with something a lot shorter:
> > > > >
> > > > > - Handle security issues and regression promptly.  Both those reported
> > > > >   by ordinary users as well as those reported by test bots.
> > > > >
> > > > > IMO, getting into more details doesn't really add much value to the
> > > > > prospect reader of the doc before submitting a new filesystem nor to
> > > > > the filesystem reviewer.
> > > >
> > > > Agreed. Your shorter version conveys the idea and the details aren't that
> > > > useful. So the short version is fine.
> > >
> > > I still want
> > >
> > > "The filesystem must handle corrupted input gracefully without hanging
> > > or crashing the kernel."
> > >
> > > to be part of this.  Not screwing over a running system is important,
> > > The guidelines ought to make that explicit.
> >
> > Agree.
> >
> >  - Handle security issues and regression promptly.  Both those reported
> >    by ordinary users and those reported by test bots and fuzzing tools.
> >    The filesystem must handle corrupted input gracefully without hanging
> >    or crashing the kernel.
>
> How about
> "...without corrupting memory, hanging, or crashing the kernel."
>

Sure. works for me.

Thanks,
Amir.

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

[Askar Safin]

Amir Goldstein <amir73il@gmail.com>:
> +  and the filesystem context API (``fs_context``) for the mount path.  See

There is no need to say this, because there is no other code paths since
this commit: https://lore.kernel.org/all/20251212174403.2882183-1-sandeen@redhat.com/

-- 
Askar Safin

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

[Amir Goldstein]

On Wed, Apr 22, 2026 at 10:51 AM Askar Safin <safinaskar@gmail.com> wrote:
>
> Amir Goldstein <amir73il@gmail.com>:
> > +  and the filesystem context API (``fs_context``) for the mount path.  See
>
> There is no need to say this, because there is no other code paths since
> this commit: https://lore.kernel.org/all/20251212174403.2882183-1-sandeen@redhat.com/

Right, I forgot that :)

Christian,

Do you want to leave something else in place of this?
Did you have anything in mind when you wrote
"I think we can compile a list of must-haves."?

Thanks,
Amir.

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

[Christian Brauner]

On Wed, Apr 22, 2026 at 11:02:56AM +0200, Amir Goldstein wrote:
> On Wed, Apr 22, 2026 at 10:51 AM Askar Safin <safinaskar@gmail.com> wrote:
> >
> > Amir Goldstein <amir73il@gmail.com>:
> > > +  and the filesystem context API (``fs_context``) for the mount path.  See
> >
> > There is no need to say this, because there is no other code paths since
> > this commit: https://lore.kernel.org/all/20251212174403.2882183-1-sandeen@redhat.com/
> 
> Right, I forgot that :)
> 
> Christian,
> 
> Do you want to leave something else in place of this?
> Did you have anything in mind when you wrote
> "I think we can compile a list of must-haves."?

No, just that we need to keep updating it.
I think our biggest items right are from the mm area (folios) and
block-ish area (iomap). That list will grow though I'm certain.

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

[Theodore Tso]

> > >  - Handle security issues and regression promptly.  Both those reported
> > >    by ordinary users and those reported by test bots and fuzzing tools.
> > >    The filesystem must handle corrupted input gracefully without hanging
> > >    or crashing the kernel.
> >
> > How about
> > "...without corrupting memory, hanging, or crashing the kernel."

I will note that security@kernel.org does not consider maliciously
fuzzed file systems as a security issue.  And a long-standing position
by both ext4 and xfs has been that distributions configuring
automounters to blindly mount USB sticks dropped in the parking lot by
the KGB, MSS, or NSA is a Bad Idea.

I'm a bit nervous about stating this as an expectation, especially
given denial of service attacks on maintainer time with a large number
of random academics which fork syzkaller, and send security reports
that mostly duplicate upstream syzkaller reports and don't support the
web site allowing developers to test syzkaller exports which don't
reproduce locally.

It's certainly an ideal, but I'm not sure it's one we can expect or
guarantee.  It's also certainly not the case on most file systems
in-tree today, to a varying degrees, but outside of the most highly
maintained file systems, if we were to state this, (a) I'd be
concerned that we would be setting expectations that will disappoint
Linux users, or worse, class-action lawyers (well, they would be
rubbing their hands with glee), and (b) if we actually enforced it,
would probably result in 90% of the current in-tree file systems
getting removed.

						- Ted

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

[Amir Goldstein]

On Wed, Apr 22, 2026 at 4:10 PM Theodore Tso <tytso@mit.edu> wrote:
>
> > > >  - Handle security issues and regression promptly.  Both those reported
> > > >    by ordinary users and those reported by test bots and fuzzing tools.
> > > >    The filesystem must handle corrupted input gracefully without hanging
> > > >    or crashing the kernel.
> > >
> > > How about
> > > "...without corrupting memory, hanging, or crashing the kernel."
>
> I will note that security@kernel.org does not consider maliciously
> fuzzed file systems as a security issue.  And a long-standing position
> by both ext4 and xfs has been that distributions configuring
> automounters to blindly mount USB sticks dropped in the parking lot by
> the KGB, MSS, or NSA is a Bad Idea.
>
> I'm a bit nervous about stating this as an expectation, especially
> given denial of service attacks on maintainer time with a large number
> of random academics which fork syzkaller, and send security reports
> that mostly duplicate upstream syzkaller reports and don't support the
> web site allowing developers to test syzkaller exports which don't
> reproduce locally.
>
> It's certainly an ideal, but I'm not sure it's one we can expect or
> guarantee.  It's also certainly not the case on most file systems
> in-tree today, to a varying degrees, but outside of the most highly
> maintained file systems, if we were to state this, (a) I'd be
> concerned that we would be setting expectations that will disappoint
> Linux users, or worse, class-action lawyers (well, they would be
> rubbing their hands with glee), and (b) if we actually enforced it,
> would probably result in 90% of the current in-tree file systems
> getting removed.

This is a sentence that I removed and Darrick asked me to
add it back, because "Not screwing over a running system is
important, The guidelines ought to make that explicit."

"The filesystem must handle corrupted input gracefully
 without corrupting memory, hanging or crashing the kernel."

Please suggest a variant which you are comfortable with and
captures the sentiment that Darrick wished to express.

Thanks,
Amir.

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

[Darrick J. Wong]

On Wed, Apr 22, 2026 at 04:35:15PM +0200, Amir Goldstein wrote:
> On Wed, Apr 22, 2026 at 4:10 PM Theodore Tso <tytso@mit.edu> wrote:
> >
> > > > >  - Handle security issues and regression promptly.  Both those reported
> > > > >    by ordinary users and those reported by test bots and fuzzing tools.
> > > > >    The filesystem must handle corrupted input gracefully without hanging
> > > > >    or crashing the kernel.
> > > >
> > > > How about
> > > > "...without corrupting memory, hanging, or crashing the kernel."
> >
> > I will note that security@kernel.org does not consider maliciously
> > fuzzed file systems as a security issue.  And a long-standing position
> > by both ext4 and xfs has been that distributions configuring
> > automounters to blindly mount USB sticks dropped in the parking lot by
> > the KGB, MSS, or NSA is a Bad Idea.
> >
> > I'm a bit nervous about stating this as an expectation, especially
> > given denial of service attacks on maintainer time with a large number
> > of random academics which fork syzkaller, and send security reports
> > that mostly duplicate upstream syzkaller reports and don't support the
> > web site allowing developers to test syzkaller exports which don't
> > reproduce locally.
> >
> > It's certainly an ideal, but I'm not sure it's one we can expect or
> > guarantee.  It's also certainly not the case on most file systems
> > in-tree today, to a varying degrees, but outside of the most highly
> > maintained file systems, if we were to state this, (a) I'd be
> > concerned that we would be setting expectations that will disappoint
> > Linux users, or worse, class-action lawyers (well, they would be
> > rubbing their hands with glee), and (b) if we actually enforced it,
> > would probably result in 90% of the current in-tree file systems
> > getting removed.

Is that such a bad thing?  Reducing the kernel attack surface by that
much would be a blessing, because any missteps in the kernel means it's
game over for the entire running system.

It's also a blessing for anyone trying to do core code changes ala
willy's folio conversion project.

> This is a sentence that I removed and Darrick asked me to
> add it back, because "Not screwing over a running system is
> important, The guidelines ought to make that explicit."
> 
> "The filesystem must handle corrupted input gracefully
>  without corrupting memory, hanging or crashing the kernel."
> 
> Please suggest a variant which you are comfortable with and
> captures the sentiment that Darrick wished to express.

I'm willing to relax on the "not hanging" part since it /is/ difficult
to detect inter-fsblock loops, and the solution that I thought I had
found (attach xfs_bufs to empty xfs transaction, look for obvious
clues in xfs_buf) is apparently no longer viewed favorably by dchinner.

https://lore.kernel.org/linux-xfs/Zw8ulrPaeXw8bUnd@dread.disaster.area/

Implementing a full-on cycle detector in xfs_btree *would* be a fun
project for someone who really wants to dig in to btrees, however.

--D