Re: API break, sysfs "capability" file

[Keith Busch]

On Tue, Apr 16, 2024 at 04:23:43PM +0200, Lennart Poettering wrote:
> On Di, 09.04.24 16:15, Christoph Hellwig (hch@xxxxxx) wrote:
> 11;rgb:1717/1414/2121
> > On Tue, Apr 09, 2024 at 10:19:09AM +0200, Lennart Poettering wrote:
> > > All I am looking for is a very simple test that returns me a boolean:
> > > is there kernel-level partition scanning enabled on this device or
> > > not.
> >
> > And we can add a trivial sysfs attribute for that.
> >
> > > At this point it's not clear to me if I can write this at all in
> > > a way that works reasonably correctly on any kernel since let's say
> > > 4.15 (which is systemd's "recommended baseline" right now).
> > >
> > > I am really not sure how to salvage this mess at all. AFAICS there's
> > > currently no way to write such a test correctly.
> >
> > You can't.  Maybe that's a lesson to not depend on undocumented internal
> > flags exposed by accident by a weirdo interface.  Just talk to
> > people.
> 
> Undocumented? Internal?
> 
> It's was actually one of the *best* documented kernel *public* APIs I
> ever came across:
> 
>    https://www.kernel.org/doc/html/v5.16/block/capability.html
> 
> So much detail, I love it!
>
> I mean, you did good work here, documented it, with all flags in all
> details. I think that's great work! You should take pride in this, not
> try to deny its existance!

The patch that introduced this was submitted not because the API was
stable; it was committed to encourage developers to update it as it
changed because it is *not* stable. That's not the kind of interface you
want exported for users to rely on, but no one should have to search
commit logs to understand why the doc exists, so I think exporting it
was just a mistake on the kernel side. To say this doc is "good"
misunderstands what it was trying to accomplish, and what it ultimately
created instead: technical debt.

The block interfaces documented in Documetation/ABI/stable/ are reliably
stable, though.