Skip to content

Release related docs updates

Jump to bottom
Hillary Fraley edited this page Sep 15, 2022 · 34 revisions

Add release notes (all releases)

Add the new version's release notes to the Release Notes page, release-notes.md, each time we release a version of Sensu Go.

Release notes are compiled based on the sensu/sensu-go and sensu/sensu-enterprise-go changelogs. When the changelogs are frozen (no further updates are expected), the release coordinator will post their links in the #sensu-release channel.

The content of the release notes will depend on what's included in each release, but the steps for adding release notes is the same for all releases:

  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>/rel-notes

  3. Open the release notes file: sensu/sensu-docs/content/sensu-go/<version>/release-notes.md.

  4. In the release notes file, create a new line for the new release at the top of the manual table of contents. For example, if the release number is 6.8.1, the table of contents line should be:

    - [6.8.1 release notes](#681-release-notes)

  5. Scroll to the end of the table of contents in the release notes file and paste in a content template:

    ## 6.8.1 release notes

**<Month> <DD>, <YYYY>** &mdash; The latest release of Sensu Go, version 6.8.1, is now available for download.

<Release synopsis>

Read the [upgrade guide][1] to upgrade Sensu to version 6.8.1.

**NEW FEATURES:**

- .

**IMPROVEMENTS:**

- .

**FIXES:**

- .

  6. Following the sensu/sensu-go and sensu/sensu-enterprise-go changelogs, fill in the release notes content template.

    • Use the release notes for previous releases as examples for formatting concerns like capitalization, punctuation, and links. If you can't find a consistent example, follow your best judgment.
    • In the release notes, use only the NEW FEATURES, IMPROVEMENTS, and FIXES categories for the notes. The changelogs may use different categories or list a fix as an improvement. Use your judgment to place notes for each change in the best category in the release notes. Exception: If a release includes breaking changes, add a fourth category: BREAKING CHANGES FOR SENSU GO <RELEASE_NUMBER>.
    • Do not include any changes that are not customer-facing. For example, we have not listed the core/v3 entities change in the release notes because it is not yet customer-facing.
    • List any changes that affect commercial features first. Each note that describes a change to a commercial feature should begin with a ([Commercial feature][295]) designation. The number is a link reference (scroll to the bottom of the release-notes.md page for the list of links).
    • Links in release notes should be versioned. Do not use links that include latest or relative links that would redirect to latest. For example, to link to the commercial features page for 6.8.1, use /sensu-go/6.8/commercial/ and not /sensu-go/latest/commercial/ or ../../commercial/.
    • In addition to listing each change, release notes should indicate what each change means for users and add any context that could help users understand what the change might mean for them. If the changelog entries do not provide enough information for you to explain each change, other sources of information include the issues and PRs associated with each change in the sensu/sensu-go and sensu/sensu-enterprise-go repos.

  7. If the release is a patch, write a brief release synopsis that summarizes the changes in the release. For minor and major releases, request the release synopsis in the #sensu-release channel. You may need to add a placeholder while you wait for the synopsis so that the release notes themselves can be reviewed in a timely manner, but do not publish the release notes without a synopsis.

  8. Commit and push your changes to the sensu-docs repo and create a sensu-docs PR for the updated release notes page.

  9. Request review for the release notes PR from the release's Engineering rep.

Update the supported versions page (all releases)

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 and push 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 and push 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 version 6.4).

Update version and build numbers for release (all releases)

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

    You will see a confirmation response after running the script:

    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}/operations/deploy-sensu/install-sensu.md (build numbers) - /sensu-go/{version}/platforms.md (version numbers in AWS links)

**NOTE**: If you run the script but `git status` doesn't list any changes to the `install-sensu.md` page 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/operations/deploy-sensu/install-sensu/#install-sensu-agents for the old build number to use in the script.
  1. Commit and push 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.

Add a docs version (major and minor releases)

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.

Create an offline PDF copy of docs (major and minor releases)

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

    NOTE: Any images in SVG format, whether saved as a file or embedded with code, must be replaced in the text before continuing to step 2. The observability pipeline diagrams displayed on the Sensu Go version homepages and in the observability pipeline category index pages are embedded SVG images. PNG versions of the embedded SVG images are saved in /static/images. In the documentation source files, replace the embedded code with references to the PNG image files (for example, {{< figure src="/images/observability-pipeline.png" link="/images/observability-pipeline.png" target="_blank" >}}) before continuing to step 2.

  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.

Promote the new version to latest (major and minor releases)

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 to the new release version number in config.toml and static.json. For example, to update to version 6.4:
    • In config.toml: latest = "6.4"
    • In static.json: "~ ^/sensu-go/6.4/?((?<=\/).*)?$": {
  4. Update the Algolia search version to use the new release version number in https://github.com/sensu/sensu-docs/blob/master/layouts/partials/footer_js.html
  5. Update the noindex version in https://github.com/sensu/sensu-docs/blob/master/layouts/partials/head.html (replace the listed version number with the new release version number). For example, to update to version 6.4: 
    {{ if not (eq .Params.version "6.4") }}
<meta name="robots" content="noindex">
{{ end }}
  6. 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 (major and minor releases)

When we add a new major or minor version of Sensu Go or remove docs that are more than three major or minor versions old from the docs.sensu.io website, we create an offline PDF copy of the docs and update the Supported Versions page.

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