Skip to content

[edk2][RFC v2] GitBook documentation process

Jump to bottom
Michael Kinney edited this page Apr 5, 2017 · 1 revision

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 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/tianocore-docs/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://github.com/tianocore-docs/edk2-TemplateSpecification/blob/master/LICENSE.txt

  • Use 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 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.1

    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

    4. Send email to edk2-devel to announce the creation of document release branch.

      [edk2][edk2-DecSpecification] Create release/0.30 branch

    5. The master branch of a document repository is always the latest DRAFT version of the document.

    6. Released versions of documents are always on a release branch with a naming convention of release/x.yy.

Gitbook Example

The examples below are two versions of the EDK II Template Specification with links to the documents published using Gitbook and the link to the GitHub repository that contains the markdown sources of the EDK II Template Specification.

The first version is a DRAFT version of the EDK II Template Specification. DRAFT versions of documents are always on the master branch. The second version is released version of the EDK II Template Specification at Revision 0.1. Release versions of documents are always on a release branch.

  • EDK II Template Specification DRAFT [ HTML , PDF , Mobi , ePub , Gitbook, GitHub ] This document is a template that can be copied to start a new Tianocore Gitbook document. It also provides examples for styles and formats commonly found in Tianocore specifications.

  • EDK II Template Specification Revision 0.1 [ HTML , PDF , Mobi , ePub , Gitbook, GitHub ] This document is a template that can be copied to start a new Tianocore Gitbook document. It also provides examples for styles and formats commonly found in Tianocore specifications.

Resources

Clone this wiki locally