forgejo_admin/basketball-api

Fork 0

Add downstream consumer check to migration workflow #193

New issue

Closed

opened 2026-03-27 21:07:05 +00:00 by forgejo_admin · 1 comment

forgejo_admin commented

2026-03-27 21:07:05 +00:00

Owner

Type

Feature

Lineage

Discovered during incident: forgejo_admin/westside-contracts #25. Migration 019 dropped players.team_id without updating westside-contracts, causing 2+ days of HTTP 500s on all contract pages.

Repo

forgejo_admin/basketball-api

User Story

As a developer running migrations on basketball-api
I want a checklist that flags shared tables with downstream consumers
So that I don't break westside-contracts (or future consumers) with schema changes

Context

basketball-api's Postgres database is consumed directly by westside-contracts via raw SQL queries over the shared cluster DNS (postgres.basketball-api.svc.cluster.local). Migration 019 (019_player_teams_junction.py) dropped players.team_id in favor of a player_teams join table. westside-contracts was still querying p.team_id, causing all contract pages to return 500 for 2+ days with no alert.

Two gaps: (1) no process to check downstream consumers before merging migrations, (2) no alerting on westside-contracts error rates.

File Targets

Files the agent should modify or create:

CONTRIBUTING.md or docs/migrations.md — document shared tables and downstream consumers
alembic/README.md — add migration checklist noting downstream verification

Files the agent should NOT touch:

alembic/versions/* — no migration changes needed

Acceptance Criteria

Shared tables documented (players, teams, parents, player_teams → westside-contracts)
Migration checklist includes "check downstream consumers" step
Documentation is discoverable from alembic directory

Test Expectations

No code tests — this is documentation/process only
Run command: N/A

Constraints

Keep it lightweight — a checklist, not a CI gate (for now)
Match existing documentation style in the repo
Don't over-engineer; this is a convention, not enforcement

Checklist

PR opened
No unrelated changes

project-westside-basketball — project this affects
forgejo_admin/westside-contracts #25 — the incident that exposed this gap

### Type Feature ### Lineage Discovered during incident: `forgejo_admin/westside-contracts #25`. Migration 019 dropped `players.team_id` without updating westside-contracts, causing 2+ days of HTTP 500s on all contract pages. ### Repo `forgejo_admin/basketball-api` ### User Story As a developer running migrations on basketball-api I want a checklist that flags shared tables with downstream consumers So that I don't break westside-contracts (or future consumers) with schema changes ### Context basketball-api's Postgres database is consumed directly by westside-contracts via raw SQL queries over the shared cluster DNS (`postgres.basketball-api.svc.cluster.local`). Migration 019 (`019_player_teams_junction.py`) dropped `players.team_id` in favor of a `player_teams` join table. westside-contracts was still querying `p.team_id`, causing all contract pages to return 500 for 2+ days with no alert. Two gaps: (1) no process to check downstream consumers before merging migrations, (2) no alerting on westside-contracts error rates. ### File Targets Files the agent should modify or create: - `CONTRIBUTING.md` or `docs/migrations.md` — document shared tables and downstream consumers - `alembic/README.md` — add migration checklist noting downstream verification Files the agent should NOT touch: - `alembic/versions/*` — no migration changes needed ### Acceptance Criteria - [ ] Shared tables documented (players, teams, parents, player_teams → westside-contracts) - [ ] Migration checklist includes "check downstream consumers" step - [ ] Documentation is discoverable from alembic directory ### Test Expectations - [ ] No code tests — this is documentation/process only - Run command: N/A ### Constraints - Keep it lightweight — a checklist, not a CI gate (for now) - Match existing documentation style in the repo - Don't over-engineer; this is a convention, not enforcement ### Checklist - [ ] PR opened - [ ] No unrelated changes ### Related - `project-westside-basketball` — project this affects - `forgejo_admin/westside-contracts #25` — the incident that exposed this gap

forgejo_admin referenced this issue from a commit

2026-03-27 22:16:53 +00:00

fix: Kaniko skip-push-permission-check (#193) (#182)

forgejo_admin commented

2026-03-28 05:45:42 +00:00

Author

Owner

Scope Review: READY

Review note: review-468-2026-03-27
Ticket is well-scoped: all template sections present, traceability complete (story:WS-S5, arch:basketball-api, issue open), file targets verified (3 new files to create, alembic/versions confirmed untouched). Only downstream consumer confirmed is westside-contracts (direct SQL to 4 shared tables). 3 AC, all agent-verifiable. Estimated ~3 min agent pass. No decomposition needed.

## Scope Review: READY Review note: `review-468-2026-03-27` Ticket is well-scoped: all template sections present, traceability complete (story:WS-S5, arch:basketball-api, issue open), file targets verified (3 new files to create, alembic/versions confirmed untouched). Only downstream consumer confirmed is westside-contracts (direct SQL to 4 shared tables). 3 AC, all agent-verifiable. Estimated ~3 min agent pass. No decomposition needed.

forgejo_admin referenced this issue from a commit

2026-03-28 11:37:29 +00:00

docs: add downstream consumer check to migration workflow

forgejo_admin referenced this issue from a pull request that will close it,

2026-03-28 11:38:05 +00:00

docs: add downstream consumer check to migration workflow #199

forgejo_admin referenced this issue

2026-03-28 11:38:40 +00:00

docs: add downstream consumer check to migration workflow #199

forgejo_admin referenced this issue

2026-03-28 11:41:29 +00:00

docs: add downstream consumer check to migration workflow #199