Add board_note_id FK to board_items + data migration

forgejo_admin commented

2026-03-24 16:50:39 +00:00

Owner

Type

Feature

Lineage

Standalone — board-pal-e-docs kanban unification. Depends on: "Add board to NoteType"

Repo

forgejo_admin/pal-e-docs

User Story

As the platform owner
I want board items to reference notes instead of the boards table
So that any note (phase, ticket, project page) can have a kanban board attached to it

Context

This is the core migration. Currently board_items.board_id FK → boards.id. After this: board_items.board_note_id FK → notes.id (where note_type="board"). The boards table remains temporarily (dual-write) until downstream consumers are updated.

Steps:

Alembic migration: add board_note_id (nullable FK → notes.id) to board_items
Data migration script: for each existing board, create a note (note_type="board", same slug/name/project_id)
Backfill: set board_items.board_note_id from the board → note mapping
Add NOT NULL constraint on board_note_id after backfill

File Targets

Files to modify:

src/pal_e_docs/models.py — add board_note_id column to BoardItem, add relationship
alembic/versions/ — new migration adding column + FK
scripts/ — data migration script to create board notes and backfill

Files NOT to touch:

src/pal_e_docs/routes/boards.py — API changes are a separate ticket
Board hooks — separate ticket

Acceptance Criteria

board_items table has board_note_id column with FK to notes.id
Every existing board has a corresponding note with note_type="board"
Every board_item has board_note_id populated
Existing board_id still works (dual FK during transition)
Board notes have same slug, name (as title), and project_id as original boards

Test Expectations

Migration runs cleanly on test DB
Data migration creates correct notes for all 6 active boards
Board items query by board_note_id returns same results as by board_id
Run: pytest tests/test_boards.py -v

Constraints

Dual FK period — both board_id and board_note_id valid during transition
Data migration must be idempotent (safe to re-run)
Must handle the unique constraint: board note slugs = existing board slugs

Checklist

PR opened
Tests pass
No unrelated changes

project-pal-e-docs — core migration for kanban unification

### Type Feature ### Lineage Standalone — board-pal-e-docs kanban unification. Depends on: "Add board to NoteType" ### Repo `forgejo_admin/pal-e-docs` ### User Story As the platform owner I want board items to reference notes instead of the boards table So that any note (phase, ticket, project page) can have a kanban board attached to it ### Context This is the core migration. Currently board_items.board_id FK → boards.id. After this: board_items.board_note_id FK → notes.id (where note_type="board"). The boards table remains temporarily (dual-write) until downstream consumers are updated. Steps: 1. Alembic migration: add board_note_id (nullable FK → notes.id) to board_items 2. Data migration script: for each existing board, create a note (note_type="board", same slug/name/project_id) 3. Backfill: set board_items.board_note_id from the board → note mapping 4. Add NOT NULL constraint on board_note_id after backfill ### File Targets Files to modify: - `src/pal_e_docs/models.py` — add board_note_id column to BoardItem, add relationship - `alembic/versions/` — new migration adding column + FK - `scripts/` — data migration script to create board notes and backfill Files NOT to touch: - `src/pal_e_docs/routes/boards.py` — API changes are a separate ticket - Board hooks — separate ticket ### Acceptance Criteria - [ ] board_items table has board_note_id column with FK to notes.id - [ ] Every existing board has a corresponding note with note_type="board" - [ ] Every board_item has board_note_id populated - [ ] Existing board_id still works (dual FK during transition) - [ ] Board notes have same slug, name (as title), and project_id as original boards ### Test Expectations - [ ] Migration runs cleanly on test DB - [ ] Data migration creates correct notes for all 6 active boards - [ ] Board items query by board_note_id returns same results as by board_id - Run: `pytest tests/test_boards.py -v` ### Constraints - Dual FK period — both board_id and board_note_id valid during transition - Data migration must be idempotent (safe to re-run) - Must handle the unique constraint: board note slugs = existing board slugs ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `project-pal-e-docs` — core migration for kanban unification

forgejo_admin commented

2026-03-24 17:21:28 +00:00

Author

Owner

Scope Review: NEEDS_REFINEMENT

Review note: review-315-2026-03-24
Two fixable issues found — ticket is well-structured but has inaccurate data and a missing detail.

Incorrect board count: Test Expectations says "6 active boards" but there are actually 13 boards. Fix the count or define what "active" means.
Missing script filename: File Targets lists scripts/ but doesn't specify the migration script name. Suggest scripts/migrate_boards_to_notes.py for agent clarity.

## Scope Review: NEEDS_REFINEMENT Review note: `review-315-2026-03-24` Two fixable issues found — ticket is well-structured but has inaccurate data and a missing detail. - **Incorrect board count:** Test Expectations says "6 active boards" but there are actually **13 boards**. Fix the count or define what "active" means. - **Missing script filename:** File Targets lists `scripts/` but doesn't specify the migration script name. Suggest `scripts/migrate_boards_to_notes.py` for agent clarity.

forgejo_admin commented

2026-03-24 17:22:06 +00:00

Author

Owner

Fix 1: Test Expectations — corrected board count. There are 13 boards total, not 6. The data migration must create notes for all 13.

Fix 2: File Targets — added explicit script filename: scripts/migrate_boards_to_notes.py

Updated Test Expectations

Migration runs cleanly on test DB
Data migration creates notes for all 13 existing boards
Board items query by board_note_id returns same results as by board_id
Run: pytest tests/test_boards.py -v

Updated File Targets addition

scripts/migrate_boards_to_notes.py — creates board notes + backfills board_note_id

## Review Refinements (from review-315-2026-03-24) **Fix 1:** Test Expectations — corrected board count. There are 13 boards total, not 6. The data migration must create notes for all 13. **Fix 2:** File Targets — added explicit script filename: `scripts/migrate_boards_to_notes.py` ### Updated Test Expectations - [ ] Migration runs cleanly on test DB - [ ] Data migration creates notes for all 13 existing boards - [ ] Board items query by board_note_id returns same results as by board_id - Run: `pytest tests/test_boards.py -v` ### Updated File Targets addition - `scripts/migrate_boards_to_notes.py` — creates board notes + backfills board_note_id

forgejo_admin commented

2026-03-24 17:24:51 +00:00

Author

Owner

Scope Review: READY

Review note: review-315-2026-03-24 (updated)
Re-review after NEEDS_REFINEMENT — both refinements verified and confirmed.

Board count: Verified 13 boards exist (IDs 1-14, no ID 9). Comment #6581 correctly fixes the count.
Script filename: scripts/migrate_boards_to_notes.py explicitly specified in comment #6581.
Note: Issue body was not updated — refinements are in comment #6581 only. Executing agent must read comments for corrected values.

## Scope Review: READY Review note: `review-315-2026-03-24` (updated) Re-review after NEEDS_REFINEMENT — both refinements verified and confirmed. - **Board count:** Verified 13 boards exist (IDs 1-14, no ID 9). Comment #6581 correctly fixes the count. - **Script filename:** `scripts/migrate_boards_to_notes.py` explicitly specified in comment #6581. - **Note:** Issue body was not updated — refinements are in comment #6581 only. Executing agent must read comments for corrected values.