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

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

On 15.07.20 16:37, George Dunlap wrote:
> > On Jul 13, 2020, at 3:47 PM, Jan Beulich <JBeulich@xxxxxxxx> wrote:
> >
> > On 13.07.2020 16:03, Juergen Gross wrote:
> > > In docs/misc/hypfs-paths.pandoc the supported paths in the hypervisor
> > > file system are specified. Make it more clear that path availability
> > > might change, e.g. due to scope widening or narrowing (e.g. being
> > > limited to a specific architecture).
> > >
> > > Signed-off-by: Juergen Gross <jgross@xxxxxxxx>
> > > Release-acked-by: Paul Durrant <paul@xxxxxxx>
> > Acked-by: Jan Beulich <jbeulich@xxxxxxxx>
> >
> > However, I'd like agreement by at least one other REST maintainer on
> > ...
> >
> > > @@ -55,6 +58,11 @@ tags enclosed in square brackets.
> > > * CONFIG_* -- Path is valid only in case the hypervisor was built with
> > >    the respective config option.
> > >
> > > +In case a tag for a path indicates that this path is available in some
> > > +case only, this availability might be extended or reduced in future by
> > > +modification or removal of the tag. A path once assigned meaning won't go
> > > +away altogether or change its meaning, though.
> > ... the newly imposed guarantee we're now making. We really want to
> > avoid declaring something as stable without being quite certain we
> > can keep it stable.
> The declaration of new nodes must all happen in this file, right?  So as long as the 
> maintainer(s) fo this file are aware of that, and it’s commented so that people know 
> that expecation, I think it’s OK.
>
> But I think this paragraph isn’t very clear to me what “might be extended or reduced …but 
> won’t go away altogether”.
>
> 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?
Yes.


Juergen