Re: [PATCH v2] docs: specify stability of hypfs path documentation

[Jürgen Groß <jgross@xxxxxxxx>]

On 20.07.20 12:19, George Dunlap wrote:
> > On Jul 16, 2020, at 3:34 PM, Jürgen Groß <jgross@xxxxxxxx> wrote:
> >
> > On 16.07.20 16:20, George Dunlap wrote:
> > > > On Jul 16, 2020, at 12:34 PM, Jürgen Groß <jgross@xxxxxxxx> wrote:
> > > >
> > > > On 16.07.20 13:24, Jan Beulich wrote:
> > > > > On 16.07.2020 12:31, Jürgen Groß wrote:
> > > > > > On 16.07.20 12:11, Jan Beulich wrote:
> > > > > > > On 15.07.2020 16:37, George Dunlap wrote:
> > > > > > > > IT sounds like you’re saying:
> > > > > > > >
> > > > > > > > 1. Paths listed without conditions will always be available
> > > > > > > >
> > > > > > > > 2. Paths listed with conditions may be extended: i.e., a node currently listed 
> > > > > > > > as PV might also become available for HVM guests
> > > > > > > >
> > > > > > > > 3. Paths listed with conditions might have those conditions reduced, but will never 
> > > > > > > > entirely disappear.  So something currently listed as PV might be reduced to 
> > > > > > > > CONFIG_HAS_FOO, but won’t be completely removed.
> > > > > > > >
> > > > > > > > Is that what you meant?
> > > > > > > I see Jürgen replied "yes" to this, but I'm not sure about 1.
> > > > > > > above: I think it's quite reasonable to expect that paths without
> > > > > > > condition may gain a condition. Just like paths now having a
> > > > > > > condition and (perhaps temporarily) losing it shouldn't all of
> > > > > > > the sudden become "always available" when they weren't meant to
> > > > > > > be.
> > > > > > >
> > > > > > > As far a 3. goes, I'm also unsure in how far this is any better
> > > > > > > stability wise (from a consumer pov) than allowing paths to
> > > > > > > entirely disappear.
> > > > > > The idea is that any user tool using hypfs can rely on paths under 1 to
> > > > > > exist, while the ones under 3 might not be there due to the hypervisor
> > > > > > config or the used system.
> > > > > >
> > > > > > A path not being allowed to entirely disappear ensures that it remains
> > > > > > in the documentation, so the same path can't be reused for something
> > > > > > different in future.
> > > > > And then how do you deal with a condition getting dropped, and
> > > > > later wanting to get re-added? Do we need a placeholder condition
> > > > > like [ALWAYS] or [TRUE]?
> > > > Dropping a condition has to be considered very carefully, same as
> > > > introducing a new path without any condition.
> > > >
> > > > In worst case you can still go with [CONFIG_HYPFS].
> > > Couldn’t we just have a section of the document for dead paths that aren’t 
> > > allowed to be used?
> > > Alternately, we could have a tag for entries we don’t want used anymore; [DEAD] 
> > > or [OBSOLETE] maybe? [DEFUNCT]? [REMOVED]?
> > > So I think I’d write a separate section, like this:
> > > ~~
> > > # Stability
> > > Path *presence* is not stable, but path *meaning* is always stable: if a tool 
> > > you write finds a path present, it can rely on behavior in future versions of 
> > > the hypervisors, and in different configurations.  Specifically:
> > > 1. Conditions under which paths are used may be extended, restricted, or removed.  For 
> > > example, a path that’s always available only on ARM systems may become 
> > > available on x86; or a path available on both systems may be restricted to only 
> > > appearing on ARM systems.  Paths may also disappear entirely.
> > > 2. However, the meaning of a path will never change.  If a path is present, it 
> > > will always have exactly the meaning that it always had.  In order to maintain 
> > > this, removed paths should be retained with the tag [REMOVED].  The path may be 
> > > restored *only* if the restored version of the path is compatible with the 
> > > previous functionality.
> > > ~~~
> > > Thoughts?
> > Would work for me, too.
> So whose court is the ball in now?  Are you going to send another patch, or 
> would you prefer I do it?
I can do it. I just hoped that maybe someone else would agree to this
approach.


Juergen