[Doc] Define API stability contract

[sjfeng1999]

Make FlyDSL's export compatibility surface explicit and provide a static catalog for repeatable stability reviews.

Motivation

Technical Details

Test Plan

Test Result

Submission Checklist

• Look over the contributing guidelines at https://github.com/ROCm/ROCm/blob/develop/CONTRIBUTING.md#pull-requests.

[Copilot]

Pull request overview

Defines and documents FlyDSL’s API-stability contract for python/flydsl/, and adds a static (non-importing) catalog generator to support repeatable stability reviews.

Changes:

• Add docs/api_stability.md describing the stability rules, deprecation window, and breaking-change criteria.
• Add scripts/list_stable_apis.py to statically collect stable API paths from __all__ manifests + the stability doc (without importing flydsl).
• Tighten/standardize export manifests (__all__) and related helpers across expr/*, expr/rocdl/*, and compiler/*; add a few new wrappers (arith.maximumf/minimumf/shrui, dsl_math_wrap_result(...preserve_numeric_type=...)), plus small call-site updates.

Reviewed changes

Copilot reviewed 26 out of 27 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/system/test_inline_compare_scf_if.py	Update type usage in a system test (fx.T.f32 property).
scripts/list_stable_apis.py	New static stable-API catalog generator (AST-based, no flydsl import).
python/flydsl/expr/typing.py	Add explicit __all__ and adjust re-export import annotations.
python/flydsl/expr/rocdl/rdna4.py	Add __all__ for s_waitcnt.
python/flydsl/expr/rocdl/rdna3.py	Add __all__ for s_waitcnt.
python/flydsl/expr/rocdl/enum.py	Add __all__ for exported enums/aliases.
python/flydsl/expr/rocdl/cdna5.py	Add __all__ for selected exports.
python/flydsl/expr/rocdl/cdna4.py	Add __all__ and alias MFMAScale = MFMA_Scale.
python/flydsl/expr/rocdl/cdna3.py	Add __all__ for s_waitcnt.
python/flydsl/expr/rocdl/init.py	Add explicit __all__ defining stable rocdl export chain.
python/flydsl/expr/primitive.py	Adjust __all__ contents (notably removes get).
python/flydsl/expr/numeric.py	Add explicit __all__ for numeric DSL types.
python/flydsl/expr/math.py	Extend dsl_math_wrap_result with preserve_numeric_type.
python/flydsl/expr/gpu.py	Move/simplify __all__ to define stable GPU helpers.
python/flydsl/expr/enum.py	Add __all__ for target-neutral enums.
python/flydsl/expr/arith.py	Rework exports; add wrappers for maximumf, minimumf, shrui.
python/flydsl/expr/init.py	Add numeric star-export; rename lazy backend map to _BACKEND_MODULES.
python/flydsl/compiler/protocol.py	Add __all__ to define stable protocol surface.
python/flydsl/compiler/init.py	Reorder/clarify __all__ (compiler stable surface).
python/flydsl/init.py	Add __all__ but still imports Config/autotune.
kernels/comm/flydsl_dispatch_combine_intranode_kernel.py	Update import of T to _mlir.extras.types.
examples/04-preshuffle_gemm.py	Update fragment dtype casting patterns (.to(fx.Float16)).
docs/index.rst	Add api_stability to the docs toctree.
docs/api_stability.md	New API stability contract doc (source of truth).
CLAUDE.md	Update guidance to reference _BACKEND_MODULES.
.gitignore	Stop ignoring .claude/ so skills can be tracked.
.claude/skills/api-stability/SKILL.md	Add/define the api-stability review skill.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.