doc: add checks on docs integration - #1480
Conversation
The docs integration often depends on overwriting files in the upstream LXD, MicroCeph, and MicroOVN repositories. If those files move or if configuration settings change, it is possible for the build to complete successfully, but with incorrect settings or other issues. This commit separates the `integrate` process in the docs Makefile into several steps: - `integrate-pull` clones the upstream repositories and pins them to specific commits - `integrate-precheck` (depends on `integrate-pull`) confirms that various files are located where expected, and are configured as expected - `integrate` (depends on `integrate-precheck`) copies and overwrites files, and builds the documentation Signed-off-by: Elijah Greenstein <elijah.greenstein@canonical.com>
|
Related to #1475, with regard to the |
|
@roosterfish -- these are some checks intended to catch changes to the upstream repositories before building and serving the integrated documentation. As you can see, I've currently set these up so that the build fails if there are any issues. However, I also considered setting the checks up as make target that could be triggered as a GitHub workflow, such that the build could complete regardless of the status of the checks. Do you have any thoughts on these two approaches? Ultimately I decided on having the build fail. If, for example, the MicroOVN header template is moved to a new directory, it's possible for the build to complete but the built docs to be set up incorrectly. I believe this was the kind of issue that we had with MicroCeph in the MicroCloud 2 docs that was resolved with this PR: #1454. |
I think it's ok to have a failing build in this case as it indicates we have to update our doc set accordingly. |
There was a problem hiding this comment.
Pull request overview
This PR improves the docs integration workflow by splitting the existing integrate target into discrete steps so upstream-repo assumptions are validated before files are overwritten and docs are built.
Changes:
- Split upstream repo fetching into a new
integrate-pulltarget. - Add an
integrate-prechecktarget that validates expected upstream file locations and key template/config assumptions before integration. - Make
integratedepend onintegrate-precheckto enforce the validation gate.
Suppressed comments (1)
doc/Makefile:89
- The fetch/clone logic will run
git clonewhenevergit -C … fetchfails (e.g., transient network error or a local repo issue), which can produce a misleading failure like “destination path already exists” and hide the real fetch problem. Consider cloning only when the repo directory doesn’t exist, and otherwise failing on fetch errors.
integrate-pull:
# Pull the other repositories
cd integration/ && ( git -C lxd fetch || git clone https://github.com/canonical/lxd )
git -C integration/lxd reset --hard $(LXDVERSION)
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| @@ -92,10 +93,72 @@ integrate: | |||
| cd integration/ && ( git -C microovn fetch || git clone https://github.com/canonical/microovn ) | |||
| git -C integration/microovn reset --hard $(MICROOVNVERSION) | |||
There was a problem hiding this comment.
Seems unrelated to me as the PR doesn't change the pinning behavior.
The docs integration often depends on overwriting files in the upstream LXD, MicroCeph, and MicroOVN repositories. If those files move or if configuration settings change, it is possible for the build to complete successfully, but with incorrect settings or other issues.
This commit separates the
integrateprocess in the docs Makefile into several steps:integrate-pullclones the upstream repositories and pins them to specific commitsintegrate-precheck(depends onintegrate-pull) confirms that various files are located where expected, and are configured as expectedintegrate(depends onintegrate-precheck) copies and overwrites files, and builds the documentation