Skip to content

TianoCore Documents GitBook Overview

Jump to bottom
Michael Kinney edited this page May 1, 2025 · 20 revisions

Introduction

The TianoCore Project uses the GitBook Markdown source format for specification and are stored in GitHub repositories in the TianoCore-Docs project. These specifications are published in HTML, PDF, MOBI, and EPUB formats utilizing GitBook tools run in GitHub Actions. Links to the published documents are provided in the TianoCore-Docs and TianoCore Uncyclo pages for specific projects or releases. The figure below shows the relationships between the 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 GitHub PRs for each document change.

  • If a document change is associated with GitHub issues, then the GitHub issues and GitHub PRs must be linked.

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

With these links in place, a developer reading a published document can review the Revision History to see what has changed. If there is a specific change that requires review, then the link to the GitHub PR and and associated GitHub Issues can be followed. The GitHub PR 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. 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 to the GitHub PR and any associated GitHub issues.

Document Repositories, Branches, and Releases

Each document in the TianoCore-Docs project is stored in a single repository. The main 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 main 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
           /   /   /------------------>
main      /   /   /
---------------------------------------------------------------> Latest DRAFT
                                              \     /
                                               \--->
                                           Document Change

Resources

Clone this wiki locally