Hi Andrea & Cameleers, On Thu, Dec 16, 2021 at 8:36 PM Andrea Cosentino <anco...@gmail.com> wrote: > I would like to stress once again how much it's becoming non-deterministic > to build the website.
I'm surprised that the build of the website is deemed non-deterministic, and not the changes to the documentation. I've found that the vast majority of website build failures were due to changes to the documentation and not caused by the build process. Last issue[1] that caused the website (not the build) to break was when a change I made[2] broke loading CSS resources in the Antora part of the website. I take full responsibility for that and I do wish that I had caught that issue sooner, and I'm trying to find some time to add more tests (e.g. visual regression tests[3]) to catch that. Nonetheless, this was the first issue of this kind that I can remember -- and I'll accept more feedback on this. A lot of thought and effort has been and is done to increase the robustness, ease maintainability and the overall quality of the website, most of this work has been done by David and to a lesser degree by me. I think we have to remember, when the website build fails an issue has been detected that could/will break the live website. We don't have a staging process, all changes go directly live. I think we should make every effort not to break the live website while allowing for frequent website updates at the same time. Failing builds are a part of that. The work David is proposing on partial builds will help with that by allowing us to run quick local checks and in the future quick checks on PRs. This will provide another, much earlier, barrier preventing the website build failure. If folk want to help with that I'm sure David is eager to see any help or comments on that. > This is becoming everyday more complicated than it should be. Can you elaborate on this? The website in itself is very complex, it has two distinct ways of generating and rendering the resulting HTML that we managed to marry together, we have ten git repositories and I can't count how many branches that need to be in a correct state for the documentation to build: i.e. contain proper versions, don't contain syntax issues or broken links. I'd be happy to help and work on any issue that anyone thinks is unnecessarily complicated. > I think we need to focus on this. Because we shouldn't postpone a release > for reason like this. I agree, and I think a good way to help is to do reviews and suggest improvements. The issue[1] I mentioned above was caused by a pull request that I, being a large change, left in review for a significant amount of time. I failed to check the preview properly, i.e. I checked the Hugo bits that were causing problems, but failed to check a clean Antora build that was done on the PR; so having a local build that was not a clean build masked the issue for me. > Building the website should be something like black magic and voodoo > invocation. It should work much more easily. To build the website one needs to follow the instructions[4], I understand that for mainly Java developers this can seem like black magic, I can only assure folk that it isn't. I'd be happy to work on improving this, but I don't have a concrete issue to work on, please provide examples of what is not clear and I can work on adding more documentation or simplifications. > I'll start another dev discussion about this argument. +1 zoran [1] https://github.com/apache/camel-website/issues/718 [2] https://github.com/apache/camel-website/pull/712 [3] https://github.com/apache/camel-website/issues/726 [4] https://github.com/apache/camel-website/#build-the-website-and-antora-theme -- Zoran Regvart
