Task: Investigate target layout for component regrouping

Table of Contents

This page documents a task in the Regroup C++ components under product-group parent directories story. It captures the goal, current status, acceptance, and any notes or results.

Goal

Decide the target layout for product-group regrouping and the implementation strategy before moving any files. The output is a written decision (landing in the story's * Decisions section) and the per-group migration tasks scaffolded against that decision.

This is investigation, not implementation. No files move in this task.

Status

Field Value
State DONE
Parent story Regroup C++ components under product-group parent directories
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-06-02

Acceptance

  • Each open question below has a written answer recorded in the story's * Decisions section, with the reasoning.
  • A scoping survey is committed: every file that needs to change for refdata, grouped by category (CMake, codegen output paths, CI, presets, tooling, IDE, docs).
  • Per-group migration tasks scaffolded under this story (one per product group), each starting from the agreed plan.
  • The pilot task (refdata) has its plan fully written before any implementation begins.

Open questions

Q1. Child directory naming

Two options for child component directories inside the group:

Option Path Pro Con
FQ projects/ores.refdata/ores.refdata.api/ Folder name self-identifies in IDE breadcrumbs and grep. Verbose; redundant prefix repeated in every path.
Short projects/ores.refdata/api/ Concise; clean. Folder name alone (api/) is ambiguous in grep / git log; mental load to match folder to component.

Recommendation to investigate: short, since the group folder already disambiguates and CMake target names keep the FQ form for compiler consumption.

Q2. The ores.qt.<group> sibling

ores.qt.refdata breaks the ores.<group>.<role> pattern: the namespace prefix is ores.qt. rather than ores.refdata.. Three options:

  1. Move under the group as projects/ores.refdata/qt/ (or projects/ores.refdata/ores.qt.refdata/ under the FQ option). Group becomes "everything refdata-flavoured" regardless of namespace.
  2. Move under a separate qt group projects/ores.qt/refdata/. Mirrors the namespace exactly but creates a parallel taxonomy.
  3. Rename the C++ namespace to ores.refdata.qt so the directory and namespace agree. Out of scope (separate refactor).

Recommendation to investigate: option 1. The directory layout exists to help humans navigate; the namespace can stay where it is.

Q3. Who owns projects/ores.<group>/CMakeLists.txt?

The group root CMakeLists has at minimum add_subdirectory calls for each child. It may also factor common settings (warning flags, boost lookup, target alias namespaces). Question: is the group root a genuine reduction in duplication, or just a trampoline?

Survey what each projects/ores.refdata.*/CMakeLists.txt does today and identify common boilerplate worth lifting.

Q4. Codegen output paths

The profile manifest's output: patterns and any template-side path construction reference projects/ores.refdata.api/.... After regroup they need to point at projects/ores.refdata/api/... (or whatever Q1 settles on). Question: how many output patterns are affected, and do they share a common helper or is the path duplicated per template?

Q5. Tooling and CI

Inventory of path-bearing places that need updating:

  • CMakeLists.txt at repo root (add_subdirectory).
  • All per-component CMakeLists.txt referencing siblings via add_subdirectory(../ores.refdata.api ...).
  • CMakePresets.json / per-preset configs.
  • .github/workflows/*.
  • doc/recipes/ and other docs hard-coding paths.
  • .compass.db path resolver (projects/ores.refdata.api/...).
  • plantuml renders any old paths into C4 diagrams.
  • VS Code workspace files, .clang-format cascades.

This task produces the inventory; the pilot task fixes them.

Plan

1. Survey

Walk projects/ and git grep 'ores\.refdata\.api' (and .core, .service, ores.qt.refdata) to enumerate every reference. Capture the counts per category in the story's * Decisions section.

2. Decide

Resolve Q1–Q3 (Q4 and Q5 are surveys; their output feeds the per-group plans). Record the decision and reasoning under * Decisions.

3. Scaffold per-group tasks

For each product group (refdata first; then trading, iam, dq, analytics, reporting, scheduler, workflow, controller, database, workspace, compute), scaffold a task via compass add task --parent-dir doc/agile/versions/v0/sprint_19/regroup_components ... with a plan body that follows the refdata pilot template.

4. Pilot plan

Write the refdata pilot's full plan (which files move, the git mv sequence, the search-and-replace patterns, the verification script). Subsequent groups inherit this plan with names substituted.

5. Commit + raise PR

Just docs (story update + investigation deliverable + scaffolded follow-on tasks). One PR.

Notes

PRs

PR Title
#997 [build] Regroup C++ components under product-group parent directories

Review

Comment summary File Decision Notes
       

Result

The open questions were resolved and, rather than scaffolding one migration task per product group, the regroup was carried out in a single pass (the change is mechanical and atomic — splitting it per group would have created merge churn for no benefit). The decisions are recorded in the story's * Decisions section (D1–D5). Summary:

  • D1 — child folders use short names (api, core, service, …); CMake target names keep the FQ form.
  • D2 — all Qt UI components live under ores.qt/ (Application layer), not beside their domain group.
  • D3 — the Qt host app moved to ores.qt/application/; ores.qt/ is a pure group folder.
  • D4 — include paths made relative / move-invariant (${CMAKE_CURRENT_SOURCE_DIR}/../include).
  • D5 — no group-root CMakeLists introduced; projects/CMakeLists.txt still adds each leaf directly.

Implementation: every projects/ores.<group>.<role>/ and projects/ores.qt.<group>/ moved under its group parent with git mv; projects/CMakeLists.txt and ~90 component src/CMakeLists.txt include paths updated; cmake --preset linux-clang-debug-make configures cleanly. Build + ctest verification carried out before merge.

No per-group split tasks were created; this task subsumed both the investigation and the implementation.

Emacs 29.1 (Org mode 9.6.6)