Re: [docs][RFC] GitBook documentation process

[Laszlo Ersek <lersek@redhat.com>]

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
>