lablup / lablup/backend.ai

Pluralize singular collection field names in artifact GraphQL/DTO payloads with deprecated aliases

Open
#10,455 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.