Skip to content

Release related docs updates

Jump to bottom
Hillary Fraley edited this page May 14, 2021 · 34 revisions

Add a docs version

Minor releases of Sensu Go require you to create a new copy of the docs, update the front matter, and update the site config.

The sensu-docs repo includes a script to automatically create a new version of the docs and update all of the required frontmatter. The command to run the script is:

./scripts/new-docs-version.sh 'OLD_SENSU_VERSION' 'NEW_SENSU_VERSION'

For example, to create a docset for version 5.25 based on version 5.24, run:

./scripts/new-docs-version.sh '5.24' '5.25'

After you run the script, in config.toml, list the new version (and applicable platforms) under the product parameters. For example: add:

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

under:

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

To confirm that the site builds correctly, run it locally with yarn run server. Then, commit your changes and create and merge a sensu-docs PR.

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.

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. Update the version number for the latest parameter (ex: latest = "5.20") in config.toml and static.json.
  • In config.toml: latest = "5.20"
  • In static.json: "~ ^/sensu-go/5.20/?((?<=\/).*)?$": {
  1. Update the Algolia search version in https://github.com/sensu/sensu-docs/blob/master/layouts/partials/footer_js.html
  2. Update https://github.com/sensu/sensu-docs/blob/master/layouts/index.html to update the Sensu Go tile to the latest version number for the Go docs.

Update version and build numbers for release

For each release, the Customer Reliability rep is responsible for updating the version and build numbers in docs.sensu.io site pages.

  1. In a Terminal (bash or zsh) window, clone the website:
git clone https://github.com/sensu/sensu-docs.git && cd sensu-docs
  1. Run the scripts/update-sensu-version.sh script to update the version and build numbers in the appropriate docs version:
$ ./scripts/update-sensu-version.sh OLD_VERSION_NUMBER OLD_BUILD_NUMBER NEW_VERSION_NUMBER NEW_BUILD_NUMBER DOCS_VERSION

For example:

$ ./scripts/update-sensu-version.sh 5.18.0 9470 5.19.0 9999 5.19
Updating Sensu version from 5.18.0 (build 9470) to 5.19.0 (build 9999) for docs version 5.19

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.

Archive docs and create offline PDFs

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.

Create an offline PDF copy of docs

Follow these steps to create an offline PDF copy of a version of the docs:

  1. Clone a local copy of the docs repo, /sensu-docs.
  2. Run a local hugo server with offline layouts:
yarn
yarn run server --layoutDir=offline
  1. Navigate to http://localhost:1313/ and select the product and version you want to PDF. Copy the local URL.
  2. Open Acrobat and navigate to File → Create → PDF from Web Page to open the Create PDF from Web Page window.
  3. Paste the local URL in the URL: field.
  4. 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.
  1. 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.
  2. In the Web Page Conversion Settings window, click OK.
  3. In the Create PDF from Web Page window, click Create.
  4. Save the generated PDF file with this naming convention: sensu-go-5-12_sensu-docs
  5. Save the PDF in Sensu's Amazon S3 account in the sensu-docs bucket, inside the pdfs folder.

Archive a docs version

Here's how to remove a version of the docs from docs.sensu.io:

  1. Clone a local copy of the docs repo, /sensu-docs, and cd in.

  2. Use git to move the target version into the archived/sensu-go/ directory:

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

  3. 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

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

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

  5. Commit changes to the sensu-docs repo and create a pull request.

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. Clone a local copy of the docs repo, /sensu-docs, and cd in.

  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/5.0

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

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

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 minor version or a patch release:

  • If the release is a new minor version (with a new version of documentation):
    • Create an offline PDF of the new docs version.
    • Add a row in the versions.md table for the new minor version.
    • Update the link to the release notes and the offline PDF copy in AWS.
    • Mark the fourth previous version as "Not supported" in the versions.md table. For example, if you add version 5.15, mark version 5.12 as "Not supported."
  • If the release is a patch release (e.g., 5.x.x with no new version of documentation):
    • Add a row in the versions.md table for the new release.
    • Update the link to the release notes for the new version. Use the link for the offline PDF copy in AWS as for the last minor version. For example, the 5.14.2 release should link to the same offline PDF copy as 5.14.1 and 5.14.0.
Clone this wiki locally