egutierrez
fe0265c3bf
- modules/data_table/MIGRATION.md: porting guide + release checklist 1.0.0-stable
- data_table.md: growth log entry commented for post-gate bump
- data_table.md: fix error_type Go remnant ("error_go_core" -> "") in C++ module
- cpp/CMakeLists.txt: SQLite3 optional dep for data_table_bench (cross-windows)
- agent_cleanup_worktree.go: !windows build tag (uses unix-only syscalls)
- dev/issues/0133-cpp-data-table-10m-rows.md: issue tracking
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
149 lines
8.4 KiB
Markdown
149 lines
8.4 KiB
Markdown
# data_table MIGRATION guide
|
|
|
|
Referencia para apps que migran a v1.0.0 estable del modulo `data_table`.
|
|
La version de modulo (`module.md`) es semver independiente del entrypoint (`data_table.md`).
|
|
Este documento cubre el salto al hito de estabilidad 1.0.0, no versiones intermedias.
|
|
|
|
---
|
|
|
|
## v2.x → estabilidad 1.0.0 (pendiente gate 0133)
|
|
|
|
### What changed (internals — no API change)
|
|
|
|
Las optimizaciones planificadas en issue 0133 son **transparentes para el caller**. La API publica (`data_table.h`) no cambia.
|
|
|
|
| Cambio interno | Impacto en caller |
|
|
|---|---|
|
|
| Columnar snapshot interno (agente B) | Ninguno. `TableInput.cells` sigue siendo row-major caller-owned. |
|
|
| String interning de celdas en snapshot | Ninguno. Misma interfaz de lectura. Strings siguen viviendo en el caller. |
|
|
| Lazy `visible_rows` (filter + sort diferidos) | Ninguno. `render()` sigue siendo una sola llamada por frame. |
|
|
| Display cache per-cell | Ninguno. La cache es opaca al caller. |
|
|
| OpenMP en compute (agente A bench gate) | Ninguno. Threading interno, thread-safety invariante: llamar solo desde el main thread de ImGui. |
|
|
|
|
### What you must do
|
|
|
|
**Nada**, si usas la API publica.
|
|
|
|
- `data_table::render(id, tables, st, events_out, show_chrome)` — firma identica.
|
|
- `TableInput`, `State`, `TableEvent`, `ColumnSpec`, `ColorRule` — sin cambios de layout.
|
|
- Back-compat overload `render(id, tables, st, show_chrome)` — sigue compilando.
|
|
|
|
Casos especificos:
|
|
|
|
| Situacion | Accion |
|
|
|---|---|
|
|
| Guardabas punteros a `TableInput.cells` entre frames | Sigue valido. El caller es dueno de `cells`; el modulo no lo mueve ni libera. |
|
|
| Usabas `data_table_internal.h` directamente | Rebuild obligatorio. El header es privado del modulo — si lo incluias, estabas fuera del contrato. No se garantiza estabilidad de `UiState` ni de los helpers internos. |
|
|
| Enlazan `fn_table_viz` (target antiguo) | Reemplazar por `fn_module_data_table`. El target `fn_table_viz` fue deprecado en v1.4.0 (2026-05-16). |
|
|
|
|
### Behavior contracts preserved
|
|
|
|
Estos contratos estan FROZEN en v1.0.0 y no pueden romperse sin major version bump:
|
|
|
|
- **Bit-identical rendering**: misma entrada → misma salida visual (excepto antialiasing de ImGui).
|
|
- **`TableEvent.row` indexa `TableInput`**: los indices de fila en eventos (`ButtonClick`, `RowDoubleClick`, `RowRightClick`) referencian la tabla de entrada original, no el snapshot interno ni la vista filtrada.
|
|
- **`stats_last_cells` pointer-identity sentinel**: el campo `State::stats_last_cells` se usa internamente para detectar cambio de datos. Si el caller pasa el mismo puntero `cells` en frames consecutivos, el modulo reutiliza la cache de stats. Cambiar el puntero (aunque el contenido sea igual) invalida la cache — comportamiento documentado y frozen.
|
|
- **`events_out` solo hace `push_back`**: `render()` nunca llama `clear()` ni `resize()` sobre el vector del caller. El caller limpia antes de cada frame si no quiere acumulacion.
|
|
- **`show_chrome = true` por defecto**: el overload de back-compat sin `show_chrome` pasa `true`.
|
|
- **`State` es caller-managed**: el modulo no alloca ni libera el `State`. El caller lo destruye cuando quiere.
|
|
|
|
### New (optional, v1.0.0+)
|
|
|
|
*(placeholder — se documentaran aqui las features opt-in que lleguen post-gate)*
|
|
|
|
---
|
|
|
|
## Backwards compatibility policy
|
|
|
|
La API publica de `data_table::render`, `TableInput`, `State`, `TableEvent`, `ColumnSpec` y `ColorRule` esta **FROZEN** en v1.0.0.
|
|
|
|
- **Breaking changes** (cambiar firma, quitar campo, cambiar semántica de parametro existente) requieren major version bump y un periodo de coexistencia con el path anterior.
|
|
- **Additive changes** (nuevo campo en struct con default sensato, nuevo overload, nuevo `CellRenderer` enum value) son minor — consumidores existentes no necesitan cambios.
|
|
- **Bugfixes** y optimizaciones internas son patch — sin cambio de contrato.
|
|
|
|
Apps consumidoras que solo usen `#include "data_table/data_table.h"` y `#include "core/data_table_types.h"` no necesitan cambios en minor y patch bumps.
|
|
|
|
---
|
|
|
|
## Porting desde el playground (pre-registry)
|
|
|
|
Si tu app usaba el playground original (`cpp/apps/primitives_gallery/playground/tables/data_table.h`):
|
|
|
|
1. **Cambiar include path**:
|
|
```cpp
|
|
// Antes
|
|
#include "tables/data_table.h"
|
|
#include "tables/data_table_types.h"
|
|
|
|
// Despues
|
|
#include "data_table/data_table.h"
|
|
#include "core/data_table_types.h"
|
|
```
|
|
|
|
2. **Cambiar target CMake**:
|
|
```cmake
|
|
# Antes
|
|
target_link_libraries(mi_app PRIVATE fn_table_viz)
|
|
|
|
# Despues
|
|
target_link_libraries(mi_app PRIVATE fn_module_data_table)
|
|
```
|
|
|
|
3. **`app.md`**: declarar `uses_modules: [data_table_cpp]` en lugar de listar funciones miembro individualmente.
|
|
|
|
4. **Namespace identico**: `data_table::render`, `data_table::State`, `data_table::TableInput` — sin cambios.
|
|
|
|
5. **`data_table_logic.h` eliminado**: los helpers internos del playground (`row_to_tsv`, drill, view_mode, etc.) eran privados. En el modulo son `static` en `data_table.cpp`. Si los necesitabas externamente, estan fuera del contrato — contactar para evaluar si deben promoverse al registry.
|
|
|
|
---
|
|
|
|
## Release checklist (gate 0133 — NO ejecutar hasta A+B listos)
|
|
|
|
Pasos exactos para ejecutar cuando agentes A y B completen su trabajo:
|
|
|
|
1. **Bench gate**: `data_table_bench --rows 10000000` debe reportar `fps_p1 >= 60`. El agente A construye el bench; esta metrica es el prerequisito de estabilidad.
|
|
|
|
2. **fn doctor clean**: `fn doctor cpp-apps` debe pasar sin nuevos `CANDIDATE` (tablas inline sin migrar en apps consumidoras). Indica que todos los consumidores usan el modulo correctamente.
|
|
|
|
3. **Build 11 consumidores**: compilar los 11 apps que linkean `fn_module_data_table` sin errores ni warnings nuevos. Verificar con:
|
|
```bash
|
|
cd cpp/build && cmake --build . --target \
|
|
registry_dashboard kanban dag_engine_ui services_monitor \
|
|
graph_explorer chart_demo 2>&1 | grep -E "error:|warning:"
|
|
```
|
|
*(ajustar lista de targets segun `fn doctor cpp-apps` output)*
|
|
|
|
4. **Version bump**:
|
|
```bash
|
|
/version modules/data_table minor "estable 1.0.0 + columnar + 10M rows"
|
|
```
|
|
Esto bumpa el campo `version:` en `module.md` (actualmente `2.1.0`) a `3.0.0` (major bump porque el modulo alcanza estabilidad contractual) o al numero que corresponda segun la politica semver del proyecto en ese momento.
|
|
|
|
> Nota: `data_table.md` tiene version `1.5.0` (entrypoint). `module.md` tiene `2.1.0` (modulo). El bump de "estabilidad 1.0.0" es un hito de politica — el numero exacto lo decide el operador segun cual de los dos .md es la fuente de verdad para el semver del modulo.
|
|
|
|
5. **Tag stable**: en `module.md` frontmatter, anadir `tags: [stable]` al array existente `[tables, viz, ui, imgui, tql, cpp]`.
|
|
|
|
6. **Capability growth log**: descomentar la entrada preparada en `data_table.md` (ver seccion al final del archivo), rellenando la fecha real `YYYY-MM-DD`.
|
|
|
|
7. **Push + tag git**:
|
|
```bash
|
|
git add modules/data_table/module.md modules/data_table/data_table.md
|
|
git commit -m "feat(data_table): stable 1.0.0 — columnar + 10M rows gate passed"
|
|
git tag data_table/v1.0.0
|
|
git push && git push --tags
|
|
```
|
|
|
|
---
|
|
|
|
## Inconsistencias detectadas en doc actual
|
|
|
|
Las siguientes inconsistencias fueron detectadas durante la preparacion de este documento. No bloquean el gate pero conviene resolver antes del bump:
|
|
|
|
1. **Version drift entre los dos .md**: `data_table.md` tiene `version: 1.5.0` y `module.md` tiene `version: 2.1.0`. Son versionados independientemente pero no esta documentado explicitamente cual es la "version publica" del modulo. Recomendacion: clarificar en `module.md` que su version es la del modulo como unidad y `data_table.md` es la del entrypoint como funcion del registry.
|
|
|
|
2. **`error_type: "error_go_core"` en `data_table.md`**: la funcion es C++ pura (no retorna `error` de Go). El campo `error_type` del frontmatter parece heredado del template Go. No afecta el comportamiento pero es semanticamente incorrecto para un entrypoint C++.
|
|
|
|
3. **`tests` array en `data_table.md` apunta a `cpp/tests/test_column_specs.cpp`** pero la documentacion dice "No hay tests unitarios directos". Los tests listados son del harness de compilacion (`cpp/tests/`), no del entrypoint en si. Aclarar en `## Notas` que el `test_file_path` referencia tests de compilacion/link, no tests de render.
|
|
|
|
4. **`llm_anthropic_cpp_core` en `module.md` uses_functions** pero `data_table.md` no lo lista (stub interno). Alinear: si el stub es interno al modulo, deberia estar en `members`, no en `uses_functions`.
|