update readme for #396

README.adoc

@@ -627,3 +627,37 @@ many of them on the command-line with:
 
 [source,text]
 $ /path/to/clickhouse server --config-file /path/to/config.xml -- --param_name param_value ...
+
+=== Generated Service Clients and Updating
+
+Each service is a Dropshot server that presents an HTTP API. The description of
+that API is serialized as an
+https://github.com/OAI/OpenAPI-Specification[OpenAPI] document which we store
+in link:./openapi[`omicron/openapi`] and check in to this repo. In order to
+ensure that changes to those APIs are made intentionally, each service contains
+a test that validates that the current API matches. This allows us 1. to catch
+accidental changes as test failures and 2. to explicitly observe API changes
+during code review (and in the git history).
+
+We also use these OpenAPI documents as the source for the clients we generate
+using https://github.com/oxidecomputer/progenitor[Progenitor]. Clients are
+automatically updated when the coresponding OpenAPI document is modified.
+
+Note that Omicron contains a nominally circular dependency:
+* Nexus depends on the Sled Agent client
+* The Sled Agent client is derived from the OpenAPI document emitted by Sled Agent
+* Sled Agent depends on the Nexus client
+* The Nexus client is derived from the OpenAPI document emitted by Nexus
+
+We effectively "break" this circular dependency by virtue of the OpenAPI
+documents being checked in.
+
+In general, changes any service API **require the following set of build steps**:
+
+* Make changes to the service API
+* Update the OpenAPI document by running the relevant test with overwrite set:
+  `EXPECTORATE=overwrite cargo test test_nexus_openapi_internal` (changing the
+  test name as necessary)
+* This will cause the generated client to be updated which may break the build
+  for dependent consumers
+* Modify any dependent services to fix calls to the generated client