Re: [RFC v2] GitBook documentation process

["Kinney, Michael D" <michael.d.kinney@intel.com>]

Hello,

One more EDK II Gitbook update this week.

The EDK II Build Specification has been converted and 
is ready for review.

https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Draft-Specification

Mike

> -----Original Message-----
> From: Kinney, Michael D
> Sent: Tuesday, March 28, 2017 10:48 AM
> To: edk2-devel@lists.01.org; Kinney, Michael D <michael.d.kinney@intel.com>
> Subject: RE: [edk2][RFC v2] GitBook documentation process
> 
> Hello,
> 
> I have added draft versions of the EDK II DEC, INF, DSC, FDF, UNI,
> and Template Specifications based on this RFC.  These are now hosted
> in the Tianocore-docs organization on GitHub and the Tianocore-docs
> organization on Gitbook.
> 
>   https://github.com/tianocore-docs
>   https://www.gitbook.com/@edk2-docs
> 
> I have added an EDK II Draft Specifications Wiki page that contains
> links to the published versions of these draft specifications from
> Gitbook along with links to the Gitbook page and GitHub repository
> for each specification.
> 
>   https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Draft-Specification
> 
> I want to make sure no content was lost in the conversion to Gitbook.
> Please review these drafts and use either the Gitbook commenting feature
> or Tianocore Bugzilla (https://bugzilla.tianocore.org) to provide feedback.
> 
> I will continue to convert the remaining EDK II related specifications.
> 
> Thanks,
> 
> Mike
> 
> > -----Original Message-----
> > From: Kinney, Michael D
> > Sent: Wednesday, March 22, 2017 9:14 PM
> > To: edk2-devel@lists.01.org; Kinney, Michael D <michael.d.kinney@intel.com>
> > Subject: [edk2][RFC v2] GitBook documentation process
> >
> > Hello,
> >
> > I have updated the GitBook RFC based on feedback received.
> >
> > Changes for V2:
> > ===============
> > * Remove [docs] from email subject
> > * Update Bugzilla for document issues to remove Package
> >   field and add Document field
> > ===============
> >
> > 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.
> >
> > I have added more EDK II documents since the first version of
> > 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
> >
> > =======================================================================
> >
> > [edk2][RFC v2] GitBook documentation process
> >
> > # 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.
> >     + Add DocumentName as a required setting when reporting a document issue
> >     + Remove PackageName as a required setting when reporting a document issue
> >
> > * 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 `[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
> >
> >       `Contributed-under: TianoCore Contribution Agreement 1.0`
> >
> >   3. Send email to edk2-devel to request creation of new document repository
> >      and link the repository to the GitBook publishing services.
> >
> >       `[edk2][edk2-NewSpecification] Create repository for New Specification`
> >
> >   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 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)
> >
> > =======================================================================
> >