Re: [RFC PATCH 1/2] Docs/admin-guide/mm/damon/usage: mark scheme filters sysfs dir as deprecated

[SeongJae Park <sj@kernel.org>]

On Tue, 21 Apr 2026 05:04:13 +0000 sashiko-bot@kernel.org wrote:

> Sashiko AI review found 1 potential issue(s):
> - [Low] Poor grammar and inappropriate terminology in the deprecation notice.
> --
> 
> commit bd6da1d76d24f1b76f6957dd9993c899af48df43
> Author: SeongJae Park <sj@kernel.org>
> 
> Docs/admin-guide/mm/damon/usage: mark scheme filters sysfs dir as deprecated
> 
> This commit updates the DAMON usage documentation to formally mark the
> sysfs 'filters/' directory as deprecated. It recommends users migrate
> to the 'core_filters/' and 'ops_filters/' directories instead.
> 
> > diff --git a/Documentation/admin-guide/mm/damon/usage.rst b/Documentation/admin-guide/mm/damon/usage.rst
> > index 534e1199cf091..4c222e956b100 100644
> > --- a/Documentation/admin-guide/mm/damon/usage.rst
> > +++ b/Documentation/admin-guide/mm/damon/usage.rst
> [ ... ]
> >  Use of ``filters`` directory can make expecting evaluation orders of given
> > -filters with the files under directory bit confusing.  Users are hence
> > -recommended to use ``core_filters`` and ``ops_filters`` directories.  The
> > -``filters`` directory could be deprecated in future.
> > +filters with the files under directory bit confusing.  For the reason,
> > +``filters`` directory is deprecated.  It is still functioning, but it will be
> > +broken and eventually removed in near future.  Users should use
> > +``core_filters`` and ``ops_filters`` directories instead.
> 
> This isn't a bug, but could the phrasing here be smoothed out a bit? There
> are a few awkward phrases like "make expecting evaluation orders" and "with
> the files under directory bit confusing".
> 
> Also, stating that a sysfs interface "will be broken" is generally avoided
> in kernel documentation. The standard convention is to say that an interface
> is "deprecated and scheduled for removal" to avoid implying that userspace
> will be intentionally broken.
> 
> Would a rewrite like this work better?
> 
> "Using the ``filters`` directory can make the evaluation order of filters
> confusing. For this reason, the ``filters`` directory is deprecated. It
> continues to function for now, but is scheduled for removal in the near
> future."

Nice suggestion.  I will apply that suggestion.


Thanks,
SJ

[...]