How-To: Maintain the Radius docs

Learn about the Radius docs maintenance process

In this guide, you’ll learn how to perform routine Radius docs maintainer and approver responsibilities. In order to successfully accomplish these tasks, you need either approver or maintainer status in the radius-project/docs repo.

To learn how to contribute to Radius docs, review the Contributor guide.

Branch guidance

The Radius docs handles branching differently than most code repositories. Instead of a main branch, every branch is labeled to match the major and minor version of a runtime release, plus an edge branch for in-flight work. For example, the v1.0 branch contains the docs for the v1.0 release. The edge branch contains the latest in-flight work.

Managing content between branches

As a docs approver or maintainer, you need to perform routine upmerges to keep the pre-release edge branch aligned with updates to the current release branch. It is recommended to upmerge the current branch into the pre-release branch on a weekly basis.

For the following steps, treat v1.0 as the current release and edge as the pre-release branch.

  1. Open Visual Studio Code to the Radius docs repo.

  2. From your local repo, switch to the latest branch (v1.0) and synchronize changes:

    git pull upstream v1.0
git push origin v1.0

  3. Switch to the upcoming branch (edge) and synchronize changes:

    git pull upstream edge
git push origin edge

  4. Create a new branch from edge:

    git checkout -b upmerge_MM-DD

  5. Open a terminal and stage a merge from the latest release into the upmerge branch:

    git merge --no-ff --no-commit v1.0

  6. Make sure included files look accurate. Inspect any merge conflicts in VS Code. Remove configuration changes or version information that does not need to be merged. Examples of files that usually shouldn’t be merged:

    • docs/config.toml
    • docs/layouts/partials/hooks/body-end.html
    • docsy sub-module

  7. Commit the staged changes and push to the upmerge branch (upmerge_MM-DD).

  8. Open a PR from the upmerge branch to the upcoming release branch (edge).

  9. Review the PR and double check that no unintended changes were pushed to the upmerge branch.