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

[Jan Beulich <jbeulich@xxxxxxxx>]

On 13.07.2020 10:04, Jürgen Groß wrote:
> On 13.07.20 09:56, Jan Beulich wrote:
>> On 13.07.2020 07:16, Juergen Gross wrote:
>>> @@ -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.
>>>   
>>> +Path availability is subject to change, e.g. a specific path specified
>>> +for a single architecture now might be made available for other 
>>> architectures
>>> +in future, or it could be made conditional by an additional config option
>>> +of the hypervisor.
>>
>> I agree this is worthwhile clarifying. To me, between the lines,
>> this then suggests that paths are entirely unreliable, which I
>> don't think is what we want. So perhaps some further clarification
>> could be added to clarify that we're not going to arbitrarily
>> change paths or their meaning? Or am I mistaken in understanding
>> that this interface is meant to act ABI-like?
> 
> You are right. What about following rewording:
> 
> "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."

Yes, yet I'd go even further and add "A path once assigned meaning
won't go away altogether or change its meaning, though" or some such.

Jan