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

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

> 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.

> 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 



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