[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

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

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] 

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.


Would work for me, too.




Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.