Design & modeling

Clarifying invariants, reviewer quorum rules, state machine, and DTO boundaries 6–8 hours

Backend (domain + APIs + tests) • PR discovery queries (dashboard) • Commit/branch discovery APIs • Diff retrieval plumbing • Contextual comment anchoring • Approval/state transition validation 14–18 hours

Frontend (UI + modals + diff viewer) • PR dashboard view • PR creation modal • PR detail page • Diff rendering + comment UI • Role-gated actions 16–20 hours

Integration & stabilization • End-to-end flows • Fixing impedance mismatches • UX friction removal 6–8 hours

⸻

Total estimate

≈ 42–54 hours

Pull Request Management Workflow:

This is the workflow I have in mind to manager pull requests:

Pull Request Workflow — End-to-End Description

This document describes the end-to-end Pull Request (PR) workflow in Sztab, from discovery and creation to review, approval, and merge. It also captures the navigation affordances and deletion constraints that make PRs a first-class, safe workflow entity.

Pull Request Dashboard

A user (developer, QA engineer, project manager, or admin) starts by visiting the Pull Request dashboard.

The dashboard is role-aware and presents PRs that are relevant to the logged-in user. Each PR entry is clickable and navigates to the PR detail page, which also serves as the entry point to the diff view.

The dashboard organizes PRs into logical lists depending on the user’s role:

• Author
  Pull requests authored by the logged-in user.

• Reviewer
  Pull requests where the logged-in user is assigned as a reviewer.

• Project Manager
  Pull requests that belong to projects managed by the logged-in user.

• Admin
  All open pull requests in the system.

A pull request may appear in multiple lists for the same user (for example, if the user is both the author and a reviewer).

Creating a Pull Request

A user creates a new pull request by providing the following information:

• A title and description explaining the intent of the change.
• The source branch and a specific commit ID.
  From this commit, Sztabina determines the list of affected files and generates the diffs.
• The target branch, which defaults to the project’s main (master) branch.
• A list of reviewers.
  For the initial implementation, all reviewers are treated as mandatory reviewers.
• An approval criterion, which defines how the PR can be approved:
  • ANY — approval by any one reviewer is sufficient.
  • CONSENSUS — approval by a majority of reviewers is required.
  • UNANIMOUS — all reviewers must approve.

Once the PR is saved:

• Its state becomes OPEN.
• Notification emails are sent to all reviewers and to the author.
• The PR appears in the dashboards of both the author and the reviewers.

Pull Request States and Transitions

A pull request progresses through the following states:

Open => Closed

The author may revoke the pull request, moving it from OPEN to CLOSED.
When this happens, notification emails are sent to all reviewers.

Closed => Open

The author may reopen a previously closed pull request without changing its attributes.
Notification emails are again sent to all reviewers.

Open => Approved

A pull request moves from OPEN to APPROVED based on its approval criterion:

• ANY: at least one reviewer approves.
• CONSENSUS: more than 50% of reviewers approve.
• UNANIMOUS: all reviewers approve.

Open => Open

While a PR is open, reviewers may add comments (including contextual comments on diffs).
Comments do not change the PR state.

Approved => Merged

Once approved, the author may merge the pull request.
Sztabina performs the merge by executing the appropriate Git commands to merge the source into the target branch.

Navigation and Linking

Pull requests are deeply integrated into the rest of the system and support rich navigation:

• Every User, Project, Branch, Issue, and Pull Request has a stable URL.
• Clicking a PR anywhere navigates to its PR detail page.
• Clicking the author or any reviewer navigates to that user’s edit/view page.
• Clicking the associated issue navigates to the issue detail page.
• Clicking the project navigates to the project edit page.
• Clicking the source or target branch navigates to the branch edit page.

This ensures that PRs are not isolated objects, but part of a connected workflow.

Deletion and Integrity Constraints

To preserve workflow integrity, the following constraints apply:

• An issue with pending pull requests cannot be deleted.
  The issue list page shows the number of associated PRs.
• A branch that has pull requests cannot be deleted.
• A user who has pending pull requests (as an author or as a reviewer) cannot be deleted.

These constraints ensure that pull requests cannot be orphaned or silently invalidated.

Summary

Pull requests in Sztab are treated as first-class workflow entities.
They are discoverable via role-aware dashboards, enforce explicit approval rules, support rich navigation across related entities, and protect system integrity through strict deletion constraints.

The workflow is designed to be explicit, auditable, and difficult to misuse, while remaining simple enough to evolve in future iterations.

UI Implementation notes:

Branch: feature/SZ-pull-request-workflow

UI files:

• src/types/pr.ts
• src/api/pr.ts
• src/components/pr
• src/pages/pr

$ pwd
/Users/rksuma/tigase/sztab/frontend/src/pages/pr
$ ls -l
total 40

 -rw-------@ 1 rksuma  staff  13536 Dec 23  2025 PrDetailPage.tsx
 -rw-------@ 1 rksuma  staff    319 Dec 23  2025 PrListPage.tsx

$
$ pwd
/Users/rksuma/tigase/sztab/frontend/src/components/pr
$ ls -l
total 112

 -rw-------@ 1 rksuma  staff  18360 Dec 23  2025 DiffViewer.tsx
 -rw-------@ 1 rksuma  staff  21738 Dec 23  2025 PrList.tsx
 -rw-------@ 1 rksuma  staff  11764 Dec 23  2025 ReviewPanel.tsx

$