python-feature-lifecycle

# Python Feature Lifecycle ## Two lifecycle levels Agent Framework uses lifecycle at two different levels: 1. **Package lifecycle** — the maturity of the package as a whole 2. **Feature lifecycle** — the maturity of a specific API or feature inside that package These are related, but they are **not the same thing**. - The **package stage is the default** for everything in the package. - **Feature-stage decorators are only for exceptions** when a feature is behind the package's default stage. - Do **not** decorate every class or function just because the package is experimental or release candidate. ### Important default If a package is still in **beta / experimental preview**, all public APIs in that package are experimental by default. - Do **not** add `@experimental(...)` everywhere in that package. - The package stage already communicates that default. Once a package moves forward, you can keep individual features behind: - If a package moves to **release candidate**, a feature may remain **experimental** - If a package moves to **released / GA**, a feature may remain **experimental** or **release candidate** That is the main use case for feature-stage decorators. ## The four stages ### 1. Experimental Use for features that are still unstable and may change or be removed without notice. Feature-level code pattern: ```python from ._feature_stage import ExperimentalFeature, experimental @experimental(feature_id=ExperimentalFeature.MY_FEATURE) class MyFeature: ... ``` Behavior: - Adds an experimental warning block to the docstring - Records feature metadata on the decorated object - Emits a runtime warning the first time the feature is used (once per feature by default) Enum setup: - Add an all-caps member to `ExperimentalFeature` - Reuse the same feature ID across all APIs that belong to the same conceptual feature ### 2. Release candidate Use for features that are nearly stable but may still receive small refinements before GA. Feature-level code pattern: ```python from ._feature_stage import ReleaseCandidateFeature, release_candidate @release_candidate(feature_id=ReleaseCandidateFeature.MY_FEATURE) class MyFeature: ... ``` Behavior: - Adds a release-candidate note to the docstring - Records feature metadata on the decorated object - Does **not** emit the experimental warning Enum setup: - Add an all-caps member to `ReleaseCandidateFeature` ### 3. Released Use for stable GA APIs. Code pattern: - **No feature-stage decorator** - **No entry** in `ExperimentalFeature` - **No entry** in `ReleaseCandidateFeature` If a feature is fully released, remove any stage-specific feature annotation. ### 4. Deprecated Use for APIs that still exist but should not be used for new code. Code pattern: ```python import sys if sys.version_info >= (3, 13): from warnings import deprecated # type: ignore # pragma: no cover else: from typing_extensions import deprecated # type: ignore # pragma: no cover @deprecated("MyOldFeature is deprecated. Use MyNewFeature instead.") class MyOldFeature: ... ``` Behavior: - Uses the repository's version-conditional deprecation import pattern - Should describe what to use instead Deprecated APIs should not also carry feature-stage decorators. ## Expected decorators by stage | Feature stage | Expected annotation | | --- | --- | | Experimental | `@experimental(feature_id=ExperimentalFeature.X)` | | Release candidate | `@release_candidate(feature_id=ReleaseCandidateFeature.X)` | | Released | No feature-stage decorator | | Deprecated | `@deprecated("...")` | ## Feature enums The feature enums are the inventory of currently staged features: - `ExperimentalFeature` - `ReleaseCandidateFeature` Guidance: - Use one enum member per conceptual feature, not per class - Ideally, an ADR already defines the overall feature boundary and therefore the feature ID that staged APIs for that feature should reuse - Keep feature IDs all caps - Reuse the same member across related APIs for the same feature - Remove enum members when the feature no longer belongs to that stage - Treat these enums as **current-stage inventories**, not as a stable consumer introspection API Minimal consumer guidance: - Treat `__feature_stage__` and `__feature_id__` as optional staged metadata, not as stable contracts - Use `getattr(obj, "__feature_stage__", None)` and `getattr(obj, "__feature_id__", None)` rather than direct attribute access - Treat missing metadata as "no explicit feature-stage annotation" - For warning filters while a feature is staged, match the literal feature ID string - Do **not** rely on `ExperimentalFeature.X`, `ReleaseCandidateFeature.X`, or the continued presence of `__feature_id__` after a feature moves stages or is released For consumers, the enums are also re-exported from `agent_framework`. For internal implementation code inside `agent_framework`, continue to import the enums and decorators from `._feature_stage`. ## Package stage vs feature stage Use the following rules: ### Package is experimental / beta - All public APIs are experimental by default - Do **not** add feature-stage decorators just to restate that - Only introduce feature-level annotations later if the package advances first ### Package is release candidate - All public APIs are RC by default - Do **not** decorate everything - Add `@experimental(...)` only for features that are intentionally still behind the package ### Package is released / GA - All public APIs are released by default - Add `@experimental(...)` or `@release_candidate(...)` only for features still being held back ## Moving a feature from one stage to the next ### Experimental -> Release candidate 1. Move the feature ID from `ExperimentalFeature` to `ReleaseCandidateFeature` 2. Replace `@experimental(...)` with `@release_candidate(...)` 3. Update any tests or docs that mention the old stage ### Experimental -> Released 1. Remove `@experimental(...)` 2. Remove the feature from `ExperimentalFeature` 3. Do not add a replacement feature-stage decorator ### Release candidate -> Released 1. Remove `@release_candidate(...)` 2. Remove the feature from `ReleaseCandidateFeature` 3. Leave the API undecorated ### Any stage -> Deprecated 1. Remove any feature-stage decorator 2. Remove the feature from the stage enum 3. Add `@deprecated("...")` 4. Update docs/tests to reflect the replacement path ## Promotion guidance Features do **not** have to pass through every stage. - It is usually a good idea to move features in order when that reflects reality - But it is completely acceptable to go **experimental -> released** - Do **not** force a feature through release candidate if there is no real RC period Likewise, when a package advances, do not automatically move every feature with it. - Promote features based on actual readiness - Keep lagging features explicitly marked only when they are behind the package default ## Practical rules of thumb - **Package default first, feature exceptions second** - **Do not decorate everything in preview packages** - **Do not double-annotate members of an already-staged class** - **Use enums only for currently staged features** - **Do not treat stage enums as a compatibility contract** - **Treat `__feature_stage__` and `__feature_id__` as optional metadata; use `getattr`** - **Remove stage annotations once a feature is released or deprecated**