Formal issue relationship types: parent/child and related (SZ-142)

rk@tigase.net opened 1 week ago

Summary

Sztab currently supports a rudimentary related issues link between issues but has no formal first-class relationship model. This issue introduces two distinct issue relationship types — parent/child and related — each with clearly defined semantics. Workflow coupling (status bubbling, priority propagation, notifications) is explicitly deferred and will be addressed in a follow-on ticket once the relationship model is validated.

Background

During design discussions it became clear that two fundamentally different workflows need to be supported:

Planning workflow — the shape of the work is understood upfront. A master issue is created in the customer-facing project and child issues are spawned deliberately in the relevant projects, each scoped to what that team needs to know.

Triage workflow — the true owner of an issue is not known at creation time. The issue moves fluidly across projects and components as understanding deepens. At any point during triage, once enough is understood, child issues can be spawned to decompose the work.

These two workflows are not mutually exclusive. Child issues can be spawned at any point in the issue lifecycle — during upfront planning or mid-triage.

Reference Use Case

Customer reports an issue in the Atom project. That becomes the master issue. Triage reveals the work spans multiple projects. Child issues are spawned in the backend project and the docs project, each linked to the master. The customer tracks overall progress from the master issue. Each engineer works in their own project with only the context they need.

@andrzej.wojcik — your scenario is the reference use case here, would welcome your input.

Out of Scope

Multi-level hierarchy (grandparent/grandchild)
Automatic child creation — manual spawning only

Activities

rk@tigase.net commented 1 week ago
Proposed Design

Data Model

New issue_relationships table:

id — primary key

source_issue_id — foreign key to issues

target_issue_id — foreign key to issues

type — enum: RELATED, PARENT_CHILD

created_by — foreign key to users

created_at — timestamp

Circular parent references must be rejected at the service layer.

Related Issues (formalise existing)

A lightweight bidirectional link between two issues. Informational only, no workflow coupling. Useful when a connection exists but neither issue depends on the other. This relationship is peer-to-peer — neither issue is subordinate to the other.

Parent/Child Issues (new)

A structured relationship where child issues exist because of the parent. In this iteration the relationship is structural only — workflow coupling is deferred.

Child issues spawned directly from the parent issue UI, pre-populated with relevant context from the parent

Parent issue displays a rollup view of all children showing project, assignee, and current status

Child issues display a reference to their parent

Deferred to Follow-on

Parent closure guard — parent cannot transition to RESOLVED or CLOSED while children remain open

Priority propagation — Critical parent flags if a child is being treated at lower priority

Notifications — child status changes notify parent owner

Status rollup — parent status automatically reflects child resolution states
rk@tigase.net commented 6 days ago

Scope Constraint (v1)

Relationships are same-project only in this implementation. Cross-project relationships are explicitly deferred to a follow-on ticket. The data model is designed to support cross-project linking without a schema change — source_id and target_id reference issue.id globally — but the UI and service layer enforce same-project in this cut.

The cross-project use case (Andrzej's Atom reference scenario) remains the target for v2 once the relationship model is validated in production.
rk@tigase.net commented 6 days ago

Summary

Add the ability to link issues as related. A related link is a symmetric peer-to-peer association with no implied semantics — it simply surfaces connected issues on the detail page.

Data model

New table issue_relation:

column type notes

id UUID PK

issue_id FK → Issue

related_issue_id FK → Issue

created_by FK → User

created_at timestamp

Two mirrored rows per link for simple reads (WHERE issue_id = ?). A unique constraint on (issue_id, related_issue_id) prevents duplicates.

UI — issue detail page

A "Related issues" section showing a flat list of linked issues. Each entry shows issue ID, title, status, and project. No behavioural affordances — links only.

Users can add and remove related issues from the detail page.

Out of scope

Directionality, hierarchy, workflow coupling, notifications, status propagation — all deferred.

column	type	notes
`id`	UUID PK
`issue_id`	FK → Issue
`related_issue_id`	FK → Issue
`created_by`	FK → User
`created_at`	timestamp

rk@tigase.net commented 6 days ago

rksuma@Ramakrishnans-MacBook-Pro sztab % git checkout -b feature/SZ-142-related-issues
Switched to a new branch 'feature/SZ-142-related-issues'
rksuma@Ramakrishnans-MacBook-Pro sztab %

rk@tigase.net changed state to 'In Progress' 6 days ago
Previous Value Current Value
Open

In Progress

Previous Value	Current Value
Open	In Progress

rk@tigase.net commented 6 days ago

Work estimate

subtask	estimate
Flyway migration — `issue_relation` table	30m
`IssueRelation` entity + repository	1h
Service layer — add/remove relation, mirror row logic	1h
REST endpoints — link/unlink	1h
"Related issues" section on issue detail page (React)	2h
Add/remove UX — search/select existing issue, confirmation on remove	2h
Tests	1.5h

Total: ~9 hours

rk@tigase.net commented 5 days ago

rksuma@Ramakrishnans-MacBook-Pro sztab % git commit -m "SZ-142: related issues feature complete"
[feature/SZ-142-related-issues 27a660d] SZ-142: related issues feature complete
 3 files changed, 171 insertions(+), 1 deletion(-)
 create mode 100644 frontend/src/components/issues/IssueRelatedItems.tsx
rksuma@Ramakrishnans-MacBook-Pro sztab % git push
Enumerating objects: 18, done.
Counting objects: 100% (18/18), done.
Delta compression using up to 12 threads
Compressing objects: 100% (10/10), done.
Writing objects: 100% (10/10), 2.60 KiB | 2.60 MiB/s, done.
Total 10 (delta 8), reused 0 (delta 0), pack-reused 0 (from 0)
remote:  
remote: Create a pull request for 'feature/SZ-142-related-issues' by visiting:
remote:     https://tigase.dev/sztab/~pulls/new?target=1325:wolnosc&source=1325:feature/SZ-142-related-issues
remote:  
To https://tigase.dev/sztab.git
   1a30be3..27a660d  feature/SZ-142-related-issues -> feature/SZ-142-related-issues
rksuma@Ramakrishnans-MacBook-Pro sztab % git checkout wolnosc && git merge feature/SZ-142-related-issues && git push
Switched to branch 'wolnosc'
Your branch is up to date with 'origin/wolnosc'.
Updating 35b73a0..27a660d
Fast-forward
 backend/src/main/java/com/sztab/controller/IssueController.java         |  44 +++++++++++++
 backend/src/main/java/com/sztab/model/IssueRelation.java                |  79 ++++++++++++++++++++++++
 backend/src/main/java/com/sztab/repository/IssueRelationRepository.java |  39 ++++++++++++
 backend/src/main/java/com/sztab/service/IssueService.java               |  73 +++++++++++++++-------
 backend/src/main/java/com/sztab/service/impl/IssueServiceImpl.java      |  75 ++++++++++++++++++++++-
 backend/src/main/resources/db/migration/V24__create_issue_relation.sql  |  18 ++++++
 backend/src/test/java/com/sztab/controller/IssueControllerTest.java     | 167 ++++++++++++++++++++++++++++++++++++++++++--------
 backend/src/test/java/com/sztab/service/IssueServiceImplTest.java       | 193 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 frontend/src/api/issues.ts                                              |  16 +++++
 frontend/src/components/issues/IssueEditModal.tsx                       |  18 +++++-
 frontend/src/components/issues/IssueRelatedItems.tsx                    | 138 +++++++++++++++++++++++++++++++++++++++++
 11 files changed, 802 insertions(+), 58 deletions(-)
 create mode 100644 backend/src/main/java/com/sztab/model/IssueRelation.java
 create mode 100644 backend/src/main/java/com/sztab/repository/IssueRelationRepository.java
 create mode 100644 backend/src/main/resources/db/migration/V24__create_issue_relation.sql
 create mode 100644 frontend/src/components/issues/IssueRelatedItems.tsx
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
To https://tigase.dev/sztab.git
   35b73a0..27a660d  wolnosc -> wolnosc
rksuma@Ramakrishnans-MacBook-Pro sztab % git branch
  backup-SZ-Error-Handling-UX-stash
  backup/SZ44-chaos
  bugfix/sz-32-backend-fixes
  experiment/git-compare
  feature/Issue-DSL-Query-Engine
  feature/SZ-142-related-issues
  feature/SZ-48-gitrepo-insane-changes
  feature/first-rev-community-user
* wolnosc
rksuma@Ramakrishnans-MacBook-Pro sztab % git branch -d feature/SZ-142-related-issues && git push origin --delete feature/SZ-142-related-issues
Deleted branch feature/SZ-142-related-issues (was 27a660d).
remote:  
remote: Create a pull request for 'feature/SZ-142-related-issues' by visiting:
remote:     https://tigase.dev/sztab/~pulls/new?target=1325:wolnosc&source=1325:feature/SZ-142-related-issues
remote:  
To https://tigase.dev/sztab.git
 - [deleted]         feature/SZ-142-related-issues
rksuma@Ramakrishnans-MacBook-Pro sztab %

rk@tigase.net changed state to 'Closed' 5 days ago
Previous Value Current Value
In Progress

Closed
Login to comment

Previous Value	Current Value
In Progress	Closed

Type	New Feature
Priority	Normal
Assignee	rk@tigase.net
Version	1.10.1
Sprints	n/a
Customer	n/a

Issue Votes (0)

Watchers (2)

Reference

SZ-142

Summary

Background

Reference Use Case

Out of Scope

Proposed Design

Data Model

Related Issues (formalise existing)

Parent/Child Issues (new)

Deferred to Follow-on

Scope Constraint (v1)

Summary

Data model

UI — issue detail page

Out of scope

Work estimate