bamaer opened a new issue, #8885: URL: https://github.com/apache/hop/issues/8885
### What needs to happen? ## Problem Hop-website build [#511](https://ci-builds.apache.org/job/Hop/job/Hop-website/job/main/511/) fails in the `Checks` stage (`npm run check:links`). Verify artifact and Deploy are skipped, so the site is not updated. The last successful build is #484. ``` anchor not found from dev-manual/next/annotation-derived-widgets.html to dev-manual/next/annotation-derived-widgets.html#manual::hop-gui/disable-ui-elements.adoc 1 errors and 0 warnings ``` The source is `docs/hop-dev-manual/modules/ROOT/pages/annotation-derived-widgets.adoc:71`, added in #8636: ``` See xref:manual::hop-gui/disable-ui-elements.adoc[Disabling UI elements]. ``` An unversioned cross-component xref goes to the latest stable version of the target component. On the website that is `manual` 2.19.0, because 2.20.0 is a prerelease. `hop-gui/disable-ui-elements.adoc` does not exist on `release/2.19.0`, so the xref cannot be resolved. ## Why the PR check passed `.github/workflows/pr_build_docs.yml` builds with `antora-playbook-hop.yml` from apache/hop-website. That playbook reads only the `HEAD` checkout, so the build contains a single version of each component (2.20.0, prerelease). There, `manual::` goes to 2.20.0 and the page exists. The "Antora build" check on #8636 passed. The website build (`antora-playbook.yml`) reads `main` plus every `release/*` branch, so the same xref goes to 2.19.0. ## Unversioned cross-component xrefs on main `manual::` from the dev manual: - `annotation-derived-widgets.adoc` (target missing in 2.19.0) - `architecture/logging-and-debugging.adoc` - `database/index.adoc` - `hopweb/index.adoc` - `index.adoc` - `plugin-types/gui.adoc` - `plugin-types/metadata-configuration.adoc` `dev-manual::` from the user manual: - `installation-configuration.adoc` - `technology/openlineage/index.adoc` (2 xrefs) All targets except `hop-gui/disable-ui-elements.adoc` exist in 2.19.0. Each of these xrefs breaks as soon as it points to a page that is not in the latest release. `docs/hop-dev-manual/modules/ROOT/pages/writing-documentation.adoc:46` documents the unversioned form as the way to link across manuals. ## Proposed changes 1. Pin all xrefs listed above with `{page-component-version}@`, for example `xref:{page-component-version}@manual::hop-gui/disable-ui-elements.adoc[...]`. 12 xrefs in `docs/` already use this form. 2. Update `writing-documentation.adoc` to document the versioned form. 3. In `pr_build_docs.yml`, fail on unversioned cross-component xrefs (`xref:manual::`, `xref:dev-manual::`) under `docs/`. 4. Optionally, have the PR build also read the latest `release/*` branch, so that xrefs resolve the same way as on the website, and run `npm run check:links` on the `next/` output. This needs a playbook change in apache/hop-website. ### Issue Priority Priority: 2 ### Issue Component Component: Website, Component: Documentation -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
