python-feature-lifecycle

name	python-feature-lifecycle
description	Guidance for package and feature lifecycle in the Agent Framework Python codebase, including stage meanings, feature-stage decorators, feature enums, and how to move APIs from one stage to the next.

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.