RFC: Yoga Errata Policy

[NickGerleman]

Our ability to implement even known-good changes has been limited by a concern of bug-compatibility, where a more conformant behavior may break existing product code. There have been one-off approached to handling this (e.g. UseLegacyStretchBehaviour), but a goal of the Yoga M1 release is to formalize guarantees around how these sorts of changes will be handled in the future. More concretely, the Yoga M1 release will include a formal errata policy and API, replacing existing flags, and setting a reproducible process for adding new behavior changes.

Any new behavior changes must initially be implemented as a new branch in code, guarded by an “errata” setting, alongside checks which mark whether the erratum would have created a different layout result as part of the YGLayout. Yoga with default configuration will prefer the correct behavior, but this can be customized.

Leaving branches for every bug-fix adds long-term cost, so errata are subject to removal if experimentation (telemetry) show that a behavior change is very rarely hit in real-world applications. This is validated by:

1. Measuring the exact rate an errata is hit within React Native surfaces at Meta.
   1. I.e. how often does ShadowNode layout result in a Yoga node with errata bits set
2. Measuring indirect metric impact (e.g. behavior changes, bug reports) in non-React Native surfaces used by Meta

Errata handling is independent of the existing YGExperimentalFeature mechanism for feature-gating. Changes under feature-gates, or not yet present in a stable Yoga release, are not subject to the errata policy. This allows iteration during development.

While not a bug in the same vein as other errata, a similar approach, under a separate API, would make sense to allow moving the default behavior to that of UseWebDefaults().

APIs

YGErrata
Enum bit-set of known implementation issues. They may be used to set or query behavior related to bug compatibility. The flags are not stable, and are subject to change as errata are fixed globally in the main implementation.

Examples:

1. YGErrataNone: No errata
2. YGErrataAll: All errata
3. YGErrataStretchBasis : Equivalent to previous UseLegacyStretchBehaviour
4. YGErattaClassic: All errata apart from YGErrataStretchBasis (matches current default Yoga behavior)

YGConfigSetErrata
Sets the list of layout behaviors to rely on when laying out a specific node.

YGConfigRef config = YGConfigNew();

YGErrata errata = YGErrataStretchBasis | YGErrataAbsoluteEdgeAgainstPadingBox;
YGConfigSetErrata(config, errata);

YGNodeLayoutAffectedByErrata
Queries whether the layout of a specific node was impacted by an errata, meaning an errata branch was taken, and the layout result would be different if it was not taken. Only one node is marked by errata branch. I.e. the children of a node will not be marked as effected if an errata caused a parent node layout to change.

YGNodeRef root = YGNodeNew();
YGNodeRef node = YGNodeNew();
// Setup the tree and node information

YGNodeCalculateLayout(root);
if (YGNodeLayoutEffectedByErrata(node, YGErrataStretchBasis) {
  printf("Node layout was dependent on its flex basis being stretched\n");
}