dx(rest-docs): Use stable branch if it exists

[alexronquillo]

Description

During development of a minor release, updates are going into the camunda repo's main branch, so we need to use main during this time to keep the docs up to date with the alpha releases. However, toward the end of the dev cycle for the minor version, engineering cuts a stable version branch stable/8.x and starts including code for the next version in main. At this point, we need to stop using main and switch to the stable branch until the minor version ships. After that, we need to switch back to using main.

In this PR, we added some code that does the following:

• Get the latest docs release tag (for example, 8.8.123)
• From that, increment the minor version to calculate the next minor (8.9)
• Next, we use that to check if there is a stable camunda branch for the next minor (stable/8.9)
• If there is a stable branch, we checkout that branch locally and use those specs to generate the docs
• If there isn't a stable branch, we use main

Testing

Used stable branch when tested against 8.9 ✅

https://github.com/camunda/camunda-docs/actions/runs/22615986169/job/65528871080

Found a stable branch: origin/stable/8.9

/usr/bin/git -c protocol.version=2 fetch --no-tags --prune --no-recurse-submodules --filter=blob:none --depth=1 origin +refs/heads/stable/8.9*:refs/remotes/origin/stable/8.9* +refs/tags/stable/8.9*:refs/tags/stable/8.9*

From https://github.com/camunda/camunda
  * [new branch]      stable/8.9 -> origin/stable/8.9

Used main when tested against 8.10 ✅

https://github.com/camunda/camunda-docs/actions/runs/22616567338/job/65530819477

No stable branch for version 8.10, using main

/usr/bin/git -c protocol.version=2 fetch --no-tags --prune --no-recurse-submodules --filter=blob:none --depth=1 origin +refs/heads/main*:refs/remotes/origin/main* +refs/tags/main*:refs/tags/main*

From https://github.com/camunda/camunda
  * [new branch]      main          -> origin/main
  * [new branch]      main-20240716 -> origin/main-20240716

When should this change go live?

• This is a bug fix, security concern, or something that needs urgent release support. (add bug or support label)
• This is already available but undocumented and should be released within a week. (add available & undocumented label)
• This is on a specific schedule and the assignee will coordinate a release with the Documentation team. (create draft PR and/or add hold label)
• This is part of a scheduled alpha or minor. (add alpha or minor label)
• There is no urgency with this change (add low prio label)

PR Checklist

• The commit history of this PR is cleaned up, using {type}(scope): {description} commit message(s)

• My changes are for an upcoming minor release and are in the /docs directory (version 8.9).
• My changes are for an already released minor and are in a /versioned_docs directory.

• I added a DRI, team, or delegate as a reviewer for technical accuracy and grammar/style:
  • Engineering team review
  • Technical writer review via @camunda/tech-writers unless working with an embedded writer.

[korthout]

👍 Nice work @alexronquillo

🔧 Please have a look at my comments before merging.

[korthout]

👍 Nice! I checked whether sort also works with cases like 8.10.0, but it works correctly.

[alexronquillo]

Updated per review

[mesellings]

Lgtm, would be interested to see if @jwulf had any input before we merge it however?

[mesellings]

@alexronquillo feel free to merge if we don't hear from @jwulf by EOD tomorrow so we don't block @korthout for too long, we can always follow up with any comments etc if needed 👍