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

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

On 28/08/15 18:51, Lars Kurth wrote:
>> On 28 Aug 2015, at 18:40, Andrew Cooper <andrew.cooper3@citrix.com> 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.
> 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.

Absolutely.  Not everyone has a server with 123TB of RAM to hand, or
even 16TB which is default current limit.  (For this issue, testing from
both Citrix and Oracle indicates a bug when more than 5TB of RAM is used.)

Therefore, a distinction between the theoretical limit and
currently-tested limit is very useful.  I expect the the commercial
stakeholders will be in a position to routinely test at far above the
limit available to direct consumers of the Xen project.


For the in-tree statement of limits, I have not put much though to how
to represent them yet, but I am not sure that the feature template
proposed in #1 will be a great fit.  I suspect we will want something a
little different.

>
> * Maybe a Testing section, which outlines what is tested automatically and what should be manually tested when updated. It could be optional.

Ooh - that is a good idea.

Even if it is just a paragraph about suggested things to test when
modifying, it will be useful to contributors.

> * Maybe another optional references section: that would allow us to link to 3rd party specs, presentations, etc.

I should really put some references in the migration document, shouldn't I.

~Andrew