StableHLO Specification Checklist

In this document, we summarize the guidelines for reviewing changes to the specification. At the moment, these changes typically involve checking multiple things in multiple sources, so this document summarizes them all to simplify reviews:

  1. Check that the "Specification" column in status.md says "yes", add a row if adding a new op.
  2. Check if the section title matches the op's mnemonic in the ODS.
  3. Check if the "Semantics" section matches XLA's Operation Semantics.
  4. Check whether the "Inputs" and "Outputs" sections:
    1. List the same items as the ODS.
    2. List the same items as HloInstruction::CreateFromProto.
    3. Are ordered exactly like ODS.
    4. If there are any mismatches, check that there are corresponding tickets.
  5. Check whether the "Constraints" section:
    1. Matches XLA's shape_inference.cc.
    2. Matches XLA's hlo_verifier.cc.
    3. Matches the ODS.
    4. Matches StablehloOps.cpp.
    5. If there are any mismatches, check that there are corresponding tickets. Link all those tickets in the spec, in locations which are as specific as possible (e.g. if a ticket is about a constraint that hasn't been implemented, link the ticket right in that constraint).
    6. If the corresponding parts of the ODS and StablehloOps.cpp match the spec, check that the "Verification" and "Type Inference" columns in status.md say "yes".
  6. Check whether the "Examples" section:
    1. Only has one example. (In the future, we'll link to more examples from the StableHLO interpreter test suite).
    2. Uses valid MLIR syntax by running stablehlo-opt on code examples.
    3. Uses generic MLIR syntax which can be obtained by running stablehlo-opt -mlir-print-op-generic (we stick to generic syntax in the spec to avoid having to change the spec on prettyprinter changes).
  7. Check that the description in the op's ODS:
    1. Includes the first sentence of the spec.
    2. Then links to the corresponding section of the spec.
    3. Then uses the same example as the spec but via pretty syntax which can be obtaining by running stablehlo-opt.
  8. Check that the files related to implementing verification and type inference constraints follow the guidelines as mentioned below:
    1. Follow guideline #1 for StablehloOps.td.
    2. Follow guideline #2 for TypeInference.cpp and StablehloOps.cpp.
    3. Follow guideline #5 for ops_stablehlo.mlir.
    4. Follow guideline #6 for infer_stablehlo.mlir.
  9. Evaluate the op for side effects and speculatability.
    1. If the op has no side effects and is always speculatable, give it the Pure trait. This is rare, as most ops allow dynamic shapes, which may lead to shape mismatches at runtime, which is undefined behavior. Some ops can have undefined behavior in other situations as well. The vast majority of ops do not have side effects (they should have the NoMemoryEffect trait).
    2. Most ops fall into one of the HLO_SpeculatableIf* traits. If the op does not fit into any of those, give it the ConditionallySpeculatable trait and implement the interface methods. Add tests to stablehlo/tests/ops_speculatability.mlir to cover the speculatability logic.