Pluralize singular collection field names in artifact GraphQL/DTO payloads with deprecated aliases
- Dominant language
- Python
- Stars
- 670
- Forks
- 183
- Avg merge
- 15h 13m
- Merged PRs (30d)
- 368
Description
## Background
In [PR #10445](https://github.com/lablup/backend.ai/pull/10445) (BA-5385), the `artifactRevision` field name was restored as singular, but it actually returns a collection (`ArtifactRevisionConnection`). This is inconsistent with other payloads in the same module that use plural names for collections (e.g., `artifactRevisions` in `ImportArtifactsPayload` / `DelegateImportArtifactsPayload`).
Review comment: [PR review](https://github.com/lablup/backend.ai/pull/10445#pullrequestreview-3996192564)
## Tasks
1. **Rename singular collection fields to plural** across the following files:
1. **Add deprecated aliases** — keep the old singular field names as deprecated aliases (for at least one release) to avoid breaking existing clients.
1. **Remove deprecated aliases** in a subsequent release after clients have migrated.
## Affected Files
- `src/ai/backend/manager/api/gql/artifact/types.py` — `ScanArtifactModelsPayload.artifact_revision` → `artifact_revisions`
- `src/ai/backend/manager/api/gql/artifact/resolver.py` — mutation payload field references
- `src/ai/backend/common/dto/manager/v2/artifact/response.py` — `ScanArtifactModelsGQLPayload.artifact_revision` → `artifact_revisions`
- `src/ai/backend/common/dto/manager/v2/artifact_registry/response.py` — singular list field → plural
- `docs/manager/graphql-reference/v2-schema.graphql` — schema field name update
- `docs/manager/graphql-reference/supergraph.graphql` — schema field name update
- `tests/unit/common/dto/manager/v2/artifact_registry/test_response.py` — test fixture updates
## Approach
- Phase 1: Add plural field as canonical + keep singular as deprecated alias (strawberry `deprecation_reason` for GraphQL, Pydantic `Field(deprecated=...)` for DTO)
- Phase 2 (future release): Remove deprecated singular aliases
JIRA Issue: BA-5387
Contributor guide
Research direction
Start with the affected fields in src/ai/backend/manager/api/gql/artifact/types.py and src/ai/backend/common/dto/manager/v2/artifact/response.py, comparing them with existing plural collection fields. Trace the payload references in resolver.py, update the two GraphQL schema files, and run tests/unit/common/dto/manager/v2/artifact_registry/test_response.py. Done means plural fields are canonical while singular aliases remain deprecated across the listed code, schemas, and fixtures.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- graphql, python
- Domain
- api, backend, documentation
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 58/100