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

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

On 27/08/15 03:44, Jim Fehlig wrote:
> On 08/25/2015 04:40 AM, Andrew Cooper wrote:
>> 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?
>
> Yes. It provides excellent info, with pointers to dig deeper for those
> interested.
>
> Your proposal does raise the bar for feature contribution, but I'm not
> active enough in the Xen community to know if folks are supportive of
> the additional overhead. Would new features require a feature doc
> before committing?

Unless there are some screaming objections, I am hoping yes, and that
the document becomes the authoritative support statement for the
feature.  (This is currently a real problem working out the security
status of bugs in features lacking a concrete statement of support.)

Writing one of these documents is not hard (I hope for there to soon be
many examples to refer to), and I would like to see it become
common-practice to have as $N/$N on a series.

~Andrew