From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wr0-x231.google.com (mail-wr0-x231.google.com [IPv6:2a00:1450:400c:c0c::231]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id AE01E80470 for ; Mon, 20 Mar 2017 11:18:34 -0700 (PDT) Received: by mail-wr0-x231.google.com with SMTP id l37so98070712wrc.1 for ; Mon, 20 Mar 2017 11:18:34 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to:user-agent; bh=r/uHLGCJvDABUx8HwZ7FFgE0DPVj8MrywFfonmbvVIY=; b=QModrZAN9skrvIkcOZ7OF0XxIsLG1DiYETHvVENglGzE9aWx9IPa0teH+t/n0+JSpX z5teGyK4CMQvlbggmvqyA7KPsqkJC1w1E8880uez5eF1huoWkDmaU37QdiWB2IiirDIm nrpMvA2EgF2Fawn6R6W8Ly2ph+yfuyQx4QYO8= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to:user-agent; bh=r/uHLGCJvDABUx8HwZ7FFgE0DPVj8MrywFfonmbvVIY=; b=jBFvvntzIFimt/TqJ9ZEQkhhMeBczFoTfEVm1jTZkSSrAWSGMJtx/YQol6HQp4PqbG Nghym5Cr70TYWsqmdh9TLUilSCHbwxNsPYeMS4LiR2GY+T2cFmOpRpbkRNmr+naGBzI5 bqEgxW5Q35sUpHkDV0Yu3WfRZuDfPtp2+6EPa+SCK9M2pz4zHgQZbXgtQNgZQwWjJ6JB dyp0N2bV6+sbEwp0CEgE461iaZorDYDnalgs+CssrbbxRFuvTXxz0vlOxNXpxqY3J96f gw19INe2kObg2D1Xowc5o8dcD8W+zRTcxLqnNPX0WnbxlXytbsDsiu5ntJFe6PFoPPNL uOGQ== X-Gm-Message-State: AFeK/H14zztSCIohkr4+GXPq02tK+Y27YAdnhHtyfIjTcj2lbmB462I0yZjjd8jwSwte/dej X-Received: by 10.223.167.66 with SMTP id e2mr26017948wrd.48.1490033912923; Mon, 20 Mar 2017 11:18:32 -0700 (PDT) Received: from bivouac.eciton.net (bivouac.eciton.net. [2a00:1098:0:86:1000:23:0:2]) by smtp.gmail.com with ESMTPSA id y4sm14355317wmy.5.2017.03.20.11.18.31 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 20 Mar 2017 11:18:32 -0700 (PDT) Date: Mon, 20 Mar 2017 18:18:30 +0000 From: Leif Lindholm To: "Kinney, Michael D" Cc: "edk2-devel@lists.01.org" Message-ID: <20170320181830.GZ16034@bivouac.eciton.net> References: MIME-Version: 1.0 In-Reply-To: User-Agent: Mutt/1.5.23 (2014-03-12) 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:18:35 -0000 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Hi Mike, I agree with Laszlo's comments (including that this looks really good!). Just one question below: 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 > > ======================================================================= > > # 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 > > * 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` > > 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 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 > 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? Regards, Leif > # 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