Skip to content

Latest commit

 

History

History
88 lines (65 loc) · 4.8 KB

VERSIONED-CONTENT.md

File metadata and controls

88 lines (65 loc) · 4.8 KB
Raw

Version Conent

One goal of the documentation effort is to have versioned content: anyone using Bottlerocket can browse documentation and know the information only applies to a specific version they specify. To accomplish this, the documentation must have multiple copies of the content, often varying only slightly between versions.

Note: This document is designed to be mostly general to any section (e.g. OS, brupop, etc.), so specific tasks to a particular section will be explicitly called out.

Version Content Scoping

The documentation content for each version is scoped to major/minor version lines, but not patches. As an example: 1.13.x and 1.14.x will have separate copies of the documentation, but 1.14.1 and 1.14.2 do not. In the rare situation where functionality or changes appear at a patch boundary, the change will be merged into minor as users are generally expected to keep software updated to the latest patch.

Branching strategy

This site uses Hugo which generates HTML off a single branch, prod, which is distinct from main . prod is the source for the GitHub Pages output and any merged code takes immediate effect. main represents the in-progress version of the current state of the site. Upcoming versions of the site are maintained in project-version branches. As a consequence, a new branch is created for each version and documentation works one version forward of current. Consequently, when the current version is released, a new branch is created for the next version. Example:

Version 1.14.0 is released.
    +-- Branch 1.14.x is merged
    +-- Branch 1.15.x is created
    .
    .
    .
Version 1.15.0 is released
    +-- Branch 1.15.x is merged
    +-- Branch 1.16.x is created

Adding or merging a new version branch

When a new branch is created, the previous versioned documentation is duplicated in the new branch at the correct place in the directory tree. This allows for each version to be edited and published independently. When merging a new branch, git will see all these files as net-new adds, so reviewing becomes difficult. As a courtesy to reviewers, adding a manual diff between the current and new context directories in the body of the PR will assist in review. This can be accomplished with the diff tool with the recursive option on Unix-like systems:

Example:

diff -c --recursive 1.13.x/ 1.14.x/

Task: Change the current version

The data/versions/current.toml dictates how various shortcodes will know the ‘current’ version of any given project. This needs to be updated on every version release. Additionally, the foldable menu needs to be directed to be opened, which can be accomplished by adding the HTML ID of the invisible “check” box to the foldable_check_id field; this is deterministically generated by Hugo and will follow the format of #m-<lang code><project><major><minor>x-check (for example 1.15.x of the OS will #m-enos115x-check ) and can be verified using browser DevTools.

Example, for version 1.15.1 of the OS (bottlerocket-os/bottlerocket), you would update the following section:

[os]
    major = 1
    minor = 15
    patch = 1
    foldable_check_id = "#m-enos115x-check"

OS Section special tasks

When updating the OS section (which documents bottlerocket-os/bottlerocket), there are a few extra tasks.

Update the variants

Variant information for the new version should be generated and placed into the [lang]/os/[minor version]/version-information/variants/ directory on every minor release. This can be accomplished with the variant-kernel script. See/scripts/variant-kernel/README.md for more information.

Update the package versions

The inventory of the package versions should be updated on every minor and patch release and placed in the [lang]/os/[minor version]/version-information/packages/[full version] directory. This can be accomplished with the software-version-inventory script. See/scripts/software-versions-inventory/README.md for more information.

Handling changes to the current version

If a contribution comes in on the current version and the information applies to both current and future versions, the changes will need to be manually pulled forward. For example: /content/en/os/1.13.x/concepts/api-driven/index.markdown receives a contribution while 1.14.x is being worked on. The maintainer will need to evaluate if the contribution is also relevant for 1.14.x. If the contribution is relevant for just the 1.13.x line, then the contribution can be merged as-is. If the contribution is relevant for both versions, the maintainer makes an issue noting to integrate the contributed content into the new version and asks the contributor to make a further contribution to resolve that issue.