From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga01.intel.com (mga01.intel.com [192.55.52.88]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id B4BC021A0482F for ; Fri, 31 Mar 2017 16:07:02 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=intel.com; i=@intel.com; q=dns/txt; s=intel; t=1491001622; x=1522537622; h=from:to:subject:date:message-id:references:in-reply-to: content-transfer-encoding:mime-version; bh=+5WNIn+xRggx9jd5Ft8JNWlOenUAkA+ubrTMyRrHUO4=; b=GsoCKeIypA3rq2nRpwHH7plAjiffS4b1FqIZDlIqOImJ2CHKbzRAjBPs vTW9GRvldfhuM3RVPFdVPb2ie2katw==; Received: from fmsmga002.fm.intel.com ([10.253.24.26]) by fmsmga101.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 31 Mar 2017 16:07:02 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.36,254,1486454400"; d="scan'208";a="1149476791" Received: from orsmsx107.amr.corp.intel.com ([10.22.240.5]) by fmsmga002.fm.intel.com with ESMTP; 31 Mar 2017 16:07:02 -0700 Received: from orsmsx116.amr.corp.intel.com (10.22.240.14) by ORSMSX107.amr.corp.intel.com (10.22.240.5) with Microsoft SMTP Server (TLS) id 14.3.319.2; Fri, 31 Mar 2017 16:07:01 -0700 Received: from orsmsx113.amr.corp.intel.com ([169.254.9.59]) by ORSMSX116.amr.corp.intel.com ([10.22.240.14]) with mapi id 14.03.0319.002; Fri, 31 Mar 2017 16:07:01 -0700 From: "Kinney, Michael D" To: "edk2-devel@lists.01.org" , "Kinney, Michael D" Thread-Topic: [edk2][RFC v2] GitBook documentation process Thread-Index: AdKjij8ZG11dCD0mQh64YUGyE+lk5wEX/CTQAKI/b0A= Date: Fri, 31 Mar 2017 23:07:01 +0000 Message-ID: References: In-Reply-To: Accept-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-ctpclassification: CTP_IC x-titus-metadata-40: eyJDYXRlZ29yeUxhYmVscyI6IiIsIk1ldGFkYXRhIjp7Im5zIjoiaHR0cDpcL1wvd3d3LnRpdHVzLmNvbVwvbnNcL0ludGVsMyIsImlkIjoiMTE0MzVjZTEtYTU1Zi00YjRmLThlNjQtNjFiNDkyMDFhNjNlIiwicHJvcHMiOlt7Im4iOiJDVFBDbGFzc2lmaWNhdGlvbiIsInZhbHMiOlt7InZhbHVlIjoiQ1RQX0lDIn1dfV19LCJTdWJqZWN0TGFiZWxzIjpbXSwiVE1DVmVyc2lvbiI6IjE1LjkuNi42IiwiVHJ1c3RlZExhYmVsSGFzaCI6IjJ6Q2I0RHh4U1IwaDd5KzdjWmp4b3Rwa2o0OUg0XC9VVVN1XC9OMlBVS2owTT0ifQ== x-originating-ip: [10.22.254.138] MIME-Version: 1.0 Subject: Re: [RFC v2] GitBook documentation process X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.22 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 31 Mar 2017 23:07:03 -0000 Content-Language: en-US Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable Hello, One more EDK II Gitbook update this week. The EDK II Build Specification has been converted and=20 is ready for review. https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Draft-Specific= ation Mike > -----Original Message----- > From: Kinney, Michael D > Sent: Tuesday, March 28, 2017 10:48 AM > To: edk2-devel@lists.01.org; Kinney, Michael D > Subject: RE: [edk2][RFC v2] GitBook documentation process >=20 > Hello, >=20 > I have added draft versions of the EDK II DEC, INF, DSC, FDF, UNI, > and Template Specifications based on this RFC. These are now hosted > in the Tianocore-docs organization on GitHub and the Tianocore-docs > organization on Gitbook. >=20 > https://github.com/tianocore-docs > https://www.gitbook.com/@edk2-docs >=20 > I have added an EDK II Draft Specifications Wiki page that contains > links to the published versions of these draft specifications from > Gitbook along with links to the Gitbook page and GitHub repository > for each specification. >=20 > https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Draft-Spec= ification >=20 > I want to make sure no content was lost in the conversion to Gitbook. > Please review these drafts and use either the Gitbook commenting feature > or Tianocore Bugzilla (https://bugzilla.tianocore.org) to provide feedbac= k. >=20 > I will continue to convert the remaining EDK II related specifications. >=20 > Thanks, >=20 > Mike >=20 > > -----Original Message----- > > From: Kinney, Michael D > > Sent: Wednesday, March 22, 2017 9:14 PM > > To: edk2-devel@lists.01.org; Kinney, Michael D > > Subject: [edk2][RFC v2] GitBook documentation process > > > > Hello, > > > > I have updated the GitBook RFC based on feedback received. > > > > Changes for V2: > > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > * Remove [docs] from email subject > > * Update Bugzilla for document issues to remove Package > > field and add Document field > > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > > > The following is an RFC proposal for using GitBook for tianocore > > documentation. This RFC is also available at the following link: > > > > * https://github.com/mdkinney/edk2-TemplateSpecification/wiki > > > > Please review this proposal and the referenced documents and > > provide any comments or concerns you may have. > > > > The Sample GitBook documents are hosted in personal GitHub and > > personal GitBook pages. When this RFC is approved, these will > > documents be migrated to Tianocore pages and additional EDK II > > related documents will be added as the conversion to GitBook > > format is completed. > > > > I have added more EDK II documents since the first version of > > this RFC. The complete set now available for review are: > > > > * EDK II Template Specification > > https://www.gitbook.com/book/mdkinney/edk-ii-template-specification > > > > * EDK II DEC Specification > > https://www.gitbook.com/book/mdkinney/edk-ii-dec-specification > > > > * EDK II UNI Specification > > https://www.gitbook.com/book/mdkinney/edk-ii-uni-specification > > > > * EDK II FDF Specification > > https://www.gitbook.com/book/mdkinney/edk-ii-fdf-specification > > > > * EDK II DSC Specification > > https://www.gitbook.com/book/mdkinney/edk-ii-dsc-specification > > > > Thanks, > > > > Mike > > > > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > > > [edk2][RFC v2] GitBook documentation process > > > > # Introduction > > > > This RFC provide a proposal to create and maintain open source document= s > > associated with the Tianocore project. Markdown is a document source f= ormat > > that is compatible with the patch review process that is currently used= for > > EDK II source changes. [GitBook](https://www.gitbook.com) is a documen= t > > publishing service that uses Markdown as an input format and can genera= te > > published documents as web pages, PDF, MOBI, and EPUB and provide a Git= Hub > > integration service that supports pulling Markdown sources from GitHub = hosted > > repositories. > > > > There are several elements to this proposal: > > > > * Update of the TianoCore Contribution Agreement from Version 1.0 to > > Version 1.1 to cover open source documentation associated with the > > TianoCore project. The following is a link to the revised agreement. > > > > https://github.com/mdkinney/edk2- > TemplateSpecification/blob/master/CONTRIBUTIONS.txt > > > > * New license for TianoCore documentation source files and TianoCore pu= blished > > documents. The following is a link to the license that is based on t= he > > [FreeBSD Documentation License](https://www.freebsd.org/copyright/fre= ebsd-doc- > > license.html): > > > > https://github.com/mdkinney/edk2-TemplateSpecification/blob/master/LI= CENSE.txt > > > > * Use [TianoCore-Docs](https://github.com/tianocore-docs) GitHub organi= zation to > > host the GIT repositories for TianoCore documents. The reason a new > organization > > is being used is because the GitBook services requires one GIT reposi= tory per > > document. A separate organization separates the source code reposito= ries from > > documentation repositories. > > > > * Use [TianoCore Bugzilla](https://bugzilla.tianocore.org) to report do= cument > issues. > > + Add DocumentName as a required setting when reporting a document = issue > > + Remove PackageName as a required setting when reporting a documen= t issue > > > > * Use the same patch review process that is used for EDK II source code= to > provide > > changes to TianoCore documents with the differences listed below. Th= is is a > very > > brief summary. A second RFC and/or Wiki page will cover the detailed= process. > > > > 1. Use `[repo-name PATCH]` tag in patch review emails. > > > > `[edk2][edk2-DecSpecification PATCH] Fix typo in Section 2.7` > > > > 2. Use TianoCore Contribution Agreement 1.1 in commit message > > > > `Contributed-under: TianoCore Contribution Agreement 1.0` > > > > 3. Send email to edk2-devel to request creation of new document repos= itory > > and link the repository to the GitBook publishing services. > > > > `[edk2][edk2-NewSpecification] Create repository for New Specific= ation` > > > > 5. Send email to edk2-devel to announce the creation of document rele= ase > branch. > > > > `[edk2][edk2-DecSpecification] Create release/0.30 branch` > > > > 6. The `master` branch of a document repository is always the latest = DRAFT > version > > of the document. > > > > 7. Released versions of documents are always on a release branch with= a naming > > convention of `release/x.yy`. > > > > # Sample EDK II Documents in GitBook Format > > > > A couple of documents have been used to prototype this proposal. A new= document > > called _EDK II Template Specification_ has been created to provide a sa= mple that > > can be used to start new documents. It can also be updated over time t= o provide > > examples of the Markdown syntax required for specific document styles a= nd > experiment > > with refinements to the document management process. The second docume= nt is the > > _EDK II Package Declaration (DEC) File Format Specification_ that has b= een > converted > > to GitBook. This GitBook version can be compared against current versi= on at: > > https://github.com/tianocore- > docs/Docs/raw/master/Specifications/DEC_Spec_1_25.pdf > > > > Here are the links to the _EDK II Template Specification_ in a personal= GitHub > > repository and linked to a personal GitBook account. The DRAFT version= of the > > _EDK II Template Specification_ is in the `master` branch, and the rele= ased > version > > is in the `releases/0.10` branch. This template also shows some exampl= e usage of > > the [PlatUML](http://plantuml.com) to implement figures and diagrams. > > > > * https://github.com/mdkinney/edk2-TemplateSpecification > > * https://www.gitbook.com/book/mdkinney/edk-ii-template-specification > > > > Here are the links to the GitBook published documents > > > > * _EDK II Template Specification_ DRAFT > > + WEB: https://www.gitbook.com/read/book/mdkinney/edk-ii-template-spe= cification > > + PDF: https://www.gitbook.com/download/pdf/book/mdkinney/edk-ii-temp= late- > > specification > > + MOBI: https://www.gitbook.com/download/mobi/book/mdkinney/edk-ii-te= mplate- > > specification > > + EPUB: https://www.gitbook.com/download/epub/book/mdkinney/edk-ii-te= mplate- > > specification > > * _EDK II Template Specification_ Revision 0.10 > > + WEB: https://mdkinney.gitbooks.io/edk-ii-template- > > specification/content/v/release/0.1/ > > + PDF: https://www.gitbook.com/download/pdf/book/mdkinney/edk-ii-temp= late- > > specification/v/release/0.1 > > + MOBI: https://www.gitbook.com/download/mobi/book/mdkinney/edk-ii-te= mplate- > > specification/v/release/0.1 > > + EPUB: https://www.gitbook.com/download/epub/book/mdkinney/edk-ii-te= mplate- > > specification/v/release/0.1 > > > > Here are the links to the _EDK II Package Declaration (DEC) File Format > Specification_ > > in a personal GitHub repository and linked to a personal GitBook accoun= t. The > DRAFT > > version of this specification is in the `master` branch. > > > > * https://github.com/mdkinney/edk2-DecSpecification > > * https://www.gitbook.com/book/mdkinney/edk-ii-dec-specification > > > > * _EDK II Package Declaration (DEC) File Format Specification__ DRAFT > > + WEB: https://www.gitbook.com/read/book/mdkinney/edk-ii-dec-specific= ation > > + PDF: https://www.gitbook.com/download/pdf/book/mdkinney/edk-ii-dec- > specification > > + MOBI: https://www.gitbook.com/download/mobi/book/mdkinney/edk-ii-de= c- > specification > > + EPUB: https://www.gitbook.com/download/epub/book/mdkinney/edk-ii-de= c- > specification > > > > # Resources > > > > * [GitHub TianoCore](https://github.com/tianocore) > > * [GitHub TianoCore-Docs](https://github.com/tianocore-docs) > > * [TianoCore Bugzilla](https://bugzilla.tianocore.org) > > * [GitBook](https://www.gitbook.com) > > * [GitBook ToolChain Documentation](https://toolchain.gitbook.com/) > > * [GitBook MarkDown](https://toolchain.gitbook.com/syntax/markdown.html= ) > > * [GitBook Editor](https://www.gitbook.com/editor) > > * [PlantUML](http://plantuml.com) > > * [PlantUML Language Specification](http://plantuml.com/sitemap-languag= e- > > specification) > > > > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > >