Spike: do we have enough info in a PR's workflow to build only a portion of the c8 docs?

[pepopowitz]

Related to https://github.com/camunda/product-hub/issues/499

The vast majority of build-docs workflow executions are for PRs running checks before GitHub decides if they're mergeable. And the vast majority of those PRs are modifying no more than 1 to 3 versions of the documentation.

We should research if it's feasible to use the build-docs workflow context to decide which versions are affected by a PR, and modify the docusaurus config to only include those versions before building. If it's possible, this would allow us to merge PRs sooner. It would also likely be significantly less work than archiving old versions of the docs completely.

Timebox: a half day
Output of this spike: details added to https://github.com/camunda/product-hub/issues/499 describing the feasibility of reducing the scope of a build-docs build by excluding versions not changed in the PR.

Concerns/Questions I'd like to answer

• ✅ ❌ do we have access to file paths changed in the workflow context? This would be required to determine which versions are affected.
  • TL;DR: we can get them all for pull_request trigger; I haven't figured out how to get them all for push trigger. But we might be able to remove the push trigger entirely to simplify the workflow and unlock build time improvements.
  • See [HOLD] Spike: can we identify all changed files in a PR? #1673 for full details.
• ✅ what about link-checking? It runs in each build-docs workflow, and checks all production URLs.
  • TL;DR we can limit link-checking to a subset of versions in a way that it will still pass.
  • See [HOLD] Spike: link-checking with excluded versions #1675 for full details, including the answers to most of these questions:
    • does the build for a PR with only one version fail on link-checking?
    • can we include only a subset of URLs in the link-checking, based on the built versions?
      • link check against only the recent X versions?
      • or current version and next?
      • Only supported versions? (Might still be too much)
    • what is going wrong with daily link-checking? If we reduce the link-checking coverage of individual PRs, I'd want to rely on daily link-checking to accurately report problems.
    • can we decouple link-checking from the build-docs workflow in a reasonable manner?
    • and if so, would we just be shifting the merge check time to a new separate link-checking workflow?
  • note: we can remove link-checks against tags (tags were brought in by Best Practices and laziness)
• ✅ note that the full build will still need to occur for deployments. I think those might be using the same workflow, in which case we'd want to bifurcate it 🍴. this is not true, there are separate workflows for publishing.

[pepopowitz]

Investigation completed!