Skip to content
This repository was archived by the owner on Jul 10, 2025. It is now read-only.

Commit eb15bc4

Browse files
alextpmartinwicke
authored andcommitted
clarify policy for stuff which keeps changing
1 parent 581d21a commit eb15bc4

File tree

1 file changed

+6
-2
lines changed

1 file changed

+6
-2
lines changed

governance/api-reviews.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -259,12 +259,16 @@ No API endpoint should stay in experimental forever. If a particular
259259
experimental API hasn't had major changes in two minor releases we should remove
260260
the experimental annotation from the API name or delete it. If we do want to
261261
delete it we need to have a deprecation plan that can migrate all users to some
262-
other API endpoint or composition of existing APIs.
262+
other API endpoint or composition of existing APIs. In rare cases experimental
263+
APIs can continue to be iterated on after many releases (see TPUStrategy); this
264+
only applies for fairly large API surfaces.
263265

264266
When removing the experimental annotation we should, if at all possible, allow
265267
escape routes to not break existing code. This means toplevel symbols
266268
`tf.experimental.foo` and methods like `tf.Class.experimental_foo` should get a
267269
deprecation warning on 2.x before deletion on 2.x+1; we should use the
268270
doc_controls decorators to not pollute API docs with deprecated "graduated"
269271
experimental APIs. For experimental function arguments we should consider
270-
catching `**kwargs` to raise the proper warnings for at least one version.
272+
catching `**kwargs` to raise the proper warnings for at least one version (note
273+
though that `**kwargs` is generally discouraged from our APIs; we prefer
274+
explicitly named keyword arguments if at all possible).

0 commit comments

Comments
 (0)