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

[Lars Kurth <lars.kurth.xen@xxxxxxxxx>]

> On 28 Aug 2015, at 18:40, Andrew Cooper <andrew.cooper3@xxxxxxxxxx> wrote:
> 
> On 28/08/15 18:16, Lars Kurth wrote:
>>> On 27 Aug 2015, at 15:52, Ian Jackson <ian.jackson@xxxxxxxxxxxxx> 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.

As I said, it was just an idea to discuss.
 
> 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 

This end of the mail was deleted by mistake. I meant to say was ...

We may need some extra tags/headings, if we were to include things such as 
supported limits for memory, vCPUs, ... I remember, you raised the point that 
some of the theoretical limits are not always tested. 

* Maybe a Testing section, which outlines what is tested automatically and what 
should be manually tested when updated. It could be optional.
* Maybe another optional references section: that would allow us to link to 3rd 
party specs, presentations, etc.

Lars
_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel