Hi Andrea, On Thu, Dec 2, 2021 at 10:25 AM Andrea <and...@tarocch.it> wrote: > I have one practical question though: right now, which is the recommended > practice to check if a new release of a sub-project brake the website build?
I'm deliberately not going to consider a release event as it is not a release that breaks the website but a change made in the documentation or configuration of Antora and that can be done independently of a release. In general I have seen these two cases most often: A. A change was made, and existing documentation is affected. Examples of this are: Camel Quarkus documentation pointing to Camel Component Reference that doesn't or no longer exists; a page was removed from the Camel User Manual that is referenced from Camel K; or a version of Camel Component Reference was unpublished from the website and Camel Kafka Connectors documentation is referencing it. This shows up as a broken xref when building the documentation, the error message says what document on what branch is using what xref that can no longer be dereferenced. B. New branch of documentation was configured in the Antora playbook, but the descriptors on that branch haven't been updated to match the version. This shows up as a "duplicate nav" error, explaining that there are sources of a document with the same page coordinates (component name, module name, version, path). Both of these cases can be detected by running the build locally with the proposed changes. Those changes don't need to be committed/pushed. There is an example of such workflow in the website README[1]. In some (sub-)projects there are xref checks that are run in the local context as a part of the build, those can detect only a subset of issues, i.e. they typically can't detect an issue outside of the branch being built. We could, and David is proposing that we do, invest more effort to build better xref checks, see the other thread on incremental builds using site manifests. zoran [1] https://github.com/apache/camel-website/#working-on-documentation-asciidoc-content -- Zoran Regvart
