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](https://github.com/sensu/sensu-docs/blob/master/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](https://docs.sensu.io/sensu-go/latest/versions/), 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.

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

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.

New major or minor versions also require an [offline PDF](#create-an-offline-pdf-copy-of-docs) for the new docs version.

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

## 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](https://docs.sensu.io/) site pages.

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


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](#create-an-offline-pdf-copy-of-docs)
- [Archive a docs version](#archive-a-docs-version)
- [Update the Supported Versions page](#update-the-supported-versions-page)

### 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


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-5-12_sensu-docs`
11. 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/6.3/ 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/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

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



## 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 = "6.4"`) in [config.toml](https://github.com/sensu/sensu-docs/blob/master/config.toml) and [static.json](https://github.com/sensu/sensu-docs/blob/master/static.json).
  - In config.toml: `latest = "6.4"`
  - In static.json: `"~ ^/sensu-go/6.4/?((?<=\/).*)?$": {`
2. Update the Algolia search version in https://github.com/sensu/sensu-docs/blob/master/layouts/partials/footer_js.html
3. 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.
Clone this wiki locally