From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga05.intel.com (mga05.intel.com [192.55.52.43]) (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 177C68040E for ; Wed, 22 Mar 2017 21:14:29 -0700 (PDT) Received: from fmsmga005.fm.intel.com ([10.253.24.32]) by fmsmga105.fm.intel.com with ESMTP; 22 Mar 2017 21:14:28 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.36,208,1486454400"; d="scan'208";a="79666529" Received: from orsmsx106.amr.corp.intel.com ([10.22.225.133]) by fmsmga005.fm.intel.com with ESMTP; 22 Mar 2017 21:14:28 -0700 Received: from orsmsx163.amr.corp.intel.com (10.22.240.88) by ORSMSX106.amr.corp.intel.com (10.22.225.133) with Microsoft SMTP Server (TLS) id 14.3.319.2; Wed, 22 Mar 2017 21:14:28 -0700 Received: from orsmsx113.amr.corp.intel.com ([169.254.9.211]) by ORSMSX163.amr.corp.intel.com ([169.254.9.49]) with mapi id 14.03.0319.002; Wed, 22 Mar 2017 21:14:27 -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+lk5w== Date: Thu, 23 Mar 2017 04:14:26 +0000 Message-ID: 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.139] MIME-Version: 1.0 Subject: [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: Thu, 23 Mar 2017 04:14:29 -0000 Content-Language: en-US Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable 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=20 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=20 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=20 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=20 format is completed. I have added more EDK II documents since the first version of=20 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 documents=20 associated with the Tianocore project. Markdown is a document source forma= t that is compatible with the patch review process that is currently used for EDK II source changes. [GitBook](https://www.gitbook.com) is a document publishing service that uses Markdown as an input format and can generate=20 published documents as web pages, PDF, MOBI, and EPUB and provide a GitHub integration service that supports pulling Markdown sources from GitHub host= ed repositories. There are several elements to this proposal: * Update of the TianoCore Contribution Agreement from Version 1.0 to=20 Version 1.1 to cover open source documentation associated with the=20 TianoCore project. The following is a link to the revised agreement. https://github.com/mdkinney/edk2-TemplateSpecification/blob/master/CONTRI= BUTIONS.txt * New license for TianoCore documentation source files and TianoCore publis= hed documents. The following is a link to the license that is based on the=20 [FreeBSD Documentation License](https://www.freebsd.org/copyright/freebsd= -doc-license.html): https://github.com/mdkinney/edk2-TemplateSpecification/blob/master/LICENS= E.txt * Use [TianoCore-Docs](https://github.com/tianocore-docs) GitHub organizati= on to=20 host the GIT repositories for TianoCore documents. The reason a new orga= nization is being used is because the GitBook services requires one GIT repository= per document. A separate organization separates the source code repositories= from documentation repositories. * Use [TianoCore Bugzilla](https://bugzilla.tianocore.org) to report docume= nt issues. + Add DocumentName as a required setting when reporting a document issu= e + Remove PackageName as a required setting when reporting a document is= sue * 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. This i= s a very brief summary. A second RFC and/or Wiki page will cover the detailed pro= cess. 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=20 `Contributed-under: TianoCore Contribution Agreement 1.0` 3. Send email to edk2-devel to request creation of new document repositor= y=20 and link the repository to the GitBook publishing services. `[edk2][edk2-NewSpecification] Create repository for New Specificatio= n` 5. Send email to edk2-devel to announce the creation of document release = branch. `[edk2][edk2-DecSpecification] Create release/0.30 branch` 6. The `master` branch of a document repository is always the latest DRAF= T version of the document. 7. Released versions of documents are always on a release branch with a n= aming 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 doc= ument called _EDK II Template Specification_ has been created to provide a sample= that can be used to start new documents. It can also be updated over time to pr= ovide examples of the Markdown syntax required for specific document styles and e= xperiment with refinements to the document management process. The second document i= s the=20 _EDK II Package Declaration (DEC) File Format Specification_ that has been = converted to GitBook. This GitBook version can be compared against current version a= t: 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 Git= Hub=20 repository and linked to a personal GitBook account. The DRAFT version of = the=20 _EDK II Template Specification_ is in the `master` branch, and the released= version is in the `releases/0.10` branch. This template also shows some example us= age of=20 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-specifi= cation + PDF: https://www.gitbook.com/download/pdf/book/mdkinney/edk-ii-template= -specification + MOBI: https://www.gitbook.com/download/mobi/book/mdkinney/edk-ii-templa= te-specification + EPUB: https://www.gitbook.com/download/epub/book/mdkinney/edk-ii-templa= te-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-template= -specification/v/release/0.1 + MOBI: https://www.gitbook.com/download/mobi/book/mdkinney/edk-ii-templa= te-specification/v/release/0.1 + EPUB: https://www.gitbook.com/download/epub/book/mdkinney/edk-ii-templa= te-specification/v/release/0.1 Here are the links to the _EDK II Package Declaration (DEC) File Format Spe= cification_ in a personal GitHub repository and linked to a personal GitBook account. = The DRAFT=20 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-specificatio= n + PDF: https://www.gitbook.com/download/pdf/book/mdkinney/edk-ii-dec-spec= ification + MOBI: https://www.gitbook.com/download/mobi/book/mdkinney/edk-ii-dec-sp= ecification + EPUB: https://www.gitbook.com/download/epub/book/mdkinney/edk-ii-dec-sp= ecification # 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-language-sp= ecification) =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