From mboxrd@z Thu Jan  1 00:00:00 1970
From: Juergen Gross <xen@pfupf.net>
Subject: Re: [PATCH for-4.6 1/2] docs: Template for feature
 documents
Date: Tue, 25 Aug 2015 00:58:49 +0200
Message-ID: <55DBA1A9.5090702@pfupf.net>
References: <1440437822-29490-1-git-send-email-andrew.cooper3@citrix.com>
	<1440437822-29490-2-git-send-email-andrew.cooper3@citrix.com>
	<55DB7022.8090306@pfupf.net> <55DBA032.2010906@citrix.com>
Mime-Version: 1.0
Content-Type: text/plain; charset="us-ascii"; Format="flowed"
Content-Transfer-Encoding: 7bit
Return-path: <xen-devel-bounces@lists.xen.org>
In-Reply-To: <55DBA032.2010906@citrix.com>
List-Unsubscribe: <http://lists.xen.org/cgi-bin/mailman/options/xen-devel>,
	<mailto:xen-devel-request@lists.xen.org?subject=unsubscribe>
List-Post: <mailto:xen-devel@lists.xen.org>
List-Help: <mailto:xen-devel-request@lists.xen.org?subject=help>
List-Subscribe: <http://lists.xen.org/cgi-bin/mailman/listinfo/xen-devel>,
	<mailto:xen-devel-request@lists.xen.org?subject=subscribe>
Sender: xen-devel-bounces@lists.xen.org
Errors-To: xen-devel-bounces@lists.xen.org
To: Andrew Cooper <andrew.cooper3@citrix.com>, Xen-devel <xen-devel@lists.xen.org>
List-Id: xen-devel@lists.xenproject.org

On 08/25/2015 12:52 AM, Andrew Cooper wrote:
> On 24/08/2015 20:27, Juergen Gross wrote:
>> On 08/24/2015 07:37 PM, Andrew Cooper wrote:
>>> Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
>>> ---
>>>    docs/Makefile                 |    2 +-
>>>    docs/features/template.pandoc |   55
>>> +++++++++++++++++++++++++++++++++++++++++
>>>    2 files changed, 56 insertions(+), 1 deletion(-)
>>>    create mode 100644 docs/features/template.pandoc
>>>
>>> diff --git a/docs/Makefile b/docs/Makefile
>>> index 272292c..5d620e5 100644
>>> --- a/docs/Makefile
>>> +++ b/docs/Makefile
>>> @@ -16,7 +16,7 @@ MARKDOWNSRC-y := $(sort $(shell find misc -name
>>> '*.markdown' -print))
>>>
>>>    TXTSRC-y := $(sort $(shell find misc -name '*.txt' -print))
>>>
>>> -PANDOCSRC-y := $(sort $(shell find specs -name '*.pandoc' -print))
>>> +PANDOCSRC-y := $(sort $(shell find features/ misc/ specs/ -name
>>> '*.pandoc' -print))
>>>
>>>    # Documentation targets
>>>    DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(MAN1SRC-y))
>>> diff --git a/docs/features/template.pandoc
>>> b/docs/features/template.pandoc
>>> new file mode 100644
>>> index 0000000..d883b82
>>> --- /dev/null
>>> +++ b/docs/features/template.pandoc
>>> @@ -0,0 +1,55 @@
>>> +% Template for feature documents
>>> +
>>> +\clearpage
>>> +
>>> +This is a suggested template for formatting of a Xen feature
>>> document in tree.
>>> +
>>> +The purpose of this document is to provide a concrete support
>>> statement for the
>>> +feature (indicating its security status), as well as brief user and
>>> technical
>>> +documentation.
>>> +
>>> +# Basics
>>> +
>>> +A table with an overview of the support status and applicability.
>>> +
>>> +---------------- ----------------------------------------------------
>>> +         Status: e.g. **Supported**/**Tech Preview**/**Experimental**
>>> +
>>> +Architecture(s): e.g. x86, arm
>>> +
>>> +   Component(s): e.g. Hypervisor, toolstack, guest
>>> +
>>> +       Hardware: _where applicable_
>>> +---------------- ----------------------------------------------------
>>
>> What about adding some information when the feature was introduced or
>> some other historical stuff? Something like:
>>
>> Experimental in Xen 4.1
>> Supported in Xen 4.3
>> xl syntax changed in Xen 4.4
>>
>
> In the longterm, I would expect that information to be visible via `git
> log`.
>
> Having said that, it probably is useful to have a summary of history
> available in the written document.
>
> How about a #History section at the bottom?  That can at least include
> "document written" as a starting point and subsequent major changes in
> short form.

Sure, I'm fine with this.

Juergen