From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) (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 A05DD8042F for ; Fri, 17 Mar 2017 03:51:50 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 1AAE0804FF; Fri, 17 Mar 2017 10:51:51 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com 1AAE0804FF Authentication-Results: ext-mx03.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx03.extmail.prod.ext.phx2.redhat.com; spf=pass smtp.mailfrom=lersek@redhat.com DKIM-Filter: OpenDKIM Filter v2.11.0 mx1.redhat.com 1AAE0804FF Received: from lacos-laptop-7.usersys.redhat.com (ovpn-116-70.phx2.redhat.com [10.3.116.70]) by smtp.corp.redhat.com (Postfix) with ESMTP id 4F2D460A9D; Fri, 17 Mar 2017 10:51:50 +0000 (UTC) To: "Kinney, Michael D" , "edk2-devel@lists.01.org" References: From: Laszlo Ersek Message-ID: <4b4b2b39-bdb7-2f3c-7160-9e169015616f@redhat.com> Date: Fri, 17 Mar 2017 11:51:48 +0100 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.8.0 MIME-Version: 1.0 In-Reply-To: X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.27]); Fri, 17 Mar 2017 10:51:51 +0000 (UTC) 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: Fri, 17 Mar 2017 10:51:50 -0000 Content-Type: text/plain; charset=windows-1252 Content-Transfer-Encoding: 7bit On 03/17/17 02:07, 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 > > ======================================================================= > > # Introduction > > This RFC provide a proposal to create and maintain open source documents > associated with the Tianocore project. Markdown is a document source format > 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 > published documents as web pages, PDF, MOBI, and EPUB and provide a GitHub > 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 published > documents. The following is a link to the license that is based on the > [FreeBSD Documentation License](https://www.freebsd.org/copyright/freebsd-doc-license.html): > > https://github.com/mdkinney/edk2-TemplateSpecification/blob/master/LICENSE.txt > > * Use [TianoCore-Docs](https://github.com/tianocore-docs) GitHub organization to > host the GIT repositories for TianoCore documents. The reason a new organization > 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 document issues Currently, setting a Package on reported bugs is mandatory, even if Component=Documentation. Can we add pseudo-packages for the books? > > * 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 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` I suggest not to mandate a [docs] prefix. I think the list traffic isn't high enough for this (and if traffic was high enough for that, then a separate list would likely make more sense). > > 2. Use `[docs][repo-name PATCH]` tag in patch review emails. > > `[edk2][docs][edk2-DecSpecification PATCH] Fix typo in Section 2.7` Similarly, [docs] is messy here. [edk2] is added by the list software when it reflects emails, and "repo-name PATCH" (within the brackets) can be passed to git-format-patch with the --subject-prefix option. There's no good automated solution for adding [docs] separately, and IMO it is unnecessary as well -- the "repo-name" part is good enough identification. The rest looks good to me, from a single read. Thanks! Laszlo > > 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 repository > and link the repository to the GitBook publishing services. > > `[edk2][docs][edk2-NewSpecification] Create repository for New Specification` > > 5. Send email to edk2-devel to announce the creation of document release 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 sample that > can be used to start new documents. It can also be updated over time to provide > examples of the Markdown syntax required for specific document styles and experiment > with refinements to the document management process. The second document is the > _EDK II Package Declaration (DEC) File Format Specification_ that has been converted > to GitBook. This GitBook version can be compared against current version 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 released version > is in the `releases/0.10` branch. This template also shows some example 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-specification > + PDF: https://www.gitbook.com/download/pdf/book/mdkinney/edk-ii-template-specification > + MOBI: https://www.gitbook.com/download/mobi/book/mdkinney/edk-ii-template-specification > + EPUB: https://www.gitbook.com/download/epub/book/mdkinney/edk-ii-template-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-template-specification/v/release/0.1 > + EPUB: https://www.gitbook.com/download/epub/book/mdkinney/edk-ii-template-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 account. 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-specification > + PDF: https://www.gitbook.com/download/pdf/book/mdkinney/edk-ii-dec-specification > + MOBI: https://www.gitbook.com/download/mobi/book/mdkinney/edk-ii-dec-specification > + EPUB: https://www.gitbook.com/download/epub/book/mdkinney/edk-ii-dec-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-language-specification) > > ======================================================================= > _______________________________________________ > edk2-devel mailing list > edk2-devel@lists.01.org > https://lists.01.org/mailman/listinfo/edk2-devel >