v0.3.0 Merge Strategy & Dependency Tracker

[JohnRDOrazio]

v0.3.0 Merge Strategy

This issue tracks the merge order and dependency relationships for all v0.3.0 PRs across both ontokit-api and ontokit-web. Issues within the same phase can generally be parallelized unless a specific dependency is noted.

Project board: https://github.com/orgs/CatholicOS/projects/6

---

Phase 1: Foundation

Migrations, deployment fixes, and infrastructure that other work depends on. Merge these first.

• ontokit-web#20 + ontokit-web#21 — Deployment fixes (/app/public + .next/standalone missing) — same branch (PR), merge together
• ontokit-api#11 — Auto-run database migrations on container startup (PR)
• ontokit-api#12 — NormalizationRun model not registered in models/__init__.py (bug) (PR)
• ontokit-api#9 — PostgreSQL ontology index tables (migration + indexing service, PR) — must merge before ontokit-web#33
• ontokit-api#5 — Include branch refs in revision history response (PR) — must merge before ontokit-web#8
• ontokit-api#2 — SPARQL endpoint wiring fix (PR, independent)

Phase 2: Core Features

Main feature work. Some items are blocked by Phase 1.

• ontokit-api#15 + ontokit-api#16 — IndexedOntologyService bugs: instance_count=0 + empty equivalent/disjoint IRIs — must fix before Web Add PostgreSQL index tables for ontology query optimization #33 lands (PR)
• ontokit-web#49 — Handle nullable index fields from API (PR #50) — ⚠️ blocked by ontokit-api#15 + ontokit-api#16 (API PR ontokit-api#18)
• ontokit-api#17 — Inconsistent import style for OntologyIndexService and get_arq_pool (cleanup) — related to ontokit-api#9 (PR)
• ontokit-web#33 — PostgreSQL ontology index (frontend) (PR #36) — ✅ All blockers merged (API Remove duplicate branch display in editor header #9, Upgrade lucide-react from 0.468 to 0.577 #15, Upgrade Zod from 3 to 4 #16, Upgrade Next.js 15 → 16 + next-intl 3 → 4 + eslint-config-next 16 #17, Web fix: handle nullable fields from API index path #49)
• ontokit-web#8 — Git history graph with branch topology (PR #10) — ✅ Phase 1 blocker (ontokit-api#5) merged
• ontokit-web#30 — Exemplar ontology support (PR #25)
• ontokit-web#6 — Explicit Save button in detail panel (PR #7)
• ontokit-web#4 + ontokit-web#5 — GitHub-linked upstream source + read-only sync fields — same branch (PR #37), merge together
• ontokit-api#6 — Lint error limiting + auto-fix — frontend fix: (Web PR #41)
• ontokit-web#31 — Auth UX for private projects (PR #26)
• ontokit-web#35 — Skip project dashboard page, navigate directly to editor (PR #39)
• ontokit-web#46 — Make projects page the landing page with Public/Private/All tabs (PR #47, independent)

Phase 3: Polish & Upgrades

Bug fixes, docs, and dependency upgrades. Lower risk, merge last.

• ontokit-web#29 — Fix misleading import error message (PR #24)
• ontokit-web#9 — Remove duplicate branch display (PR #40)
• ontokit-web#32 — Add Genesis section to README (PR #28)

Dependency upgrades (ordered):

• ontokit-web#15 — Upgrade lucide-react 0.468 → 0.577 (lowest risk) (PR #43)
• ontokit-web#16 — Upgrade Zod 3 → 4 (independent) (PR #42)
• ontokit-web#18 — Upgrade Tailwind CSS 3 → 4 (PR #44) — must merge before ontokit-web#17
• ontokit-web#17 — Upgrade Next.js 15 → 16 (PR #45) — ⚠️ merge last (highest blast radius, all other branches should land first)

Phase 4: Pre-release Bug Fixes

Remaining bug fixes and small improvements before v0.3.0 release.

• ontokit-api#29 — Add search parameter to project list endpoint (API PR #28) — must merge before Web fix: project list shows misleading count without pagination #52
• ontokit-web#52 — fix: project list with server-side search and pagination (PR #71)
• ontokit-web#53 — fix: accessToken in React Query key causes unnecessary refetches (PR #70)
• ontokit-web#54 — fix: use React Query refetch instead of window.location.reload() on error (PR #73)
• ontokit-api#32 — Add filter=private to project list endpoint (API PR #35) — must merge before Web feat: add My Projects and Private tabs with correct filtering #55
• ontokit-web#55 — feat: add My Projects and Private tabs with correct filtering (PR #69)
• ontokit-web#58 — Bug: branch switcher is active for unauthenticated users (PR #68)
• ontokit-web#74 — Separate viewer and editor routes for projects (PR #82, supersedes #59)
• ontokit-web#85 — Bug: viewer source tab empty in developer mode (PR #86)
• ontokit-web#75 — Add share button to copy project permalink (PR #87, depends on Separate viewer and editor routes for projects #74)
• ontokit-web#64 — Rename manualSave to hideSaveButton and default to false (PR #72)
• ontokit-api#31 — Rename 'upstream sync' to 'remote sync' (backend) — merge with ontokit-web#79
• ontokit-web#79 — Rename 'upstream sync' to 'remote sync' (frontend) — merge with ontokit-api#31
• ontokit-web#83 — Suppress exhaustive-deps warning in useProjectViewer.ts (PR #91)
• ontokit-web#84 — Move Radix Tooltip Provider to app level for shared usage (PR #90)
• ontokit-api#24 — fix: wrap webhook handler's arq enqueue in try/except (API PR #41)
• ontokit-api#25 — docs: add Field descriptions for nullable OWLClassResponse fields (API PR #38)
• ontokit-api#34 — Evaluate returning unfilteredTotal in project list endpoint (API PR #40)
• ontokit-api#36 — Docs: filter_type docstring missing 'private' option (API PR #39)
• ontokit-api#42 — fix: resolve CodeQL security alerts (API PR #43)
• ontokit-api#44 — fix: resolve mypy errors in scripts/setup-zitadel.py (API PR #45)
• ontokit-api#46 — test: improve code coverage from 40% to 52% (API PR #47)
• ontokit-web#92 — Show unfiltered project count when search/filter is active (PR #93) — depends on ontokit-api#34
• ontokit-web#94 — Increase test coverage: hooks, API clients, and components (PR #95)

---

Post-v0.3.0 planning: See ontokit-web#67 — v0.4.0 Merge Strategy & Dependency Tracker for all issues targeting the next release.

---

Dependency Graph

graph TD
  subgraph Phase 1: Foundation
    A9["API #9<br/>PG index tables"]:::done
    A5["API #5<br/>Branch refs in history"]:::done
    A11["API #11<br/>Auto-migrate"]:::done
    A12["API #12<br/>Model registration"]:::done
    A2["API #2<br/>SPARQL wiring"]:::done
    W20["Web #20+#21<br/>Deployment fixes"]:::done
  end

  subgraph Phase 2: Core Features
    A15["API #15+#16<br/>Index service bugs"]:::done
    A17["API #17<br/>Import cleanup"]:::done
    W49["Web #49<br/>Nullable index fields"]:::done
    W33["Web #33<br/>PG index frontend"]:::done
    W8["Web #8<br/>Git history graph"]:::done
    W30["Web #30<br/>Exemplar ontology"]:::done
    W6["Web #6<br/>Save button"]:::done
    W4["Web #4+#5<br/>GitHub upstream sync"]:::done
    A6["API #6<br/>Lint error limiting"]:::done
    W31["Web #31<br/>Auth UX"]:::done
    W35["Web #35<br/>Skip dashboard"]:::done
    W46["Web #46<br/>Landing page tabs"]:::done
  end

  subgraph Phase 3: Polish & Upgrades
    W29["Web #29<br/>Import error msg"]:::done
    W9["Web #9<br/>Dup branch display"]:::done
    W32["Web #32<br/>README genesis"]:::done
    W15d["Web #15<br/>lucide-react upgrade"]:::done
    W16d["Web #16<br/>Zod upgrade"]:::done
    W18["Web #18<br/>Tailwind 3→4"]:::done
    W17["Web #17<br/>Next.js 15→16"]:::done
  end

  subgraph Phase 4: Pre-release
    A29["API #29<br/>Search param"]:::done
    W52["Web #52<br/>Server-side search"]:::done
    A32["API #32<br/>filter=private"]:::done
    W55["Web #55<br/>My Projects tabs"]:::done
    W53["Web #53<br/>Query key fix"]:::done
    W54["Web #54<br/>RQ refetch"]:::done
    W58["Web #58<br/>Branch switcher"]:::done
    W74["Web #74<br/>Viewer/editor split"]:::done
    W85["Web #85<br/>Viewer source fix"]:::done
    W75["Web #75<br/>Share button"]:::done
    W64["Web #64<br/>hideSaveButton"]:::done
    A31["API #31 + Web #79<br/>Remote sync rename"]:::done
    W83["Web #83<br/>exhaustive-deps"]:::done
    W84["Web #84<br/>Tooltip provider"]:::done
    A24["API #24<br/>Webhook try/except"]:::open
    A25["API #25<br/>Field descriptions"]:::open
    A34["API #34<br/>unfilteredTotal"]:::open
    A36["API #36<br/>Docstring fix"]:::open
  end

  %% Phase 1 → Phase 2 dependencies
  A9 --> A15
  A9 --> A17
  A15 --> W49
  A15 --> W33
  A17 --> W33
  W49 --> W33
  A5 --> W8

  %% Phase 3 dependency chain
  W18 --> W17

  %% Phase 4 dependencies
  A29 --> W52
  A32 --> W55
  W74 --> W75
  W74 --> W85

  %% Styles
  classDef done fill:#d4edda,stroke:#28a745,color:#155724
  classDef open fill:#fff3cd,stroke:#ffc107,color:#856404

Loading

[JohnRDOrazio]

@damienriehl I created a project board to track the issues between ontokit-api and ontokit-web, and asked claude to categorize and organize the issues in a proper order so that we have a clear merge strategy. This issue lays out the roadmap for merging the various open issues, whether in progress or todo. For now all issues have v0.3.0 as a milestone; as long as we only have a limited amount of issues that we are working on, we can simply set them all to the next release milestone. If in the future we start to have hundreds of issues, then we might want to organize them between multiple release milestones, but for now I would keep it simply and set all open issues to the next release milestone.