ls-apis: mention related RFDs and sections

[iximeow]

i think my confusion about "is dns-server-api client-versioned or server-versioned" in this rev of #8322 came from both not quite understanding what determines versioned_how, and the relationship between versioned_how in api-manifest.toml, descriptions in openapi-manager, and definitions in RFD 532. i think this helps clarify the relationship, and mentioning 565 might have helped clarify the "updated before" relationship.

i'm actually still not very sure i know how to determine if the DNS API is or is not server-managed. abstractly, it makes sense, but what i think i was hoping to find is a source of truth for what service must be updated before others as reconfigurator executes a blueprint. 565 talks about each component a bit more which helped me conceptualize "tiers" better (plenty familiar with DAGs, but the dot output was still hard to parse and i couldn't reason through "why"s)

really, the confusion i had was that i wasn't sure if api-manifest.toml incorrectly modeled service update dependencies, or if i'd misunderstood the model. so i'd tried reasoning through "can there be an old DNS client with a new DNS server" and got that wrong. maybe what i'd have needed was more like the source of truth about the order services are updated? i'm not sure if my confusion makes sense, even.

maybe the question i'm trying to ask is: "is versioned_how prescriptive or descriptive?" i think it is descriptive, and i was trying to find a prescriptive answer to check it against.

[davepacheco]

The change looks good. Below I'm trying to clarify how all this works.

---

The whole purpose of all of this tooling and metadata is to enable us to:

1. determine an update sequence (a sequence of updates to deployment units) that will ensure there cannot be a client-server version mismatch during the update from release A to release B
2. verify at build-time that the sequence we picked will indeed not cause a client-server version mismatch

To be clear, the update sequence is a static, determined thing, written into RFD 565. It's not computed by the tooling or anything. In fact, the tooling and metadata don't work in terms of the update sequence at all. Instead, they operate like this:

• we've defined properties "server-side-only-versioned" and "client-side-versioned"
• we've labeled (via the metadata) APIs as one or the other. This is somewhat arbitrary -- more below.
• the tooling identifies [all] API dependencies [ideally/hopefully]
• the tooling verifies that the graph where nodes are components and edges represent API dependencies for server-side-only APIs only forms a DAG
• we somewhat arbitrarily selected an update sequence that's consistent with the DAG and determined it in RFD 565

This is enough to guarantee that the update sequence will work. If someone were to add a client for a server-side-only API that would be deployed before its server, the tool would notice and fail at CI time.

I think you might be asking: how is it determined whether each API would be server-side-only-versioned or client-side-versioned? Hopefully it's clearer now that the tooling doesn't do this at all. We just went through and made determinations (somewhat assisted by the tooling), wrote them down, and had the tool verify them. The process is described in #7138, under "How I made the choice for each API". Importantly, it was somewhat arbitrary, even though there are also constraints. When there's a circular dependency between A and B (possibly going through other services), either one (or both) could be client-side versioned.

To be concrete, DNS is server-side-versioned because it's a leaf: it doesn't have any dependencies, so it's easy to make sure it gets deployed before it's clients -- just update it before any of its clients. So that was an easy one 😄 The details in 7138 explain how we picked the others.

[iximeow]

When there's a circular dependency between A and B (possibly going through other services), either one (or both) could be client-side versioned.

ah! this is something i think i was fumbling towards but didn't quite consciously realize: stating "server-side-versioned" is to make explicit a simplification of the deployment model, because "client-and-server-side-versioned" is harder to think about and support. from there it's just that we want to be as strict as we can to keep the whole procedure as simple as possible.

continuing with the DNS example, in the limit there's no objective requirement that DNS must be server-side versioned - if it had dependencies, the statement could change. that just makes versioning more complicated, and if we did consider changing it for some reason, that tradeoff would have to be considered.

[davepacheco]

Exactly right.