xfs
[Top] [All Lists]

Re: [PATCH 6/6] xfs: document log sysfs attributes in testing ABI

To: Dave Chinner <david@xxxxxxxxxxxxx>
Subject: Re: [PATCH 6/6] xfs: document log sysfs attributes in testing ABI
From: Brian Foster <bfoster@xxxxxxxxxx>
Date: Thu, 26 Jun 2014 08:30:22 -0400
Cc: xfs@xxxxxxxxxxx
Delivered-to: xfs@xxxxxxxxxxx
In-reply-to: <20140626050345.GZ4453@dastard>
References: <1402060414-22075-1-git-send-email-bfoster@xxxxxxxxxx> <1402060414-22075-7-git-send-email-bfoster@xxxxxxxxxx> <20140626050345.GZ4453@dastard>
User-agent: Mutt/1.5.23 (2014-03-12)
On Thu, Jun 26, 2014 at 03:03:45PM +1000, Dave Chinner wrote:
> On Fri, Jun 06, 2014 at 09:13:34AM -0400, Brian Foster wrote:
> > Create a sysfs-fs-xfs ABI documentation file for newly added sysfs
> > attributes. This is created under the testing section.
> > 
> > Signed-off-by: Brian Foster <bfoster@xxxxxxxxxx>
> 
> Looks fine, but I'm not sure we ever want people to think these are
> going to form part of the stable XFS ABI - they are encodings of
> deeply internal functionality of XFS. We're not going to be tied to
> an implementation because of diagnostic information we expose to
> to sysfs, so users need to know that this is a volatile interface.
> 

I was under the impression that sysfs in general was considered a stable
ABI. Perhaps not to the degree of things like system call interfaces,
but the Documentation/ABI/README describes the expected lifecycle for
these attributes (i.e., testing->stable->obsolete->removed).

> Hence I'd suggest adding a disclaimer indicating that these not ever
> guaranteed to be stable and could change or be removed at any time
> without warning. Say, for example, we add another description line
> like this:
> 
>    Stability:         Volatile
> 
> We can then point out the entries that are we'll never guarantee are
> stable, those that we are stabilising, and those that are considered
> stable easily?
> 

I'm not against adding another keyword, though I'm curious how this is
different from the above. Wouldn't we use the location of the
documentation to identify how stable the interface is expected to be? To
put it another way, this seems fine under the testing section (but that
suggests volatility already), but I wouldn't ever place a "Stability:
volatile" attribute under the stable section.

Taking a look at the ABI/testing/sysfs-fs-ext4 file, it goes back to
2009 with the most recent update in 2012 and it's still under the
testing section. It's not clear if that's by design or just stale
documentation, but perhaps that is technically the right approach. E.g.,
while clearly those attributes aren't still under "testing," they aren't
ever going to be considered "stable ABI." That means use them for
informational and tuning purposes, don't ever build userspace programs
with significant dependence on them, etc. Anything that does grow unique
importance (i.e., a future spaceman dependency) can get moved over to
stable as we'll expect to provide some kind of deprecation warning and
period of backwards compatibility for supported tools. Thoughts?

Brian

> Cheers,
> 
> Dave.
> -- 
> Dave Chinner
> david@xxxxxxxxxxxxx

<Prev in Thread] Current Thread [Next in Thread>