Platform updatability best practices

Recommended: Use FIDL types and protocols to define interfaces between any two things that may update separately. Leverage the FIDL rubric where applicable.

• FIDL has versioning annotations.
• FIDL offers API and ABI compatibility guarantees.
• FIDL enables soft transitions by supporting changing type definitions, adding and removing methods over time, and renaming types.

Not recommended: Avoid languages other than FIDL to define interfaces where independent updates matter. These include: plain text, JSON, and protocol buffers.

When reviewing alternatives, ask yourself what affordances they have for updatability.

• Is there a schema for the data?
• Can the schema change over time, while providing backward/forward compatibility? How?
• What changes to the schema are API/ABI preserving/breaking? How would you know before committing a breaking change?
• Is the wire format stable?

Recommended: Be careful when designing platform APIs and ABIs for use outside the platform. Design for updatability, find ways to enforce that your clients use the intended interfaces, and don’t offer ways to circumvent the interface.

Not recommended: Avoid exposing your clients to your implementation details that are not contractual. Common mistakes include exposing broadly-scoped capabilities or namespaces, and leaking implementation details via component identifiers (such as fuchsia-pkg:// URLs) and diagnostics selectors.