W28 - Definition & Interface Dependencies

The Importance of Definitions

In daily operations, many confusing issues and unclear responsibilities usually stem from problems with how concepts are defined. For example, a definition may be vague, or it may be clear but lacks consensus. Take a common case: when QA assigns an owner to a bug in Ones, in more complex scenarios they may be unsure who is the appropriate assignee. The root cause of this confusion is an unclear definition of the concept of “assignee,” or a lack of shared understanding. Without a clear definition, we tend to treat “assignee” as a composite concept that includes the person who introduced the issue, the person who handles it, and the person ultimately responsible. If the issue is even slightly complex, this naturally creates ambiguity where one term has multiple meanings. A clear, simple definition usually resolves the problem. For example, the simplest and clearest principle is: assign it to whoever will fix it— the assignee is the handler. This is unrelated to breaking down responsibility or finding root causes and accountable parties; that is the remit of COE post-mortems.

How Inter-service Dependencies Affect Backward Compatibility

In a decoupled front-end/back-end architecture, API changes and iterations must pay careful attention to backward compatibility. Generally, backend API fields should only be added, not changed. If backward compatibility is not maintained, adjusting the deployment order of front-end and back-end or adding feature flags to switch between old and new APIs won’t solve the sharp failures that occur at release boundaries. Pay special attention to inter-API dependencies: if you didn’t modify an old API but introduced a new version, and that new API depends on an upstream API—for example, if the upstream API returns the endpoint for the downstream API—then even adding an API requires extra care. You must ensure the upstream API is version-compatible with the newly added downstream API.