TheLortex
commented
1 year ago It's not exactly what happens. At any moment there are two namespaces, current and live. They are symlinks pointing to folders in the data server indexed by a hash of many things, including the voodoo commit and accessible by ocaml.org in docs-data.ocaml.org/current and docs-data.ocaml.org/live.
When the voodoo commit changes, the hash changes and the current folder points to that new folder (which is initally empty). At this point the content of the live folder is frozen. The CI starts working and fills the current folder with the content of the docs website.
Then, when it's ready, manual confirmation is required to make live point to the same folder as current.
What that means for ocaml.org is that if there is a breaking change, we can make a seamless update using these steps:
- update voodoo introducing the breaking change
- confirm voodoo update in docs ci
- wait 24-48h, so the new docs website is built
- update ocaml.org to consume the new data format in the
currentnamespace - confirm
livepointing to same folder ascurrentin docs CI - update ocaml.org to consume data in the
livenamespace
sabine
As I understand it at the moment, updating voodoo to the new data format means that, some moment around 24-48 hours in the future, suddenly, ocaml.org will break and needs someone to quickly jump and apply the patch to make ocaml.org able to consume the new data format.
If that happens in an inconvenient moment, that could be problematic.
If, unexpectedly, there are issues with a large number of packages' generated documentation, we may need to roll back and apply a fix. However, we don't seem to have a way to do that after the pipeline switches the
live-folder.I may be completely mistaken on this, and if I am, would be glad for someone to point out if there's an intended way to do these kinds of breaking data-format changes.
This is the root problem behind https://github.com/ocaml/infrastructure/issues/18, https://github.com/ocurrent/ocaml-docs-ci/issues/87, and https://github.com/ocurrent/ocaml-docs-ci/issues/85 and the underlying reason why we still don't have the missing preambles back in the package documentation.