From 12de7e9b505d1fd1e7128a194f6696f9c1993e82 Mon Sep 17 00:00:00 2001 From: Sabine Schmaltz Date: Tue, 24 Jan 2023 13:00:21 +0100 Subject: [PATCH] document pipeline from the perspective of ocaml.org --- README.md | 34 ++++++++++++++++++++++++++++++---- 1 file changed, 30 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 409b1b80..41a11653 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,13 @@ # Voodoo -Voodoo is the OCaml documentation generator. +Voodoo is the OCaml package documentation generator. -## Getting started +The documentation pipeline at [ocaml-docs-ci](https://github.com/ocurrent/ocaml-docs-ci) uses voodoo to generate data for the ocaml.org website. Read more about how to deploy a new version of voodoo to the documentation pipeline [here](#the-documentation-pipeline). + +## Build and run locally This package is intended to be used as part of an -[ocurrent](https://github.com/ocurrent/ocurrent) pipeline, for example -via [ocaml-docs-ci](https://github.com/ocurrent/ocaml-docs-ci). As such, +[ocurrent](https://github.com/ocurrent/ocurrent) pipeline. As such, it's tricky to use in isolation. Having said that, there is some rudimentary support for using it this way. The steps below will guide you to build to build a small documentation website locally. @@ -127,3 +128,28 @@ make odoc 1. Serve `_generated/html` `voodoo-*` commands must be called from the `_generated` directory. + +## The documentation pipeline + +The documentation pipeline serves the package documentation built by voodoo at two locations: +1. live: `https://docs-data.ocaml.org/live/p/{PACKAGE_NAME}/{PACKAGE_VERSION}/` (manually-promoted live version), and +2. current: `https://docs-data.ocaml.org/current/p/{PACKAGE_NAME}/{PACKAGE_VERSION}/` (always follows the `live` branch of `voodoo`). + +The pipeline checks daily for updates to the `live` branch of this repository. When it finds new commits, the pipeline starts to build the package documentation using the new commits. It takes around 24-48h to complete the build. The resulting data appears in the `current` folder. + +### Promoting package documentation to live + +When all packages' documentation has been built, a job where an [authorized user](https://github.com/ocurrent/ocaml-docs-ci/blob/main/src/ocaml_docs_ci.ml) can manually confirm promoting the `current` folder to the `live` folder appears [here](https://docs.ci.ocaml.org/jobs). + +### How to safely and seamlessly upgrade ocaml.org on breaking changes + +If there is a breaking change (usually: modification of the documentation format generated by voodoo), +we can perform a seamless update on ocaml.org using these steps: + +1. push the voodoo update that introduces the breaking change to the `live` branch of voodoo +2. confirm voodoo update in docs ci +3. wait 24-48h for the documentation pipeline to build the new package documentation +4. update ocaml.org to consume data from `https://docs-data.ocaml.org/current` (if necessary, we can fall back to `https://docs-data.ocaml.org/live` which still serves the previous data) +5. confirm that everything went fine on ocaml.org +6. [promote the `current` folder to `live`](#promoting-package-documentation-to-live) +7. update ocaml.org to consume data in the live namespace `https://docs-data.ocaml.org/live`