Restore field-level GQL descriptions dropped by gql_pydantic_type
- Dominant language
- Python
- Stars
- 670
- Forks
- 183
- Avg merge
- 17h 7m
- Merged PRs (30d)
- 358
Description
## Objective
Make field-level BackendAIGQLMeta reach the GraphQL schema for @gql_pydantic_type types, so that API version metadata stops being written into the shared v2 DTOs.
## Background
gql_pydantic_type wraps strawberry.experimental.pydantic.type, which rebuilds every non-resolver field from the Pydantic model. The rebuilt StrawberryField carries graphql_name, deprecation_reason, permission_classes, directives, extensions and metadata over from the class-body field, but hardcodes description to the Pydantic field's description (strawberry/experimental/pydantic/object_type.py). Whatever gql_field or gql_added_field supplied is discarded. gql_node_type and gql_pydantic_input use plain Strawberry decorators and are unaffected.
Two consequences visible on main:
- Version tags on such fields never reach the schema. PreemptionConfig.enabled declares added_version 26.8.0 in the GQL layer, yet its SDL description carries no "Added in" line.
- To satisfy the graphql-inspector rule that every newly added field carries "Added in X.Y.Z.", the tag has to be written into the shared v2 DTO instead. common/dto/manager/v2/deployment/types.py and common/dto/manager/v2/app_config/response.py do this today, and those DTOs are also read by REST v2, the SDK and the CLI.
The divergence is directly observable: ModelMountConfig.subpath declares "``null`` means the vfolder root" in the GQL layer, while the schema ships the DTO's "``None`` means the vfolder root".
## Acceptance Criteria
- gql_pydantic_type restores class-body field descriptions after decoration, so gql_field and gql_added_field on a Pydantic-backed output type reach the schema.
- The regenerated schema dumps are reviewed field by field; every changed description is the GQL-layer text intentionally winning over a diverged DTO text.
- "Added in" prefixes are removed from common/dto/manager/v2/deployment/types.py and common/dto/manager/v2/app_config/response.py, with the version expressed in the GQL field metadata instead.
- The graphql-inspector check passes.
- api/gql/AGENTS.md documents which decorator sources its field descriptions from where.
## Notes
Regenerating the schema after the fix changes roughly 690 lines in v2-schema.graphql and the same in supergraph.graphql, mostly descriptions on Agent, ResourceGroup and Deployment types whose GQL-layer and DTO wording had drifted apart. The code change itself is small; the review effort is the schema diff.
Found while reviewing BA-7150 (PR #13377), which had to put the version tag into the AppConfig DTO for this reason.
JIRA Issue: BA-7187
Contributor guide
Research direction
Start in strawberry/experimental/pydantic/object_type.py and trace gql_pydantic_type's field rebuilding, then inspect the GQL fields and DTOs named in the issue. Regenerate v2-schema.graphql and supergraph.graphql to review the description changes, remove the duplicated version tags from the two DTO files, and update api/gql/AGENTS.md. Done means the GQL descriptions and metadata reach the schema and graphql-inspector passes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- graphql, python
- Domain
- api, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 55/100