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 _______________________________________________ xfs mailing list xfs@xxxxxxxxxxx http://oss.sgi.com/mailman/listinfo/xfs
