Skip to content

Commit b5e5521

Browse files
Python: Clarify meta-package promotion policy (#9311)
* Python: clarify meta-package promotion policy * Python: centralize package promotion guidance * Python: freeze namespaces after RC * Python: allow approved namespace exceptions * Python: clarify lazy namespace compatibility
1 parent ec47b90 commit b5e5521

8 files changed

Lines changed: 169 additions & 114 deletions

File tree

‎.github/scripts/check_python_api_compatibility.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,8 @@
3333
)
3434
_GRIFFE_VERSION = version("griffe")
3535
_PACKAGE_STATUS_ROW = re.compile(
36-
r"^\| `(?P<name>[^`]+)` \| `(?P<path>python/packages/[^`]+)` \| `(?P<state>[^`]+)` \|$"
36+
r"^\| `(?P<name>[^`]+)` \| `(?P<path>python/packages/[^`]+)` \| `(?P<state>[^`]+)` \|"
37+
r"(?: `[^`]+` \|)?$"
3738
)
3839

3940

‎.github/tests/test_python_api_compatibility.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,16 @@ def test_discovers_only_released_non_lab_modules(self) -> None:
116116

117117
self.assertEqual([spec.module for spec in specs], ["stable_api"])
118118

119+
def test_package_status_row_allows_optional_meta_package_column(self) -> None:
120+
rows = [
121+
"| `agent-framework-core` | `python/packages/core` | `released` |",
122+
"| `agent-framework-core` | `python/packages/core` | `released` | `yes` |",
123+
]
124+
125+
for row in rows:
126+
with self.subTest(row=row):
127+
self.assertIsNotNone(api_checker._PACKAGE_STATUS_ROW.match(row))
128+
119129
def test_filters_base_unreleased_apis_but_not_head_only_decorators(self) -> None:
120130
self.write_status([("agent-framework-core", "core", "released")])
121131
self.write_module(

‎python/.github/skills/python-feature-lifecycle/SKILL.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,10 @@ These are related, but they are **not the same thing**.
2121
- **Feature-stage decorators are only for exceptions** when a feature is behind the package's default stage.
2222
- Do **not** decorate every class or function just because the package is experimental or release candidate.
2323

24+
This skill describes staged API behavior within a package. For creating or promoting a package, including sample
25+
placement, meta-package membership, versioning, and lazy-loading namespace decisions, follow the
26+
`python-package-management` skill.
27+
2428
### Important default
2529

2630
If a package is still in **beta / experimental preview**, all public APIs in that package are experimental by default.

‎python/.github/skills/python-package-management/SKILL.md‎

Lines changed: 89 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -23,15 +23,15 @@ python/
2323

2424
- `agent-framework-core` contains core abstractions and OpenAI/Azure OpenAI built-in
2525
- Provider packages extend core with specific integrations
26-
- Root `agent-framework` depends on `agent-framework-core[all]`
26+
- Root `agent-framework` depends on `agent-framework-core[all]`. Despite the existing extra name, this is a
27+
curated standard install set, not every package at a particular lifecycle stage.
2728
- Entries in `agent-framework-core[all]` carry lower and upper bounds. Workspace integrations use the version
2829
released with the current Core cohort as their lower bound so pip does not backtrack across old cyclic
2930
`core[all] -> integration -> core` combinations.
3031
- `packages/lab` is intentionally excluded from the root uv workspace. It has its own
3132
`pyproject.toml`, `uv.lock`, environment, CI matrix, and dependency updates so experimental
32-
dependencies cannot constrain released provider packages. Lab is also an explicit exception
33-
to the lifecycle rule that beta packages belong in `agent-framework-core[all]`. Lab resolves
34-
released Core and provider distributions rather than local root-workspace packages.
33+
dependencies cannot constrain released provider packages. Lab resolves released Core and provider
34+
distributions rather than local root-workspace packages.
3535

3636
## Dependency Management
3737

@@ -114,6 +114,35 @@ uv run poe test
114114
- Run Lab dependency and validation commands from `packages/lab`; root workspace tasks deliberately do not
115115
discover or update the Lab project.
116116

117+
## Meta-package Membership
118+
119+
Package lifecycle and membership in the root `agent-framework` meta-package are independent decisions. A package
120+
starts outside `agent-framework-core[all]`, and promotion to `beta`, `rc`, or `released` does not add it
121+
automatically.
122+
123+
Adding a package to or removing a package from the standard install set requires an agreed GitHub issue and an
124+
explicit core-team decision. For additions, consider:
125+
126+
- whether the package is useful across common Agent Framework workloads rather than for one specialized storage
127+
backend, hosting adapter, channel, or deployment target;
128+
- whether its dependency footprint is proportionate and compatible with the meta-package's supported Python and
129+
platform matrix, especially for native, heavyweight, or conflict-prone dependencies;
130+
- whether it belongs in the documented standard getting-started experience; and
131+
- whether including one package would create an expectation that an open-ended family of alternative backends or
132+
adapters must also be included.
133+
134+
Default to a separate install when the case is unclear. Existing membership is not precedent for every package in
135+
the same lifecycle stage or category.
136+
137+
For removals, the issue must also assess compatibility for existing `pip install agent-framework` and
138+
`agent-framework-core[all]` users, document any migration or replacement path, determine whether the change is
139+
breaking, and identify the required Core and root meta-package version changes. Do not treat removal as ordinary
140+
dependency cleanup.
141+
142+
Track the decision in the `Meta package` column of `python/PACKAGE_STATUS.md`. When membership changes, update
143+
`packages/core/pyproject.toml` `[project.optional-dependencies].all`, the Core and root package versions as required,
144+
and the status table in the same change.
145+
117146
## Lazy Loading Pattern
118147

119148
### Root core API
@@ -151,6 +180,19 @@ def __getattr__(name: str) -> Any:
151180
) from exc
152181
```
153182

183+
### Namespace compatibility
184+
185+
The core namespace module and the objects it re-exports have different compatibility rules:
186+
187+
- While an owning package is `alpha`, `beta`, or `rc`, imports for objects from that package may be added, removed,
188+
or moved between approved lazy-loading namespaces by explicit core-team decision. Those object paths follow the
189+
owning package's prerelease lifecycle.
190+
- Do not remove a core namespace module unless it is empty after the change and is used exclusively by packages
191+
that have not reached `released`.
192+
- If a namespace exposes objects from any released package, keep the namespace. Changing import paths for released
193+
objects requires a deprecated forwarding path where feasible; otherwise the agreed issue must include migration
194+
guidance, explicit breaking-change acknowledgement, and the required Core and root meta-package version changes.
195+
154196
## Adding a New Connector Package
155197

156198
**Important:** Do not create a new package unless approved by the core team.
@@ -166,9 +208,9 @@ Every new package starts as `alpha`.
166208
5. Include samples inside the package (e.g., `packages/my-connector/samples/`)
167209
6. Do **NOT** add to `[all]` extra in `packages/core/pyproject.toml`
168210
7. Do **NOT** create lazy loading in core yet
169-
8. Add the package to `python/PACKAGE_STATUS.md` and keep that file updated when packages are added,
170-
removed, renamed, or promoted. If the package exposes individually staged APIs, keep the feature list
171-
there current too.
211+
8. Add the package to `python/PACKAGE_STATUS.md` with lifecycle state `alpha` and meta-package membership `no`,
212+
and keep that file updated when packages are added, removed, renamed, promoted, or have their membership
213+
changed. If the package exposes individually staged APIs, keep the feature list there current too.
172214
9. Keep the `Typing :: Typed` classifier and the `py.typed` marker in step. The classifier alone is a
173215
promise PEP 561 keeps through the `py.typed` file inside the package directory, and that file is
174216
the signal checkers act on: a package that declares `Typing :: Typed` without shipping it is not
@@ -204,6 +246,19 @@ Recommended dependency workflow during connector implementation:
204246

205247
### Promotion path
206248

249+
Create a GitHub issue for every package promotion and get core-team agreement before implementing the promotion.
250+
The issue must record:
251+
252+
- the current and target lifecycle stages;
253+
- whether the package should be included in the root meta-package, with rationale based on the criteria above; and
254+
- the lazy-loading namespace decision for the transition: `alpha` -> `beta` selects whether and where to expose the
255+
package, while `beta` -> `rc` and `rc` -> `released` preserve the existing namespace by default and may change
256+
the package's prerelease object imports only by explicit core-team decision and under the namespace compatibility
257+
rules above.
258+
259+
Record an explicit `no` or `none` when the package should remain outside the meta-package or should not have a
260+
lazy-loading namespace. Do not infer either decision from the target lifecycle stage.
261+
207262
Promotion work is not isolated to the package being promoted. If a promotion changes dependency
208263
metadata for downstream packages, also update the dependent packages' own versions so they publish
209264
new metadata alongside the promoted dependency bounds.
@@ -212,14 +267,16 @@ promotions as well as standalone version update work.
212267

213268
#### Alpha -> Beta
214269

215-
Move a package to `beta` when it is stable enough to be part of the main install surface.
270+
Move a package to `beta` when it is stable enough for broader prerelease use.
216271

217272
1. Update the package version to the beta pattern: `1.0.0b<date>`
218273
2. Update the classifier to `Development Status :: 4 - Beta`
219-
3. Add the package to `[all]` in `packages/core/pyproject.toml`
220-
4. Move samples to the root `samples/` tree and remove package-local samples
221-
5. Create or update the relevant lazy-loading namespace in core when the package belongs under one
222-
6. Update `python/PACKAGE_STATUS.md`
274+
3. Move samples to the root `samples/` tree and remove package-local samples
275+
4. Apply the lazy-loading decision recorded in the promotion issue, creating or updating the approved namespace
276+
when applicable
277+
5. Apply the meta-package decision recorded in the promotion issue. The default is to remain excluded; add the
278+
package to `[all]` only when inclusion is explicitly approved.
279+
6. Update the lifecycle state and meta-package membership in `python/PACKAGE_STATUS.md`
223280

224281
After `alpha`, there should be no samples left inside a package folder.
225282

@@ -230,20 +287,30 @@ Move a package to `rc` when its API is close to the final released shape.
230287
1. Update the package version to the release-candidate pattern: `1.0.0rc<number>`
231288
2. Keep the classifier at `Development Status :: 4 - Beta` because PyPI does not have a separate
232289
release-candidate classifier
233-
3. Keep the package in `core[all]`
234-
4. Keep samples only in the root `samples/` tree
235-
5. Update `python/PACKAGE_STATUS.md` to show the package as `rc`
290+
3. Apply the meta-package decision recorded in the promotion issue, preserving current membership when unchanged
291+
or using the membership-change process above when an addition or removal is explicitly approved; the stage
292+
transition alone does not add it to `core[all]`
293+
4. Preserve the existing lazy-loading namespace by default. Changes to the package's prerelease object imports are
294+
discouraged and require explicit core-team approval recorded in the promotion issue; apply the namespace
295+
compatibility rules above
296+
5. Keep samples only in the root `samples/` tree
297+
6. Update `python/PACKAGE_STATUS.md` to show the package as `rc` and keep its membership value current
236298

237299
#### RC -> Released
238300

239301
Move a package to `released` when it no longer carries a prerelease qualifier.
240302

241303
1. Update the package version to the stable pattern: `1.0.0`
242304
2. Update the classifier to `Development Status :: 5 - Production/Stable`
243-
3. Keep the package in `core[all]`
244-
4. Keep samples only in the root `samples/` tree
245-
5. Update `python/PACKAGE_STATUS.md` to show the package as `released`
246-
6. Update all `README.md` files that install that package with
305+
3. Apply the meta-package decision recorded in the promotion issue, preserving current membership when unchanged
306+
or using the membership-change process above when an addition or removal is explicitly approved; release does
307+
not imply inclusion in `core[all]`
308+
4. Preserve the lazy-loading namespace used at RC by default. Any final changes to the package's prerelease object
309+
imports require explicit core-team approval recorded in the promotion issue; apply the namespace compatibility
310+
rules above
311+
5. Keep samples only in the root `samples/` tree
312+
6. Update `python/PACKAGE_STATUS.md` to show the package as `released` and keep its membership value current
313+
7. Update all `README.md` files that install that package with
247314
`pip install agent-framework-... --pre` so they use `pip install agent-framework-...` without
248315
the `--pre` suffix
249316

@@ -291,8 +358,8 @@ Move a package to `released` when it no longer carries a prerelease qualifier.
291358

292359
```bash
293360
pip install agent-framework-core # Core only
294-
pip install agent-framework-core[all] # Core + all connectors
295-
pip install agent-framework # Same as core[all]
361+
pip install agent-framework-core[all] # Core + curated standard integrations
362+
pip install agent-framework # Same standard install set as core[all]
296363
pip install agent-framework-foundry # Specific connector (pulls in core)
297364
```
298365

@@ -305,6 +372,7 @@ When changing a package, check if its `AGENTS.md` needs updates:
305372

306373
Keep `python/PACKAGE_STATUS.md` updated when:
307374
- A package is added, removed, renamed, or promoted between lifecycle stages
375+
- A package is added to or removed from the root meta-package
308376
- A package starts or stops exposing individually staged experimental or release-candidate APIs
309377

310378
When a package adds, removes, or renames environment variables, update the related documentation in the same

‎python/AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@ Instructions for AI coding agents working in the Python codebase.
1313
- `python-development` — coding standards, type annotations, docstrings, logging, performance
1414
- `python-testing` — test structure, fixtures, async mode, running tests
1515
- `python-code-quality` — linting, formatting, type checking, prek hooks, CI workflow
16-
- `python-feature-lifecycle` — package vs feature lifecycle stages, decorators, enums, and promotion guidance
17-
- `python-package-management` — monorepo structure, lazy loading, versioning, new packages
16+
- `python-feature-lifecycle` — package-stage meaning plus staged API decorators, enums, and feature promotion
17+
- `python-package-management` — package creation and promotion, meta-package membership, lazy loading, and versioning
1818
- `pull-requests` — writing PR descriptions (template) and handling/resolving PR review comments
1919
- `agent-framework-py-release` — Python release PR workflow, CHANGELOG-driven package bumps, lifecycle version rules, and dependency-floor validation
2020

‎python/CODING_STANDARD.md‎

Lines changed: 7 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -351,7 +351,7 @@ python/
351351
├── samples/ # Sample code and examples
352352
├── packages/
353353
│ ├── core/ # agent-framework-core - Core abstractions and implementations
354-
│ │ ├── pyproject.toml # Defines [all] extra that includes all connector packages
354+
│ │ ├── pyproject.toml # Defines the curated standard-integration [all] extra
355355
│ │ ├── tests/ # Tests for core package
356356
│ │ └── agent_framework/
357357
│ │ ├── __init__.py # Lazy runtime public API exports
@@ -423,47 +423,11 @@ def __getattr__(name: str) -> Any:
423423
) from exc
424424
```
425425

426-
### Adding a New Connector Package
427-
428-
**Important:** Do not create a new package unless there is an issue that has been reviewed and approved by the core team.
429-
430-
#### Initial Release (Preview Phase)
431-
432-
For the first release of a new connector package:
433-
434-
1. Create a new directory under `packages/` (e.g., `packages/my-connector/`)
435-
2. Add the package to `tool.uv.sources` in the root `pyproject.toml`
436-
3. Include samples inside the package itself (e.g., `packages/my-connector/samples/`)
437-
4. **Do NOT** add the package to the `[all]` extra in `packages/core/pyproject.toml`
438-
5. **Do NOT** create lazy loading in core yet
439-
440-
#### Promotion to Stable
441-
442-
After the package has been released and gained a measure of confidence:
443-
444-
1. Move samples from the package to the root `samples/` folder
445-
2. Add the package to the `[all]` extra in `packages/core/pyproject.toml`
446-
3. Create a provider folder in `agent_framework/` with lazy loading `__init__.py`
447-
448-
### Versioning and Core Dependency
449-
450-
All non-core packages declare a lower bound on `agent-framework-core` (e.g., `"agent-framework-core>=1.0.0b260130"`). Follow these rules when bumping versions:
451-
452-
- **Core version changes**: When `agent-framework-core` is updated with breaking or significant changes and its version is bumped, update the `agent-framework-core>=...` lower bound in every other package's `pyproject.toml` to match the new core version.
453-
- **Non-core version changes**: Non-core packages (connectors, extensions) can have their own versions incremented independently while keeping the existing core lower bound pinned. Only raise the core lower bound if the non-core package actually depends on new core APIs.
454-
455-
### External Dependency Version Bounds
456-
457-
The guiding principle for external dependencies is to make the range of allowed versions as broad as possible, even if that means we have to do some conditional imports, and other tricks to allow small changes in versions.
458-
So we use bounded ranges for external package dependencies in `pyproject.toml`:
459-
460-
461-
- For stable dependencies (`>=1.0.0`), use a lower bound at a known-good version and an explicit upper bound that reflects the maximum major version we currently support (for example: `openai>=1.99.0,<3`).
462-
- For prerelease (`dev`/`a`/`b`/`rc`) dependencies, use a known-good lower bound with a hard upper boundary in the same prerelease line (for example: `azure-ai-projects>=2.0.0b3,<2.0.0b4`).
463-
- For `<1.0.0` dependencies, use a known-good bounded range with an explicit upper cap. Prefer the broadest validated range the package can actually support: that may be a patch line, a minor line, or multiple minor lines (for example: `a2a-sdk>=0.3.5,<0.4.0`, `fastapi>=0.115.0,<0.136.0`, `uvicorn>=0.30.0,<0.39.0`).
464-
- For prerelease (`dev`/`a`/`b`/`rc`) dependencies, use a known-good bounded range with a hard upper cap and keep the range only as broad as the package's validation coverage justifies.
465-
- Prefer keeping support for multiple major versions when practical. This may mean that the upper bound spans multiple major versions when the dependency maintains backward compatibility; if APIs differ between supported majors, version-conditional imports/branches are acceptable to preserve compatibility.
466-
- When adding or changing an external dependency, first run `uv run poe validate-dependency-bounds-test` to validate workspace-wide lower/upper compatibility, then run `uv run poe validate-dependency-bounds-project --mode both --package <workspace-package-name> --dependency "<dependency-name>"` to expand package-scoped bounds.
426+
The decision to expose a package through lazy loading, and the namespace to use, is a package-governance decision
427+
rather than a coding convention. Follow
428+
[`python-package-management`](.github/skills/python-package-management/SKILL.md) for package creation, lifecycle
429+
promotion, sample placement, meta-package membership, lazy-loading approval, versioning, and dependency bounds.
430+
This section only defines how to implement an approved lazy-loading surface.
467431

468432
### Installation Options
469433

@@ -473,7 +437,7 @@ Connectors are distributed as separate packages and are not imported by default
473437
# Install core only
474438
pip install agent-framework-core
475439

476-
# Install core with all connectors
440+
# Install core with the curated standard integrations
477441
pip install agent-framework-core[all]
478442
# or (equivalently):
479443
pip install agent-framework

0 commit comments

Comments
 (0)