Re: [RFC v2 for-4.6 0/2] In-tree feature documentation

[Andrew Cooper <andrew.cooper3@citrix.com>]

On 28/08/15 18:16, Lars Kurth wrote:
>> On 27 Aug 2015, at 15:52, Ian Jackson <ian.jackson@eu.citrix.com> wrote:
>>
>> Andrew Cooper writes ("[RFC v2 for-4.6 0/2] In-tree feature documentation"):
>>> An issue which Xen has is an uncertain support statement for features.
>>> Given the success seen with docs/misc/xen-command-line.markdown, and in
>>> particular keeping it up to date, introduce a similar system for
>>> features.
>>>
>>> Patch 1 introduces a proposed template (and a makefile tweak to include
>>> the new docs/features subdirectory), while patch 2 is a feature document
>>> covering the topic of migration.
>>>
>>> v2 Adds %Revision and #History table, following feedback from v1.
>>>
>>> This is tagged RFC as I expect people to have different views as to what
>>> is useful to include.  I would particilarly appreciate feedback on the
>>> template before it starts getting used widely.
>>>
>>> Lars: Does this look like a reasonable counterpart to your formal
>>> support statement document?
>>>
>>> Jim: Per your request at the summit for new information, is patch 2
>>> suitable?
>> I have read both patches.
> Me too
>
>> I do wonder whether cross-referencing all the "issues" is a good idea.
>> It seems like it might be a lot of work to keep them in step.
> There is a risk that these may go stale. I am wondering, whether if we do have features, we can come up with some conventions that allow us to grep for the issues on the list. Just an idea.
>
> We could have a unique feature ID in the #basics section. Migration (as in the first line of migration.pandoc) is probably too generic in this example (too many false negatives). But if there was a unique enough feature identifier that can be grep'ed in commit logs, on xen-devel@, ... that may help.

This feels like over-engineering a solution.  Maintaining a set of
unique features will be extra burden on the core maintainers, as well as
a extra burden on submitters to know how to work this brand new system.

I would hope that few supported features have "issues" as identified in
the migration document.

I expect this section to be far more useful for experimental and tech
preview features.  In such cases issues are perfectly fine (It is far
better to have some code people can play with, with a set of known
restrictions, than to have no code at all), and can serve as a todo list
before its status can be elevated to supported.

>
>> Overall I think this is a good template.  The extra overhead may even
>> be negative.  The work of writing up a feature in the style of this
>> document may obviate the need to put much of the same information in a
>> 0/N or a design document, and the existing template is quite
>> lightweight.
> I agree. I don't really have any additional comments Andrew. So feel free to 
>
> We may need some extra tags/headings, if we were to include things such as 

I would like to avoid making the system overly prescriptive (as this
makes it harder for contributers), but I would be perfectly happy
reviewing a new series where patch 0/$N simply says "refer to patch $Y
for the feature document".

~Andrew