Skip to contentSkip to conversation

docs: add guidelines for submitting new filesystems

PATCH Superseded Amir Goldstein 8 participants 28 messages Apr 17 – Apr 22

Subsystems (2)

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 docs: add guidelines for submitting new filesystems

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

---

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
Documentation/filesystems/adding-new-filesystems.rst new file +167 -0
new file mode 100644
index 0000000000000..2e59b7127c05f
@@ -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
+(``[email protected]``).  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.
Documentation/filesystems/index.rst +1 -0
index f4873197587df..10e40cc9cbc9d 100644
@@ -42,6 +42,7 @@ algorithms work.
    caching/index
 
    porting
+   adding-new-filesystems
 
 Filesystem support layers
 =========================
Signature · 1 line
2.53.0
#1 lore raw

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

Quoted 8 lines · Amir Goldstein
Documentation/filesystems/adding-new-filesystems.rst new file +8 -0
+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

Documentation/filesystems/adding-new-filesystems.rst line 41

Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +10 -0
+   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.

Quoted 9 lines
Documentation/filesystems/adding-new-filesystems.rst new file +9 -0
+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

Documentation/filesystems/adding-new-filesystems.rst line 62

Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +10 -0
+  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.

Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +10 -0
+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>`_

Documentation/filesystems/adding-new-filesystems.rst line 83

Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +10 -0
+  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.

Documentation/filesystems/adding-new-filesystems.rst line 97

Quoted 12 lines
Documentation/filesystems/adding-new-filesystems.rst new file +12 -0
+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.

Quoted 4 lines
Documentation/filesystems/adding-new-filesystems.rst new file +4 -0
+Submission Process
+------------------
+
+Send patches to the linux-fsdevel mailing list

Documentation/filesystems/adding-new-filesystems.rst line 144

Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +10 -0
+(``[email protected]``).  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, ...

Quoted 11 lines
Documentation/filesystems/adding-new-filesystems.rst new file +11 -0
+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

Documentation/filesystems/adding-new-filesystems.rst line 167

Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +10 -0
+   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.

#2 lore raw
Quoted 20 lines · Matthew Wilcox

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

Quoted 15 lines · Amir Goldstein
Documentation/filesystems/adding-new-filesystems.rst new file +15 -0
+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.
+
Quoted 8 lines

Documentation/filesystems/adding-new-filesystems.rst line 41

Quoted 3 lines

+ - If kernel-level performance, reliability, or integration is genuinely

Documentation/filesystems/adding-new-filesystems.rst new file +2 -0
+   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...

Quoted 115 lines
Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +9 -0
+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

Documentation/filesystems/adding-new-filesystems.rst line 62

Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +10 -0
+  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.

Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +10 -0
+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>`_

Documentation/filesystems/adding-new-filesystems.rst line 83

Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +10 -0
+  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.

Documentation/filesystems/adding-new-filesystems.rst line 97

Quoted 12 lines
Documentation/filesystems/adding-new-filesystems.rst new file +12 -0
+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.

Quoted 4 lines
Documentation/filesystems/adding-new-filesystems.rst new file +4 -0
+Submission Process
+------------------
+
+Send patches to the linux-fsdevel mailing list

Documentation/filesystems/adding-new-filesystems.rst line 144

Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +10 -0
+(``[email protected]``).  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, ...

Quoted 19 lines
Documentation/filesystems/adding-new-filesystems.rst new file +19 -0
+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
Quoted 9 lines

Documentation/filesystems/adding-new-filesystems.rst line 167

Quoted 2 lines
Documentation/filesystems/adding-new-filesystems.rst new file +2 -0
+   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.

#3 lore raw
In reply to Matthew Wilcox
Quoted 75 lines · Matthew Wilcox

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

Quoted 8 lines · Amir Goldstein
Documentation/filesystems/adding-new-filesystems.rst new file +8 -0
+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

Documentation/filesystems/adding-new-filesystems.rst line 41

Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +10 -0
+   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.

Quoted 9 lines
Documentation/filesystems/adding-new-filesystems.rst new file +9 -0
+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

Documentation/filesystems/adding-new-filesystems.rst line 62

Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +10 -0
+  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.

Quoted 18 lines
Documentation/filesystems/adding-new-filesystems.rst new file +18 -0
+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
Quoted 8 lines

Documentation/filesystems/adding-new-filesystems.rst line 83

Quoted 2 lines
Documentation/filesystems/adding-new-filesystems.rst new file +2 -0
+  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.

Quoted 68 lines

Documentation/filesystems/adding-new-filesystems.rst line 97

Quoted 13 lines
Documentation/filesystems/adding-new-filesystems.rst new file +12 -0
+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.

Quoted 4 lines
Documentation/filesystems/adding-new-filesystems.rst new file +4 -0
+Submission Process
+------------------
+
+Send patches to the linux-fsdevel mailing list

Documentation/filesystems/adding-new-filesystems.rst line 144

Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +10 -0
+(``[email protected]``).  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, ...

Quoted 11 lines
Documentation/filesystems/adding-new-filesystems.rst new file +11 -0
+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

Documentation/filesystems/adding-new-filesystems.rst line 167

Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +10 -0
+   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.

#4 lore raw
Quoted 3 lines · Jaegeuk Kim
Quoted 1 line · Matthew Wilcox

...

Quoted 10 lines
Quoted 5 lines

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.

#5 lore raw
Quoted 37 lines · Amir Goldstein
Quoted 3 lines · Jaegeuk Kim
Quoted 1 line · Matthew Wilcox

...

Quoted 10 lines
Quoted 5 lines

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.

Quoted 4 lines

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

Quoted 3 lines

Thanks,
Amir.

#6 lore raw
Quoted 44 lines · Jaegeuk Kim
Quoted 37 lines · Amir Goldstein
Quoted 3 lines · Jaegeuk Kim
Quoted 1 line · Matthew Wilcox

...

Quoted 10 lines
Quoted 5 lines

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.

Quoted 4 lines

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

Quoted 9 lines

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.

#7 lore raw
In reply to Amir Goldstein

Documentation/filesystems/adding-new-filesystems.rst line 78

Quoted 8 lines · Amir Goldstein
Documentation/filesystems/adding-new-filesystems.rst new file +8 -0
+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.

#8 lore raw
Quoted 23 lines · Matthew Wilcox

Documentation/filesystems/adding-new-filesystems.rst line 78

Quoted 8 lines · Amir Goldstein
Documentation/filesystems/adding-new-filesystems.rst new file +8 -0
+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.

Quoted 1 line

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.

reviewer
#9 lore raw
In reply to Matthew Wilcox
Quoted 12 lines · Matthew Wilcox

Documentation/filesystems/adding-new-filesystems.rst line 78

Quoted 8 lines · Amir Goldstein
Documentation/filesystems/adding-new-filesystems.rst new file +8 -0
+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:

Quoted 9 lines

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

Signature · 2 lines
Jan Kara <[email protected]>
SUSE Labs, CR
reviewer
#10 lore raw
In reply to Amir Goldstein

Documentation/filesystems/adding-new-filesystems.rst line 162

Quoted 3 lines · Amir Goldstein

+ - Handle security issues promptly. Filesystems parse complex on-disk

Documentation/filesystems/adding-new-filesystems.rst new file +2 -0
+   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

Signature · 2 lines
Jan Kara <[email protected]>
SUSE Labs, CR
#11 lore raw
Quoted 6 lines · Jan Kara

Documentation/filesystems/adding-new-filesystems.rst line 162

Quoted 3 lines · Amir Goldstein

+ - Handle security issues promptly. Filesystems parse complex on-disk

Documentation/filesystems/adding-new-filesystems.rst new file +2 -0
+   structures from potentially untrusted media and must treat security
+   reports with urgency.
Quoted 7 lines

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.

#12 lore raw
Quoted 17 lines · Amir Goldstein
Quoted 6 lines · Jan Kara

Documentation/filesystems/adding-new-filesystems.rst line 162

Quoted 3 lines · Amir Goldstein

+ - Handle security issues promptly. Filesystems parse complex on-disk

Documentation/filesystems/adding-new-filesystems.rst new file +2 -0
+   structures from potentially untrusted media and must treat security
+   reports with urgency.
Quoted 7 lines

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:

Quoted 8 lines

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

Quoted 1 line

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

reviewer
#13 lore raw
In reply to Amir Goldstein
Quoted 17 lines · Amir Goldstein
Quoted 6 lines · Jan Kara

Documentation/filesystems/adding-new-filesystems.rst line 162

Quoted 3 lines · Amir Goldstein

+ - Handle security issues promptly. Filesystems parse complex on-disk

Documentation/filesystems/adding-new-filesystems.rst new file +2 -0
+   structures from potentially untrusted media and must treat security
+   reports with urgency.
Quoted 7 lines

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:

Quoted 8 lines

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

Quoted 1 line

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

Signature · 2 lines
Jan Kara <[email protected]>
SUSE Labs, CR
#14 lore raw
Quoted 36 lines · Jan Kara
Quoted 17 lines · Amir Goldstein
Quoted 6 lines · Jan Kara

Documentation/filesystems/adding-new-filesystems.rst line 162

Quoted 3 lines · Amir Goldstein

+ - Handle security issues promptly. Filesystems parse complex on-disk

Documentation/filesystems/adding-new-filesystems.rst new file +2 -0
+   structures from potentially untrusted media and must treat security
+   reports with urgency.
Quoted 7 lines

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:

Quoted 8 lines

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

Quoted 1 line

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:

Quoted 7 lines

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

reviewer
#15 lore raw
Quoted 15 lines · Amir Goldstein
Quoted 10 lines · Jan Kara

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:

Quoted 6 lines

- 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

Signature · 2 lines
Jan Kara <[email protected]>
SUSE Labs, CR
#16 lore raw
Quoted 19 lines · Jan Kara
Quoted 18 lines · Amir Goldstein
Quoted 10 lines · Jan Kara

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.

Quoted 6 lines
Quoted 3 lines

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

Quoted 6 lines

Honza

Signature · 2 lines
Jan Kara <[email protected]>
SUSE Labs, CR
#17 lore raw
Quoted 28 lines · Darrick J. Wong
Quoted 19 lines · Jan Kara
Quoted 18 lines · Amir Goldstein
Quoted 10 lines · Jan Kara

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.

Quoted 6 lines
Quoted 3 lines

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.

Quoted 7 lines

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.

#18 lore raw
Quoted 37 lines · Amir Goldstein
Quoted 28 lines · Darrick J. Wong
Quoted 19 lines · Jan Kara
Quoted 18 lines · Amir Goldstein
Quoted 10 lines · Jan Kara

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.

Quoted 6 lines
Quoted 3 lines

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.

Quoted 7 lines

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.

Quoted 6 lines

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

Quoted 3 lines

Thanks,
Amir.

#19 lore raw
Quoted 41 lines · Darrick J. Wong
Quoted 39 lines · Amir Goldstein
Quoted 28 lines · Darrick J. Wong
Quoted 19 lines · Jan Kara
Quoted 18 lines · Amir Goldstein
Quoted 10 lines · Jan Kara

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.

Quoted 6 lines
Quoted 3 lines

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.

Quoted 7 lines

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.

Quoted 8 lines
Quoted 4 lines

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

#20 lore raw
Quoted 7 lines
Quoted 7 lines
Quoted 4 lines

- 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 [email protected] 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

#21 lore raw
Quoted 22 lines · Theodore Tso
Quoted 8 lines
Quoted 8 lines
Quoted 5 lines

- 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 [email protected] 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.

Quoted 9 lines

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.

#22 lore raw
Quoted 23 lines · Amir Goldstein
Quoted 22 lines · Theodore Tso
Quoted 8 lines
Quoted 8 lines
Quoted 5 lines

- 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 [email protected] 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.

Quoted 9 lines
Quoted 9 lines

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.

Quoted 9 lines

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/[email protected]/

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

#23 lore raw
In reply to Amir Goldstein
Quoted 38 lines · 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

Quoted 1 line

---

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.

Quoted 72 lines

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
Documentation/filesystems/adding-new-filesystems.rst new file +37 -0
new file mode 100644
index 0000000000000..2e59b7127c05f
@@ -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.

Documentation/filesystems/adding-new-filesystems.rst line 47

Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +10 -0
+
+ - 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.

Documentation/filesystems/adding-new-filesystems.rst line 49

Quoted 2 lines
Documentation/filesystems/adding-new-filesystems.rst new file +2 -0
+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."

Documentation/filesystems/adding-new-filesystems.rst line 56

Quoted 7 lines
Documentation/filesystems/adding-new-filesystems.rst new file +7 -0
+
+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.

Quoted 31 lines
Documentation/filesystems/adding-new-filesystems.rst new file +31 -0
+
+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
+-----------------------------------------

Documentation/filesystems/adding-new-filesystems.rst line 97

Quoted 10 lines
Documentation/filesystems/adding-new-filesystems.rst new file +10 -0
+
+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.

Quoted 85 lines
Documentation/filesystems/adding-new-filesystems.rst new file +70 -0
+
+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
+(``[email protected]``).  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.
Documentation/filesystems/index.rst +1 -0
index f4873197587df..10e40cc9cbc9d 100644
@@ -42,6 +42,7 @@ algorithms work.
    caching/index
 
    porting
+   adding-new-filesystems
 
 Filesystem support layers
 =========================
Signature · 1 line
2.53.0
#24 lore raw
Quoted 124 lines · Christian Brauner
Quoted 38 lines · 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

Quoted 1 line

---

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.

Quoted 78 lines

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
Documentation/filesystems/adding-new-filesystems.rst new file +43 -0
new file mode 100644
index 0000000000000..2e59b7127c05f
@@ -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.
+
+
Quoted 9 lines

Documentation/filesystems/adding-new-filesystems.rst line 47

Quoted 4 lines
Documentation/filesystems/adding-new-filesystems.rst new file +4 -0
+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.

Quoted 6 lines

Documentation/filesystems/adding-new-filesystems.rst line 49

Quoted 2 lines
Documentation/filesystems/adding-new-filesystems.rst new file +2 -0
+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.

Quoted 10 lines

Documentation/filesystems/adding-new-filesystems.rst line 56

Quoted 7 lines
Documentation/filesystems/adding-new-filesystems.rst new file +7 -0
+
+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.

Quoted 36 lines
Quoted 36 lines
Documentation/filesystems/adding-new-filesystems.rst new file +36 -0
+
+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.
+
Quoted 9 lines

Documentation/filesystems/adding-new-filesystems.rst line 97

Quoted 5 lines
Documentation/filesystems/adding-new-filesystems.rst new file +5 -0
+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.

#26 lore raw
Quoted 6 lines · Askar Safin

Amir Goldstein <[email protected]>:

Quoted 1 line

+ 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/[email protected]/

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.

#27 lore raw
Quoted 8 lines · Amir Goldstein
Quoted 6 lines · Askar Safin

Amir Goldstein <[email protected]>:

Quoted 1 line

+ 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/[email protected]/

Quoted 7 lines

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.