Skip to content

Latest commit

 

History

History
141 lines (89 loc) · 7.31 KB

release-procedure.md

File metadata and controls

141 lines (89 loc) · 7.31 KB

Release & publish procedure

The complete documentation is fully versioned. This means that there will be no static content that is the same across all versions. The documentation contains a drop down menu to set the version including Next, a version-less preview.

Perform a patch release

Patch releases for docs can happen nearly any time, barring significant infrastructure changes. Currently, it's recommended to either ask for a release in #ask-documentation (internal Camunda employees only) or include a release date in the PR.

Issues or PRs labeled Bug will be prioritized and released as soon as possible, but may not be immediate.

To perform a patch release, confirm what is on main via staging at stage.docs.camunda.io is ready for release.

Then use the GitHub UI and follow the instructions below:

  1. Navigate to https://github.com/camunda/camunda-docs/releases and click Draft a new release
  2. Click Choose a tag and create a new tag representing the next patch release. The title with autopopulate.
  3. Click Autogenerate release notes. The Describe this release field will fill with PRs included in this release.
  4. Click Publish release.

The build process for publish-prod will kick off which could take around 30 min to finish. If publish-prod is successful, the updates will appear on docs.camunda.io.

Perform a minor release

Minor releases to Camunda 8 happen twice a year in April and October, on the second Tuesday of the month, and the documentation is versioned on the same cadence.

To prepare for a minor product release, you'll need to create a new docs version.

Create new version

The versioning process copies a snapshot of the current documentation from the un-versioned source to a new versioned source location.

Docusaurus creates the new version in versioned_docs. The contents in docs immediately become the documentation for the next release. See the versioning docs for more details on source locations of versions.

To create the new versions:

  1. Make the ./hacks/cutNewVersions.sh shell file executable, if it isn't already:

    > chmod +x ./hacks/cutNewVersions.sh

  2. Create a new branch, from main. For example, release-8.8-all-steps.

  3. Update the versions at the top of the ./hacks/cutNewVersions.sh file.

  4. Run the ./hacks/cutNewVersions.sh script:

    > ./hacks/cutNewVersions.sh

  5. Create a second branch, for example release-8.8-first-step, pointed at the first commit generated by the ./hacks/cutNewVersions.sh script. Open a PR for this branch, into main.

    Tip: This commit is very large, and will crash the browser of anyone trying to review it. Use the GitHub CLI to create this PR, to avoid crashing your own browser. Example:

    gh pr create --assignee @me --title "release(8.8): release version 8.8 (the big PR)"

  6. Switch back to the original branch, e.g. release-8.8-all-steps.

  7. Make manual updates for the new version:

    1. Ensure the "unmaintained" banner does not appear for supported versions. We currently support all versions of Camunda 8 since none are older than 18 months.

      // 👋 When cutting a new version, remove the banner for maintained versions by adding an entry. Remove the entry to versions >18 months old.
   versions: {
      "8.3": {
         banner: "none",
      },
   },

    2. Ensure the older docs do not appear in the sitemap. Only the unversioned links should appear in the sitemap.

      In docusaurus.config.js, add the previously current version number to the ignorePatterns array:

      sitemap: {
   changefreq: "weekly",
   priority: 0.5,
   ignorePatterns: [
   "/docs/8.3/**",
   ],
},

  8. Fix cross-version links.

    Cross-version linking will often break when a new version is cut. All but the first in this need to be corrected:

    • Links that are intentionally crossing versions.
    • Links that are accidentally crossing versions, i.e. markdown paths that mistakenly begin with docs/ or browser paths that mistakenly lack a .md file extension.
    • DocCardList links, which currently require a browser path.

  9. Correct redirects.

    Adjust the .htaccess file to account for URL changes due to modifying vCurrent.

    • Remove the /next version from redirects located in the new current version's section.
    • Add redirects for content that was moved in vNext prior to this release but not accounted for in the .htaccess.
    • Add a banner for the next version at the top of [section 3]

      camunda-docs/static/.htaccess

      Lines 144 to 150 in b44afba

      ##################################################################################
      # 3. Specific content moves
      ##################################################################################
      #---------------------------------------------------------------------------------
      # 8.8: content moves introduced prior to the release of version 8.8.
      #---------------------------------------------------------------------------------
      ), to guide authors to locate their vNext redirects correctly.

    See this example for guidance.

  10. Open a second PR from the branch that includes all steps (e.g. release-8-8-all-steps), targeting the branch from the first PR (e.g. release-8-8-first-step`). This PR will be much easier for users to review in the GitHub UI, since it does not include the massive amount of content changes in the first step.

    Tip: Use the GitHub CLI to create this PR also. Specify the --base option to target the first PR. Example:

    gh pr create --base "release-8-8-first-step" --assignee @me --title "release(8.8): release version 8.8 (the reviewable PR)"

  11. With successful build and approval, merge the second PR into the first. Then merge the first into main.

Release the new version

Use the GitHub UI and follow the instructions below:

  1. Navigate to https://github.com/camunda/camunda-docs/releases and click Draft a new release
  2. Click Choose a tag and create a new tag representing the minor release. The title with autopopulate.
  3. Click Autogenerate release notes. The Describe this release field will fill with PRs included in this release.
  4. Click Publish release.

The build process for publish-prod will kick off which could take around 30 min to finish. If publish-prod is successful, the updates will appear on docs.camunda.io.

Algolia crawler (DocSearch)

The Algolia crawler runs as soon as a production publish completes.

How to manually trigger Algolia crawler

Manually triggering the Algolia crawler is not intuitive(!!!) and requires admin access. Contact @akeller for assistance.

  1. Login to the Algolia dashboard.
  2. In the bottom left corner, click ** Data sources **, and after the UI loads, click ** Crawler **. If the sidebar is collapsed, you may only see a database icon (it looks like a barrel) instead of Data sources.
  3. Click camunda, which should show the status Idle.
  4. Click Resume crawling in the upper right corner. It will change to Cancel crawl, and the UI should update.

Once the crawl is complete, you should see the updates you expected as search results.