From mboxrd@z Thu Jan 1 00:00:00 1970 From: Andrew Cooper Subject: Re: [PATCH for-4.6 1/2] docs: Template for feature documents Date: Tue, 25 Aug 2015 11:06:50 +0100 Message-ID: <55DC3E3A.6080609@citrix.com> 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> <20150825084122.GE29776@zion.uk.xensource.com> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <20150825084122.GE29776@zion.uk.xensource.com> List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Sender: xen-devel-bounces@lists.xen.org Errors-To: xen-devel-bounces@lists.xen.org To: Wei Liu Cc: Juergen Gross , Xen-devel List-Id: xen-devel@lists.xenproject.org On 25/08/15 09:41, Wei Liu wrote: > >>>> + >>>> +\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. > Or use a table for revision history at the beginning? I personally think > using a table is clearer than several paragraphs. > > Don't want to bikeshed how it should look like. We can always change the > template if necessary. I have introduced a history table at the end of the template. I want to avoid it getting in the way of the table of basic information and overview. ~Andrew