GitBook/GitHub Publication Process

Owned by Wes Brown
Last updated: Dec 12, 2023
2 min read

Key Requirements

  • The publication process should not impact ongoing documentation updates that are not intended to be included in the publication

  • Once published, the documentation version cannot change

  • The documentation on GitBook and any backing repositories (GitHub) should be consistent across spaces/branches

Process Highlights

  1. Ongoing work on GovStack documentation is done in the Development space on GitBook. This space is linked to the default branch in the backing Git repository, usually called main.

  2. To prepare for a new publication, when substantial updates to the documentation are complete, a new branch is created on Git for release activities. This branch is then linked to a space on GitBook. The suggested name for this branch is simply the name of the version (for example, 1.0, 1.2.3, or 23Q4).

  3. The release space is used to review and make any required updates to the documentation for the new publication. Any content changes that are not intended to be part of the new publication can be made in the Development space without impacting the release work.

  4. During the pre-release phase any edits should be done in the Development space (or directly in the main branch) as much as possible. Then the individual commits can be merged into the release branch on GitHub (GitBook lacks the functionality to merge between branches/spaces or cherrypick individual commits).

    1. The only changes which should be performed directly on the release branch/space are changes which should not be merged back into the main branch. For example, links to other specifications in the release space should always reference the versioned URL for the content (for example, if the Reference Use Case space needs to link to the Consent BB, it should use the versioned url, https://govstack.gitbook.io/bb-consent/v/con-23q4 rather than the non-versioned url, https://govstack.gitbook.io/bb-consent/).

  5. If there are any changes to the release branch which need to be merged back into the default branch, cherrypick the specific commits and merge them back into main.

  6. The URLs in the new publication space are checked to ensure that they link to properly versioned documents. For example, all links to resources within the GovStack documentation must use the newly created publication space.

  7. The new version space is published on GitBook and made the default space for the documentation (using the Customize Collection page) and there is much rejoicing

Diagram