Idea: Stop syncing data to legacy epic tables

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

WorkItem RelatedLink Implementation Strategy

Background

Issue #515885 (closed) revealed a bug where WorkItem RelatedLinks were created without corresponding Legacy Epic RelatedLinks. This prompted a discussion about how to handle such synchronization issues going forward, especially as work items become the source of truth.

Current State

After completing Workstream 5 for related epic links, the WorkItem system is now the source of truth. We're working on making it the source of truth for Epic-Issue and Epic-Epic hierarchies as well. Epic creation and updates will soon go through WorkItems first.

For RelatedLinks:

  1. When creating an issue_link between epic work items, we create a corresponding related_epic_links entry and copy the data. The related_epic_links table will soon have a NOT NULL constraint on issue_link_id.
  2. Legacy REST and GraphQL APIs query only the related_epic_links table.
  3. While we ensure every related_epic_link has an issue_link, the reverse isn't guaranteed, potentially causing API inconsistencies.

Proposed Solution

Instead of continuing to sync data between tables, we propose using the issue_links IDs directly. We've evaluated several approaches:

Option 1: Negative IDs on API ❌

  • Use negative IDs to indicate work item table queries
  • Rejected due to existing clients assuming positive integers

Option 2: Store Offset ⚠️

  • Store highest ID of related_epic_links in separate table
  • Stop backfilling to related_epic_links
  • Use new table for IDs higher than stored maximum
  • Problem: Database rollbacks could cause inconsistent IDs

Option 3: Store Offset + Adapt Sequence ✅

Recommended approach:

  1. Update RelatedWorkItemLink.id sequence to match maximum ID between both tables
  2. Stop adding records to RelatedEpicLink
  3. Add rollback trigger to maintain ID synchronization
  4. Include backdated migration for trigger cleanup
  5. Maintain ID consistency even during rollbacks

Screenshot_2025-02-12_at_11.08.19

Benefits

  1. Reduced database writes
  2. Lower risk of synchronization errors
  3. No expensive backfills needed
  4. Consistent treatment of new work item epic data

Drawbacks

  1. Initial implementation complexity for offset and sequence adaptation
  2. Risk in handling edge cases during implementation

Alternative

The only alternative is to:

  1. Continue syncing IDs to legacy tables
  2. Eventually break and remove existing REST APIs and provide a work-item alternative
Edited by 🤖 GitLab Bot 🤖