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.

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. In VS Code, search for any v1.0 references and replace them with v1.1 as applicable.
  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.

Create new website for future release

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

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

These steps require authentication.

Deploy Azure Static Web App

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

Important

You need Microsoft employee access to create a new Azure Static Web App.

  1. Use Azure PIM to elevate into the Owner role for the Dapr Prod subscription.
  2. Navigate to the docs-website resource group.
  3. Select + Create and search for Static Web App. Select Create.
  4. Enter in the following information:
    • Subscription: Dapr Prod
    • Resource Group: docs-website
    • Name: daprdocs-v1-2
    • Hosting Plan: Free
    • Region: West US 2
    • Source: Other
  5. Select Review + create, and then deploy the static web app.
  6. Wait for deployment, and navigate to the new static web app resource.
  7. Select Manage deployment token and copy the value.
  8. Navigate to the docs repo Secrets management page under Settings and create a new secret named AZURE_STATIC_WEB_APPS_V1_2, and provide the value of the deployment token.

Configure DNS

Important

This section can only be completed on a Secure Admin Workstation (SAW). If you do not have a SAW device, ask a team member with one to assist.

  1. Ensure you are a member of the DMAdaprweb security group in IDWeb.

  2. Navigate to https://prod.msftdomains.com/dns/form?environment=0 on a SAW

  3. Enter the following details in the left-hand pane:

    • Team Owning Alias: DMAdaprweb
    • Business Justification/Notes: Configuring DNS for new Dapr docs website
    • Environment: Internet/Public-facing
    • Zone: dapr.io
    • Action: Add
    • Incident ID: Leave blank

  4. Back in the new static web app you just deployed, navigate to the Custom domains blade and select + Add

  5. Enter v1-2.docs.dapr.io under Domain name. Click Next.

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

  7. Back in the domain portal, enter the following information in the main pane:

    • Name: v1-2.docs
    • Type: CNAME
    • Data: Value you just copied from the static web app

  8. Click Submit in the top right corner.

  9. Wait for two emails:

    • One saying your request was received.
    • One saying the request was completed.

  10. Back in the Azure Portal, click Add. You may need to click a couple times to account for DNS delay.

  11. An SSL is now generated for you and the DNS record is saved. This may take 2-3 minutes.

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

Configure future website branch

  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 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 the v1.2 branch.

  6. Navigate to the docs Actions page and make sure the build & release successfully completed.

  7. Navigate to the new https://v1-2.docs.dapr.io website and verify that the new version is displayed.

On the new Dapr release date

  1. Wait for all code/containers/Helm charts to be published.
  2. Merge the the PR from release_v1.0 to v1.0. Delete the release/v1.0 branch.
  3. Merge the the PR from release_v1.1 to v1.1. Delete the release/v1.1 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 September 27, 2022: Docs contributing guide updates (#2768) (73861088)