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

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

On 28/08/15 18:40, Andrew Cooper wrote:
> 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.

In addition.

I expect that maintainers would have an idea of the documentation which
exists in tree, and refer to it when reviewing new code in the area.  I
certainly will be.

Nowadays, it feels that enough people reviewing new submissions have an
instinct of "changes to command line parameters should patch
docs/misc/xen-command-line.markdown".  This is a very good position as
far as keeping the command line documentation up to date goes, and was
the entire principle behind introducing that document in the first place.

I would hope that after a while, similar instincts would develop for
major modification or addition of new features.

~Andrew