From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) (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 41B8680387 for ; Mon, 20 Mar 2017 11:54:24 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=intel.com; i=@intel.com; q=dns/txt; s=intel; t=1490036064; x=1521572064; h=from:to:cc:subject:date:message-id:references: in-reply-to:content-transfer-encoding:mime-version; bh=GNetPYdhkfblcVQda/nBadQq3Ywd1mtuK+qKKwKfCtg=; b=sG70IkzgEfLj/7bRvu86l6ekuGs7PHzIMrVLA5Epw70U5Y89RckJzlbV AbCtMdI7dYq4R0JDM0Xj0uEENIrKOQ==; Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orsmga101.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 20 Mar 2017 11:54:23 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.36,195,1486454400"; d="scan'208";a="946329167" Received: from orsmsx110.amr.corp.intel.com ([10.22.240.8]) by orsmga003.jf.intel.com with ESMTP; 20 Mar 2017 11:54:23 -0700 Received: from orsmsx111.amr.corp.intel.com (10.22.240.12) by ORSMSX110.amr.corp.intel.com (10.22.240.8) with Microsoft SMTP Server (TLS) id 14.3.319.2; Mon, 20 Mar 2017 11:54:23 -0700 Received: from orsmsx113.amr.corp.intel.com ([169.254.9.211]) by ORSMSX111.amr.corp.intel.com ([10.22.240.12]) with mapi id 14.03.0319.002; Mon, 20 Mar 2017 11:54:23 -0700 From: "Kinney, Michael D" To: Leif Lindholm , "Kinney, Michael D" CC: "edk2-devel@lists.01.org" Thread-Topic: [edk2] [docs][RFC] GitBook documentation process Thread-Index: AQHSoaZlrZUs1YvKm0ee1XXXWNoZvKGeETUQ Date: Mon, 20 Mar 2017 18:54:23 +0000 Message-ID: References: <20170320181830.GZ16034@bivouac.eciton.net> In-Reply-To: <20170320181830.GZ16034@bivouac.eciton.net> Accept-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: x-ctpclassification: CTP_IC x-titus-metadata-40: eyJDYXRlZ29yeUxhYmVscyI6IiIsIk1ldGFkYXRhIjp7Im5zIjoiaHR0cDpcL1wvd3d3LnRpdHVzLmNvbVwvbnNcL0ludGVsMyIsImlkIjoiZGMwOGU4NDYtZjJmOS00YTUzLWIwZmItYTNlOGExOTEyOTFkIiwicHJvcHMiOlt7Im4iOiJDVFBDbGFzc2lmaWNhdGlvbiIsInZhbHMiOlt7InZhbHVlIjoiQ1RQX0lDIn1dfV19LCJTdWJqZWN0TGFiZWxzIjpbXSwiVE1DVmVyc2lvbiI6IjE1LjkuNi42IiwiVHJ1c3RlZExhYmVsSGFzaCI6InlmTzhBVktTT2Y0NlF6V21qajF5UmZoWmhZXC8rRU8wRE5ObHBlWE10aFdjPSJ9 x-originating-ip: [10.22.254.138] MIME-Version: 1.0 Subject: Re: [docs][RFC] 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: Mon, 20 Mar 2017 18:54:24 -0000 Content-Language: en-US Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable Hi Leif, Thanks for the feedback. I will update the RFC. I only used my personal GitHub and GitBook accounts as a=20 staging area for the RFC discussion/approval. I will migrate all GitHub and GitBook content to Tianocore accounts once approved. The official GitBook account for publishing will be named Tianocore-Docs. The Tianocore website documents areas will also be updated=20 with links to published docs from the Tianocore-docs GitBook account. Mike > -----Original Message----- > From: Leif Lindholm [mailto:leif.lindholm@linaro.org] > Sent: Monday, March 20, 2017 11:19 AM > To: Kinney, Michael D > Cc: edk2-devel@lists.01.org > Subject: Re: [edk2] [docs][RFC] GitBook documentation process >=20 > Hi Mike, >=20 > I agree with Laszlo's comments (including that this looks really > good!). Just one question below: >=20 > On Fri, Mar 17, 2017 at 01:07:59AM +0000, Kinney, Michael D wrote: > > Hello, > > > > 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. > > > > Please provide feedback by 3/24/2017. > > > > 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 > > > > # 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 > > > > * 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 `[docs]` tag in email discussions. > > > > `[edk2][docs] Subject` > > > > 2. Use `[docs][repo-name PATCH]` tag in patch review emails. > > > > `[edk2][docs][edk2-DecSpecification PATCH] Fix typo in Section 2.= 7` > > > > 3. Use TianoCore Contribution Agreement 1.1 in commit message > > > > `Contributed-under: TianoCore Contribution Agreement 1.0` > > > > 4. Send email to edk2-devel to request creation of new document repos= itory > > and link the repository to the GitBook publishing services. > > > > `[edk2][docs][edk2-NewSpecification] Create repository for New Sp= ecification` > > > > 5. Send email to edk2-devel to announce the creation of document rele= ase branch. > > > > `[edk2][docs][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_Sp= ec_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 > > >=20 > These pre-rendered versions look great, but should we have have some > official gitbook account to link against rather than your personal > one? Or do we have an alternative plan for publication? >=20 > Regards, >=20 > Leif >=20 > > # 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 > > _______________________________________________ > > edk2-devel mailing list > > edk2-devel@lists.01.org > > https://lists.01.org/mailman/listinfo/edk2-devel