egutierrez
48dd5a1869
- apps_tbd.md: tabla de decision para WIP en working tree (incluir/flag/stash/issue separado) - feature_flags.md (nuevo): doctrina TBD oficial, patrones Go/TS/Bash/Py, branch-by-abstraction, anti-patrones - INDEX: entrada 24 Refs: trunkbaseddevelopment.com/feature-flags y branch-by-abstraction. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3.6 KiB
Trunk-based development (TBD) en apps generadas con fn
El registry NO usa TBD (push directo a master OK). Pero toda app generada con fn que viva en apps/, projects/<name>/apps/ o que se despliegue a un VPS via deploy_server DEBE seguir TBD mientras se desarrolla.
Tronco unico: master en todos los repos dataforge/<name> del ecosistema (apps + analyses). Ver ADR 0002. El default de git init debe estar en master (git config --global init.defaultBranch master) — los pipelines de scaffolding y ensure_repo_synced_bash_infra ya pasan master explicitamente.
master ← siempre deployable
↑
└── issue/<NNNN>-<slug> ← rama efimera (horas)
└── quick/<slug> ← cambios rapidos sin issue
commits atomicos (feat:, fix:, test:, docs:, refactor:, chore:)
merge --no-ff → master → push → delete branch
Reglas
- Nunca trabajar directo en master para una app. Crear
issue/<NNNN>-<slug>oquick/<slug>primero. - Commits atomicos por bloque logico (no WIP, no mezclar tipos).
- Tests obligatorios antes de mergear (los que aplique al stack: ctest/go test/pytest/...).
merge --no-ffpreserva la historia paralela.git log --first-parent masterda la vista limpia.- Feature flags (no WIP) cuando una feature no cabe en una sola rama. Archivo:
dev/feature_flags.json. Detalle:feature_flags.md.
Que hacer cuando aparece WIP en el working tree
Doctrina TBD: master siempre desplegable. Si tras implementar un issue queda codigo a medias en otros archivos (modificado pero no terminado), HAY DOS opciones legales:
| Caso | Accion |
|---|---|
| WIP no relacionado al issue, pequeño, ya estable (ej. null-guards de un bug menor) | Incluirlo en el commit del issue solo si compila + tests pasan. Mencionarlo en el cuerpo del commit. |
| WIP relacionado al issue pero incompleto | Envolver en feature flag OFF (enabled: false en dev/feature_flags.json). Mergear codigo terminado y testeado. Activar flag en commit posterior. |
| WIP de otra feature distinta, no terminada | NO mergear con el issue. git stash o crear issue/<otro>-... para llevarlo aparte. NO romper master. |
| Pre-existing failing tests (no causados por la rama) | Documentar en cuerpo del commit/PR. Crear issue separado para el fix. NO bloquea merge si tu cambio no los introduce. |
Regla de oro: ningun commit pusheado a master debe romper el deployment. Si el codigo no esta terminado pero compila + pasa tests, viaja detras de un flag OFF. Si rompe, no sale.
Por que el registry esta exento
El registry es un repo de funciones reutilizables, no un servicio en produccion. Los cambios son atomicos por su propia naturaleza (una funcion = uno o dos archivos). Imponer TBD a cada fn add añadiria fricion sin ganancia: la BD se regenera con fn index, no hay deployment, no hay usuarios consumiendo master en directo.
Cuando aplica TBD
| Cambio | TBD obligatorio |
|---|---|
Funcion nueva en cpp/functions/, python/functions/, etc. |
NO — push directo a master |
Tipo nuevo en types/ |
NO |
Doc/regla en .claude/, docs/ |
NO |
Issue del registry mismo (dev/issues/) |
NO — issue cerrado y push directo |
App nueva o modificacion de app en apps/ o projects/*/apps/ |
SI |
Service desplegable (tag: service) |
SI |
Analysis en analysis/ o projects/*/analysis/ |
NO — son exploraciones efimeras |
Comandos
/git-branch— crea rama desde master actualizado (para apps)./git-push— tests → merge--no-ff→ push → eliminar rama (para apps).
Para el registry, push directo a master con commits atomicos.