[jfdev001]

• Tickets addressed: Develop documentation did not get deployed #1664
• Review: By commit
• Merge strategy: Merge (no squash)

Description

When merging to master directly, since the merge.yml workflow does not include keep_files when deploying the master docs, the existing develop documentation is overwritten by default. This PR fixes this small bug.

Verification

N/A

Documentation

Updated release note snippet about this small fix.

Future work

N/A

[schaubh]

Thanks for the support trying to improve this publishing workflow. In this instance I pushed BSK v2.12.2 yesterday and had not yet manually triggered the develop documentation process I have to start in this instance. The documentation is now built.

I’d prefer to keep the current publishing workflow. This behavior was intentional, although the rationale was not documented clearly enough. The earlier discussion is in [PR #1266](#1266).

There are two separate reasons for the current approach:

• Remove obsolete documentation. Replacing the published output ensures that deleted or renamed pages, images, and other generated assets actually disappear. Using keep_files: true would preserve those obsolete files, potentially leaving outdated documentation accessible and allowing the published site to grow over time.
• Keep documentation history manageable. Using force_orphan: true resets the gh-pages history to a single commit when publishing stable documentation. This avoids retaining an ever-growing chain of generated-documentation commits and reduces the visual clutter those commits create in SourceTree. It also limits historical documentation retained through that branch, although reclaiming old Git objects depends on garbage collection.

The downside is that publishing stable documentation also removes /develop, which must then be rebuilt. We previously accepted this tradeoff because the development-version update following a release normally republishes those docs. For releases where that does not happen automatically, I trigger the develop documentation build explicitly.

There is also a technical issue with this particular change: peaceiris/actions-gh-pages@v3 does not support combining keep_files with force_orphan, so adding this setting would not preserve /develop as intended.

For now, I’d like to retain the existing cleanup and history-reset behavior and accept the explicit develop-documentation rebuild when needed.