Releasing a version of the Knative documentation

Learn how to promote the current in-development version of the knative/docs repo (main), to a released version by creating a dedicated release-#.# branch and corresponding section knative.dev.

Before you begin

  • For updating and building website on knative.dev

    • Be granted access to Netlify for staging
      • Contact Caroline Lee or Richie Escarez

  • For GitHub

  • For building website locally:

    • Install Hugo
    • (for Mac) Install gnu-sed using brew: brew install gnu-sed
      • Update path to gnu-sed: PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH"
    • Go version 1.11+
    • Clone git@github.com:knative/website.git (has build script)

  • To create combined PRs. Make your first pull request, choose Create a new branch. Give it a name you will remember. Then when you make your subsequent updates, make sure you select the branch you just created so you can add all your changes to the same PR.

Check Eventing and Serving

Have they created related release branches? https://github.com/knative//releases/

Create matching branch for Knative docs

Once there are release branches for the three code repos, make a matching doc repo release.

Prepare the ‘main’ branch

Make sure main is in correct state:

  • Generate the latest set of API reference docs locally
    • Clone the docs repo: git clone git@github.com:knative/docs.git
    • Find the gen-api-reference-docs.sh script in the /docs/hack directory
    • Follow the instructions in the linked doc above. This creates a small set of files that document the APIs in this release. Be aware that if there have been significant changes, the script may take hours to run to completion.
  • Push to your personal GitHub repository.
  • Create a PR and check into the Knative main repository.
  • At this point the updated versions of the API docs are in knative/docs main
  • Check to make sure all changes, including install changes, have been merged into main and all hard-coded version numbers are updated. This is to make sure that any docs that have been committed outside of the normal process don’t have mechanical errors in them. This is, alas, a manual step.

Create branch from updated main

Once everything that needs to be in main is in main you need to create the release branch, using the GitHub UI.

  1. Make sure you are logged into GitHub.
  2. Select the Code tab in the Knative/docs repo.
  3. Click and open the Branch drop-down menu. Make sure that main is selected. This is the source for the new release.
  4. In the Find or create a branch text field, enter the name of the new branch you want to create: release-#.# branch The branch is created.

Make sure all links in new release branch announcement point to the appropriate peer Knative repos

  • Update all hard coded URLs to repos from “tree/main” to “tree/release-0.#”
    • For Serving, Eventing, and Eventing-contrib

Demote the previous release to archive

  • Remove the “aliases” field from the frontmatter of files from the previous release so that they look like this:

    title: “Knative contribution guidelines” linkTitle: “Contributing” weight: 20 type: “docs”

Or

  • Change the “aliases” field to point to the archived version file so “/docs//” becomes “/-docs//":

    title: “Knative contribution guidelines” linkTitle: “Contributing” weight: 20 type: “docs” aliases: /v0.9-docs/contribution-guidelines/

Not all files will have aliases on them. You just have to go through them manually. Update one, create a branch for your pull request, then update all of the others using that branch, by committing to that branch. Then create one pull request for all the changes. Make sure you make the pull request against the branch you are archiving, ie, the one before the one you just made.

Complete the release announcement and create the tag

  • On https://github.com/knative/docs/releases, click Draft a new release. release-notes tags
  • Using the box in red above, create a tag with the release (v.0..x). Copy the text of the source content from the previous release, updating the number and linking to the appropriate release notes in each of the three components.
  • Check Pre-release
  • Click Publish release (or Save draft if you are not ready to finalize).

Configure the /website build

Update the build configuration to include the new version and remove the oldest by editing the following .toml (Tom’s Obvious, Minimal Language) files. Tom’s files aren’t really obvious, but tastes vary. There are also some traditional script files. Use the github UI In the /website main branch. Click the link to go to the page to edit and insert the appropriate values:

  • Configure defaults: /website/config/_default/params.toml

    This lets the build know what the “default” release is. Add the release version you just created. default

  • Configure production builds: /website/confi/production/params.toml

    We build four versions of the docs every time - the version you just created, and the previous three versions. Set the version on line 41 to the version you just created. Set the “Archived versions” to the three previous versions. Remove any older versions. production

  • Configure local builds: /website/config/local/params.toml

    This is really just for builds you do on your machine, but update it on github as well to keep everything in sync. Set line 20 to the version you just created. local

  • Configure staging builds: /website/config/staging/params.toml

    Set line 19 to the version you just created. staging

  • Define the default branch variable:/website/scripts/docs-version-settings.sh

    This variable should be set to the version you just created. doc-version

  • Tell Netlify how to get the previous three releases by updating the three git clone commands to point to those three releases: /website/scripts/processsourcefiles.sh processsource

  • Add the just created version to line 24 of the Netlify toml file. The :splat keeps the links to the three previous versions alive, so the current version + the previous 3 versions that are still being built. The bottom release that fell out of the top four should be added to the redirects below line 29. Any links to these versions are redirected back to the most current version: /website/netlify.toml netlify

Test the content

  • Update your local versions of the build config files to run a local build.
  • Run a local build using from the /website directory: scripts/localbuild.sh. Follow the extensive instructions at the top of the script file.
  • Check to make sure everything looks okay.
  • Sync your changes to the staging branch with git pull –rebase upstream main and git push upstream staging. {need more detail}

Check the staging (Deploy Preview) build on Netlify