Maintainer guide

Get started as a Dapr docs maintainer and approver.

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

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

Branch guidance

The Dapr 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.

For the full list, visit the Docs repo.

Read the contributor’s guide for more information about release branches.

Upmerge from current release branch to the pre-release branch

As a docs approver or maintainer, you need to perform routine upmerges to keep the pre-release 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 v1.1 as the upcoming release.

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

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

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

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

    1. git pull upstream v1.1
    2. git push origin v1.1

  4. Create a new branch based off of the upcoming release:

    1. git checkout -b upmerge_MM-DD

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

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

  6. In the terminal, 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.

  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 (v1.1).

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

Release process

Dapr docs must align with features and updates included in the Dapr project release. Leading up to the Dapr release date, make sure:

  • All new features or updates have been sufficiently documented and reviewed.
  • Docs PRs for the upcoming release point to the release branch.

For the following steps, treat v1.0 as the latest release and v1.1 as the upcoming release.

The release process for docs requires the following:

  • An upmerge of the latest release into the upcoming release branch
  • An update to the latest and upcoming release Hugo configuration files
  • A new Azure Static Web App for the next version
  • A new DNS entry for the next version’s website
  • A new git branch for the next version

Upmerge

First, perform a docs upmerge from the latest release to the upcoming release branch.

Update Hugo Configuration

After upmerge, prepare the docs branches for the release. In two separate PRs, you need to:

  • Archive the latest release.
  • Bring the preview/release branch as the current, live version of the docs.
  • Create a new preview branch.

Latest release

These steps will prepare the latest release branch for archival.

  1. Open VS Code to the Dapr docs repo.

  2. Switch to the latest branch (v1.0) and synchronize changes:

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

  3. Create a new branch based off of the latest release:

    1. git checkout -b release_v1.0

  4. In VS Code, navigate to /daprdocs/config.toml.

  5. Add the following TOML to the # Versioning section (around line 154):

    1. version_menu = "v1.0"
    2. version = "v1.0"
    3. archived_version = true
    4. url_latest_version = "https://docs.dapr.io"
    6. [[params.versions]]
    7.   version = "v1.2 (preview)"
    8.   url = "v1-2.docs.dapr.io"
    9. [[params.versions]]
    10.   version = "v1.1 (latest)"
    11.   url = "#"
    12. [[params.versions]]
    13.   version = "v1.0"
    14.   url = "https://v1-0.docs.dapr.io"

  6. Delete .github/workflows/website-root.yml.

  7. Commit the staged changes and push to your branch (release_v1.0).

  8. Open a PR from release_v1.0 to v1.0.

  9. Have a docs maintainer or approver review. Wait to merge the PR until release.

Upcoming release

These steps will prepare the upcoming release branch for promotion to latest release.

  1. Open VS Code to the Dapr docs repo.

  2. Switch to the upcoming release branch (v1.1) and synchronize changes:

    1. git pull upstream v1.1
    2. git push origin v1.1

  3. Create a new branch based off of the upcoming release:

    1. git checkout -b release_v1.1

  4. In VS Code, navigate to /daprdocs/config.toml.

  5. Update line 1 to baseURL - https://docs.dapr.io/.

  6. Update the # Versioning section (around line 154) to display the correct versions and tags:

    1. # Versioning
    2. version_menu = "v1.1 (latest)"
    3. version = "v1.1"
    4. archived_version = false
    5. url_latest_version = "https://docs.dapr.io"
    7. [[params.versions]]
    8.   version = "v1.2 (preview)"
    9.   url = "v1-2.docs.dapr.io"
    10. [[params.versions]]
    11.   version = "v1.1 (latest)"
    12.   url = "#"
    13. [[params.versions]]
    14.   version = "v1.0"
    15.   url = "https://v1-0.docs.dapr.io"

  7. Navigate to .github/workflows/website-root.yml.

  8. Update the branches which trigger the workflow:

    1. name: Azure Static Web App Root
    3. on:
    4.   push:
    5.     branches:
    6.       - v1.1
    7.   pull_request:
    8.     types: [opened, synchronize, reopened, closed]
    9.     branches:
    10.       - v1.1

  9. Navigate to /README.md.

  10. Update the versions table:

  1. | Branch                                                       | Website                    | Description                                                                                      |
  2. | ------------------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------ |
  3. | [v1.1](https://github.com/dapr/docs) (primary)               | https://docs.dapr.io       | Latest Dapr release documentation. Typo fixes, clarifications, and most documentation goes here. |
  4. | [v1.2](https://github.com/dapr/docs/tree/v1.2) (pre-release) | https://v1-2.docs.dapr.io/ | Pre-release documentation. Doc updates that are only applicable to v1.2+ go here.                |
  1. Update the dapr-latest-version.html shortcode partial to the new minor/patch version (in this example, 1.1.0 and 1.1).
  2. Commit the staged changes and push to your branch (release_v1.1).
  3. Open a PR from release/v1.1 to v1.1.
  4. Have a docs maintainer or approver review. Wait to merge the PR until release.

Future preview branch

Create preview branch
  1. In GitHub UI, select the branch drop-down menu and select View all branches.
  2. Click New branch.
  3. In New branch name, enter the preview branch version number. In this example, it would be v1.2.
  4. Select v1.1 as the source.
  5. Click Create new branch.
Configure preview branch

  1. In a terminal window, navigate to the docs repo.

  2. Switch to the upcoming release branch (v1.1) and synchronize changes:

    1. git pull upstream v1.1
    2. git push origin v1.1

  3. Create a new branch based on v1.1 and name it v1.2:

  1. git checkout -b release_v1.1

  1. Rename .github/workflows/website-v1-1.yml to .github/workflows/website-v1-2.yml.

  2. Open .github/workflows/website-v1-2.yml in VS Code and update the name, trigger, and deployment target to 1.2:

    1. name: Azure Static Web App v1.2
    3. on:
    4.   push:
    5.     branches:
    6.       - v1.2
    7.   pull_request:
    8.     types: [opened, synchronize, reopened, closed]
    9.     branches:
    10.       - v1.2
    12.  ...
    14.      with:
    15.        azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_V1_2 }}
    16.        repo_token: ${{ secrets.GITHUB_TOKEN }}
    18.  ...
    20.      with:
    21.        azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_V1_2 }}
    22.        skip_deploy_on_missing_secrets: true

  3. Navigate to daprdocs/config.toml and update the baseURL to point to the new preview website:

    1. baseURL = "https://v1-2.docs.dapr.io"

  4. Update the # GitHub Information and # Versioning sections (around line 148) to display the correct versions and tags:

    1. # GitHub Information
    2. github_repo = "https://github.com/dapr/docs"
    3. github_project_repo = "https://github.com/dapr/dapr"
    4. github_subdir = "daprdocs"
    5. github_branch = "v1.2"
    7. # Versioning
    8. version_menu = "v1.2 (preview)"
    9. version = "v1.2"
    10. archived_version = false
    11. url_latest_version = "https://docs.dapr.io"
    13. [[params.versions]]
    14.   version = "v1.2 (preview)"
    15.   url = "#"
    16. [[params.versions]]
    17.   version = "v1.1 (latest)"
    18.   url = "https://docs.dapr.io"
    19. [[params.versions]]
    20.   version = "v1.0"
    21.   url = "https://v1-0.docs.dapr.io"

  5. Commit the staged changes and push to a new PR against the v1.2 branch.

  6. Hold on merging the PR until after release and the other v1.0 and v1.1 PRs have been merged.

Create new website for future release

Next, create a new website for the future Dapr release. To do this, you’ll need to:

  • Deploy an Azure Static Web App.
  • Configure DNS via request from CNCF.

Prerequisites

  • Docs maintainer status in the dapr/docs repo.
  • Access to the active Dapr Azure Subscription with Contributor or Owner access to create resources.
  • Azure Developer CLI installed on your machine.
  • Your own fork of the dapr/docs repo cloned to your machine.

Deploy Azure Static Web App

Deploy a new Azure Static Web App for the future Dapr release. For this example, we use v1.1 as the future release.

  1. In a terminal window, navigate to the iac/swa folder in the dapr/docs directory.

    1. cd .github/iac/swa

  2. Log into Azure Developer CLI (azd) using the Dapr Azure subscription.

    1. azd login

  3. In the browser prompt, verify you’re logging in as Dapr and complete the login.

  4. In a new terminal, replace the following values with the website values you prefer.

    1. export AZURE_RESOURCE_GROUP=rg-dapr-docs-test
    2. export IDENTITY_RESOURCE_GROUP=rg-my-identities
    3. export AZURE_STATICWEBSITE_NAME=daprdocs-latest

  5. Create a new azd environment.

    1. azd env new

  6. When prompted, enter a new environment name. For this example, you’d name the environment something like: dapr-docs-v1-1.

  7. Once the environment is created, deploy the Dapr docs SWA into the new environment using the following command:

    1. azd up

  8. When prompted, select an Azure subscription and location. Match these to the Dapr Azure subscription.

Configure the SWA in the Azure portal

Head over to the Dapr subscription in the Azure portal and verify that your new Dapr docs site has been deployed.

Optionally, grant the correct minimal permissions for inbound publishing and outbound access to dependencies using the Static Web App > Access control (IAM) blade in the portal.

Configure DNS

  1. In the Azure portal, from the new SWA you just created, naviage to Custom domains from the left side menu.

  2. Copy the “CNAME” value of the web app.

  3. Using your own account, submit a CNCF ticket to create a new domain name mapped to the CNAME value you copied. For this example, to create a new domain for Dapr v1.1, you’d request to map to v1-1.docs.dapr.io.

    Request resolution may take some time.

  4. Once the new domain has been confirmed, return to the static web app in the portal.

  5. Navigate to the Custom domains blade and select + Add.

  6. Select Custom domain on other DNS.

  7. Enter v1-1.docs.dapr.io under Domain name. Click Next.

  8. Keep Hostname record type as CNAME, and copy the value of Value.

  9. Click Add.

  10. Navigate to https://v1-1.docs.dapr.io and verify a blank website loads correctly.

You can repeat these steps for any preview versions.

On the new Dapr release date

  1. Wait for all code/containers/Helm charts to be published.
  2. Merge the PR from release_v1.0 to v1.0. Delete the release/v1.0 branch.
  3. Merge the PR from release_v1.1 to v1.1. Delete the release/v1.1 branch.
  4. Merge the PR from release_v1.2 to v1.2. Delete the release/v1.2 branch.

Congrats on the new docs release! 🚀 🎉 🎈

Pull in SDK doc updates

SDK docs live in each of the SDK repos. Changes made to the SDK docs are pushed to the relevant SDK repo. For example, to update the Go SDK docs, you push changes to the dapr/go-sdk repo. Until you pull the latest dapr/go-sdk commit into the dapr/docs current version branch, your Go SDK docs updates won’t be reflected on the Dapr docs site.

To bring updates to the SDK docs live to the Dapr docs site, you need to perform a straightforward git pull. This example refers to the Go SDK, but applies to all SDKs.

  1. Pull the latest upstream into your local dapr/docs version branch.

  2. Change into the root of the dapr/docs directory.

  3. Change into the Go SDK repo. This command takes you out of the dapr/docs context and into the dapr/go-sdk context.

    1. cd sdkdocs/go

  4. Switch to the main branch in dapr/go-sdk.

    1. git checkout main

  5. Pull the latest Go SDK commit.

    1. git pull upstream main

  6. Change into the dapr/docs context to commit, push, and create a PR.

Next steps

For guidance on contributing to Dapr docs, read the Contributor Guide.

Last modified October 11, 2024: Fixed typo (#4389) (fe17926)