Skip to content

TianoCore Documents GitBook Overview

Jump to bottom
Michael Kinney edited this page Aug 20, 2018 · 17 revisions

Introduction

The TianoCore Project uses the GitBook to publish specifications. These specifications are implemented using the Markdown document source format and stored in GitHub repositories in the TianoCore-Docs project. These specifications may be published in HTML, PDF, MOBI, and EPUB formats from the GitBook TianoCore-Docs project and links to the published documents are provided in the TianoCore Wiki pages for specific projects or releases. The figure below shows the relationships between these services and the types of activities that are performed by developers and administrators. The sections that follow provide the information required to perform these activities.

GitBookOverview

Links Between Content

In order to support review and use of the documents, it is important links are created between content in the different services. This simplifies the patch review process, and also allows consumers of the published documents to see the document changes associated with each resolved issue and also review discussions related to each document change. The required links include:

  • Each documents README.md file must provide a Revision History section and this section must contain the hyperlink to a TianoCore Bugzilla issue for each document change.

  • The GIT commit message for a document change must contain the list of hyperlinks to the TianoCore Bugzilla issues the commit resolves.

  • The TianoCore Bugzilla issue must contain a comment with the list of hyperlinks to GIT commits that resolve the issue.

Editing Documents describes how each of these links are provides during the document editing process.

With these three links in place, a developer reading a document published by the GitBook server can look at the Revision History to see what has changed. If there is a specific change they want to review, then the link to the TianoCore Bugzilla issue can be followed. This TianoCore Bugzilla issue provides a summary of the change and any discussions on the change that was made, and in some cases may include links to edk2-devel mailing list discussions. One of the last comments in the TianoCore Bugzilla issue contains links to the GitHub commits. Each of these links can be followed to see the exact document content changes. GitHub provides a color coded content change view for MarkDown files.

A developer can also start from the tianocore-docs document repository commit history and follow the links in a commit to the TianoCore Bugzilla issues.

Document Repositories, Branches, and Releases

Each document in the TianoCore-Docs project is stored in a single repository. The master branch in each repository contains the latest draft of that document. Document releases are made by creating a release branch with the branch name format of release/x.yy where x is the major version of the document, and yy is the minor version of the document.

Typically, a release branch for a document contains only a single commit that converts the document from a draft version to a released version. However, if a critical issue is found in a released document, then additional commits for each document errata can be made on the release branch. The following diagram shows an example document with the latest draft on the master branch along with three release branches. One errata has to be provided for a critical issue on the 0.10 release of the document.

                                 Errata
                                  --->
                release/0.10    /     \
               /--------------------------->
              /   release/0.30     
             /   /----------------->
            /   /     release/1.00
           /   /   /------------------>
master    /   /   /
---------------------------------------------------------------> Latest DRAFT
                                              \     /
                                               \--->
                                           Document Change

Resources

Clone this wiki locally