Skip to content

Release related docs updates

Jump to bottom
Hillary Fraley edited this page Jul 13, 2021 · 34 revisions

Add a docs version

For major and minor releases of Sensu Go, we create a new version of the docs to contain documentation for the upcoming release. We usually add a new docset when the release coordinator announces that a new Sensu Go release is forming in #sensu-release. If a release requires substantial new or updated documentation, we might add the new docset sooner to allow more time for docs work.

The sensu-docs repo includes a script, scripts/new-docs-version.sh, that copies all pages of an existing docs version and updates the required frontmatter in the copied pages to form a new docset with the desired version number. The docs version numbers correspond to the major and minor Sensu Go release numbers.

To add a docset for a new Sensu Go version:

  1. In a Terminal (bash or zsh) window, clone the sensu-docs repo:

    git clone https://github.com/sensu/sensu-docs.git && cd sensu-docs

  2. Create a new branch:

    git checkout -b <version_number>/add-docset

  3. Update and run the scripts/new-docs-version.sh command. The command to run the script is:

    ./scripts/new-docs-version.sh 'version_to_copy' 'new_version_number'
    • <version_to_copy> is the number for the version of the docs that is currently marked as latest
    • <new_version_number> is the number for the version of the docs you want to add

    For example, the initial docset for new Sensu Go version 6.4 would be a copy of the docs for version 6.3:

    ./scripts/new-docs-version.sh '6.3' '6.4'

    Update the command with the desired version numbers and run the command to create the new docset.

  4. Add the new docset to the docs version menu. In your local copy of sensu-docs, open config.toml. Copy the parameter object for the version you copied, paste it immediately under the product parameter object, and update it with the new version number.

    For example, to add version 6.4 to the docs version menu, find this object in your local config.toml file:

    [[params.products.sensu_go.versions]]
version = "6.3"
platforms = []

    Copy the 6.3 object and paste it directly under this object:

    [params.products.sensu_go]
 identifier = "sensu-go"
 name = "Sensu Go"
 description = "The next-generation monitoring event pipeline"
 weight = 1
 latest = "6.3"

    Update the pasted object to use the new version number and save the file:

    [[params.products.sensu_go.versions]]
version = "6.4"
platforms = []

  5. Confirm that the site builds correctly: run it locally with yarn && yarn run server. In the running local version, make sure the docs version menu lists the new docset. It should be listed above the current version's docset, which is designated with (latest).

  6. Commit your changes to the sensu-docs repo. Create and merge a sensu-docs PR to add the new version's docset.

After merging the PR to create the new version, go through open PRs and select the "update branch" button on each one. This ensures that existing pull requests are able to update new versions. Contributors will need to delete their local branch and re-fetch the branch from GitHub.

Update the Supported Versions page

Update the supported versions page, versions.md, each time we release a version of Sensu Go. The required updates depend on whether the release is a new major or minor version or a patch.

In both cases, start by cloning the sensu-docs repo and creating a new local branch:

  1. In a Terminal (bash or zsh) window, clone the sensu-docs repo: 
    git clone https://github.com/sensu/sensu-docs.git && cd sensu-docs
  2. Create a new branch: 
    git checkout -b <version_number>/supp-vers

Continue according to whether the release is a major or minor or patch.

Major or minor versions

If the release is a new major or minor version (for example, 6.x with a new version of documentation):

  1. Add a row in the versions.md table for the new version. You can copy and paste the row for the most current version as a starting point.
  2. Add a link to the new version's release notes at the bottom of the page and update the link reference in the new version's table row.
  3. Mark the fourth previous version as "Not supported" in the versions.md table. For example, if you add version 6.4, mark version 6.0 as "Not supported."
  4. Update the new table row with the anticipated release date.
  5. Commit your changes to the sensu-docs repo and create a sensu-docs PR for the updated supported versions page. Because release dates can change, hold the PR until the release party to make sure the table lists the correct release date before merging.

New major or minor versions also require an offline PDF for the new docs version.

Patch releases

If the release is a patch (for example, 6.x.x with no new version of documentation):

  1. Add a row in the versions.md table for the new patch. You can copy and paste the row for the most current patch release as a starting point.
  2. Add a link to the new version's release notes at the bottom of the page and update the link reference in the new version's table row.
  3. Update the new table row with the anticipated release date.
  4. Commit your changes to the sensu-docs repo and create a sensu-docs PR for the updated supported versions page. Because release dates can change, hold the PR until the release party to make sure the table lists the correct release date before merging.

Patch releases use the offline PDF for the associated minor version. For example, the 6.4.0, 6.4.1, and 6.4.2 table rows will all use the same offline PDF link (which would be the offline PDF for minor verson 6.4).

Create an offline PDF copy of docs

We create an offline PDF copy of each docset and link to it on the supported versions page. Creating the offline PDF requires a licensed copy of Adobe Acrobat, so you may need to contact the license holder to complete this task. Currently, Acrobat is licensed to the Principal Technical Writer.

To create an offline PDF copy of a version of the docs:

  1. In a Terminal (bash or zsh) window, clone the sensu-docs repo: 
    git clone https://github.com/sensu/sensu-docs.git && cd sensu-docs
  2. Run a local hugo server with offline layouts: 
    yarn
yarn run server --layoutDir=offline
  3. Navigate to http://localhost:1313/ and select the product and version you want to PDF. Copy the local URL.
  4. Open Acrobat and navigate to File → Create → PDF from Web Page to open the Create PDF from Web Page window.
  5. Paste the local URL in the URL: field.
  6. Click Capture Multiple Levels and select the following Settings options:
    • Leave Get only ... level(s) selected and change the number of levels to 10.
    • Select Stay on same path and Stay on same server.
  7. Click the Settings... button to open the Web Page Conversion Settings window. Make sure the File type is HTML. Under PDF Settings, select only Create bookmarks.
  8. In the Web Page Conversion Settings window, click OK.
  9. In the Create PDF from Web Page window, click Create.
  10. Save the generated PDF file with this naming convention: sensu-go-6-4_sensu-docs
  11. Save the PDF in Sensu's Amazon S3 account in the sensu-docs bucket, inside the pdfs folder.

Update version and build numbers for release

Because we create the docset for upcoming releases by copying the docset for the previous release, the new release's docset will contain the version and build numbers for the previous release until you update them.

The sensu-docs repo includes a script, scripts/update-sensu-version.sh, that searches a docset for the old version and build numbers and replaces them with the new version and build numbers you specify.

  1. In a Terminal (bash or zsh) window, clone the sensu-docs repo:

    git clone https://github.com/sensu/sensu-docs.git && cd sensu-docs

  2. Create a new branch:

    git checkout -b <version_number>/update-vers-build

  3. Run the scripts/new-docs-version.sh command. The command to run the script is:

    ./scripts/update-sensu-version.sh <version_number_to_replace> <build_number_to_replace> <new_version_number> <new_build_number> <docset_number>
    • <version_number_to_replace> is the version number that should be replaced
    • <build_number_to_replace> is the build number that should be replaced
    • <new_version_number> is the correct version number for the upcoming release (the release number, like 6.4.0 or 6.4.2)
    • <new_build_number> is the correct build number for the upcoming release (available on the Key tab in the release checklist)
    • <docset_number> is the number for the docset in which the version and build numbers should be replaced

    For example, to update the version and build numbers in the 6.4 docs, which would be based on the 6.3 docs:

    ./scripts/update-sensu-version.sh 6.3.0 9470 6.4.0 9999 6.4
Updating Sensu version from 6.3.0 (build 9470) to 6.4.0 (build 9999) for docs version 6.4

    Update the command with the desired version and build numbers and run the command. This script makes the following updates:

    • /sensu-go/{version}/installation/install-sensu.md (build numbers)
    • /sensu-go/{version}/installation/platforms.md (version numbers in AWS links)

    NOTE: If you run the script but git status doesn't list any changes to the build number on your branch, it may be because the new doc set was created from an earlier release (not the most recent release) and uses that release's build number. Check the Windows links under https://docs.sensu.io/sensu-go/latest/installation/install-sensu/#agent-download for the old build number to use in the script.

  4. Commit your changes to the sensu-docs repo and create a sensu-docs PR for the updated version and build numbers. Because build numbers can change depending on Engineering release task findings, hold the PR until the release party to make sure it includes the correct build number before merging.

Promote the new version to latest

When you're ready to promote the new version as the latest version, create a PR with the following changes:

  1. In a Terminal (bash or zsh) window, clone the sensu-docs repo: 
    git clone https://github.com/sensu/sensu-docs.git && cd sensu-docs
  2. Create a new branch: 
    git checkout -b <version_number>/promote-to-latest
  3. Update the version number for the latest parameter (ex: latest = "6.4") in config.toml and static.json.
  • In config.toml: latest = "6.4"
  • In static.json: "~ ^/sensu-go/6.4/?((?<=\/).*)?$": {
  1. Update the Algolia search version in https://github.com/sensu/sensu-docs/blob/master/layouts/partials/footer_js.html
  2. Update docs.sensu.io (https://github.com/sensu/sensu-docs/blob/master/layouts/index.html) to link the Sensu Go tile to the latest version number for the Go docs.
  3. Commit your changes to the sensu-docs repo and create a sensu-docs PR to promote the new version to latest. Hold the PR until the Engineering rep publishes all build packages during the release party.

Archive a docs version

When we add a new minor version of Sensu Go or remove docs that are more than three minor versions old from the docs.sensu.io website, we create an offline PDF copy of the docs and update the Supported Versions page. This section describes how. Here's how to remove a version of the docs from docs.sensu.io:

  1. In a Terminal (bash or zsh) window, clone the sensu-docs repo:

    git clone https://github.com/sensu/sensu-docs.git && cd sensu-docs

  2. Create a new branch:

    git checkout -b <version_number>/archive-docs

  3. Use git to move the target version into the archived/sensu-go/ directory (replace 6.3 with the correct target version):

    git mv content/sensu-go/6.3/ archived/sensu-go/

  4. Edit config.toml to remove the version being archived:

    • vi config.toml
    • i to insert
    • esc to exit insert
    • :w to write and :q to quit vim

  5. Edit static.json to update the regex to include the version being archived:

    • vi static.json
    • i to insert
    • In "~ ^/sensu-go/6.[0-2]/?((?<=\/).*)?$": {, update the range inside [] to include the version being archived. For example, to archive version 6.3, update to [0-3].
    • esc to exit insert
    • :w to write and :q to quit vim

  6. Commit your changes to the sensu-docs repo and create a sensu-docs PR to archive the docs version. Hold the PR until you merge the PR to promote the new docs version to latest.

Create offline PDF of an archived version

If you need to re-create the offline PDF of an archived version of the docs (for example, if you make a major correction in the docs), here's how:

  1. In a Terminal (bash or zsh) window, clone the sensu-docs repo:

    git clone https://github.com/sensu/sensu-docs.git && cd sensu-docs

  2. Symlink the archived version into the live site content for local server usage.

    a. Change working directory to the product root:

    cd content/sensu-go

    b. Create a relative symlink to the archived doc content:

    ln -sfv ../../archived/sensu-go/6.3

  3. Run yarn and yarn run server --layoutDir=offline

  4. Open http://localhost:1313/sensu-go/6.3/ and create the offline PDF.

Clone this wiki locally