Convoca v3.0 — Marco de versión estable¶

Fecha: 2026-08-07 Estado: APROBADO para implementación Precedente: G1 validación automatizada ✅ · G2 tests (en curso) · G3 calidad ✅ · G4 hardening ✅

1. Congelación de API pública (API Freeze)¶

A partir de v2.7.0 y hasta v3.0.0, la API pública queda congelada: no se añaden ni eliminan elementos sin aprobación explícita y bump de versión menor.

API pública congelada¶

Reglas del freeze¶

1. Un elemento de la API congelada no se elimina ni renombra sin:
2. Deprecación explícita (2 versiones menores de aviso)
3. Migración automática si hay datos afectados
4. Las adiciones son libres (no rompen nada existente)
5. Los cambios de comportamiento de endpoints REST requieren bump mayor

2. Política de deprecaciones¶

Ciclo de vida de un elemento público¶

ACTIVO → DEPRECADO (vX) → OBSOLETO (vX+1) → ELIMINADO (vX+2 o v3.0)

Ejemplo de deprecación (hook)¶

// Antes: convoca_members_estado_changed (solo 2 args)
// Ahora: convoca_members_state_changed (3 args, nombre normalizado)
if ( has_action( 'convoca_members_estado_changed' ) ) {
    do_action_deprecated( 'convoca_members_estado_changed', array( $id, $to ), '2.7.0', 'convoca_members_state_changed' );
}
do_action( 'convoca_members_state_changed', $id, $to, $from );

3. Versionado semántico (SemVer estricto)¶

MAJOR.MINOR.PATCH   — ej: 3.0.0, 2.7.1

Reglas de sincronización (ya en vigor)¶

• Header del plugin = constante = Stable tag = CHANGELOG = wiki
• Verificado por health check (check de versión)
• Todos los plugins del ecosistema comparten el bump cuando hay cambio de integración

4. Roadmap v3.0¶

Bloqueante (previo al freeze definitivo)¶

• G1: Health check automatizado (88 checks)
• G3: Código muerto eliminado (10 clases + 3 SQL legacy)
• G4: Hardening (QR local, advisories 0, nonces verificados)
• G2: PHPUnit CI verde en los 8 plugins (bootstrap WP test suite)

v3.0.0¶

• Congelar API: publicar API-REFERENCE.md (inventario completo)
• Eliminar todos los elementos deprecados acumulados (si hay)
• Migración automática única: upgrade_to_3_0_0 en cada plugin
• Guía para desarrolladores externos publicada en wiki
• Test suite completa en CI (PHPUnit + Playwright + health check)

Post-v3.0 (3.1+)¶

• Versiones independientes por plugin (semver por componente)
• Compatibilidad declarada con versiones de WP (5.9-6.x)
• Hooks de integración adicionales según demanda de la comunidad

5. Migraciones automáticas¶

Patrón (ya usado en Upgrade_Manager)¶

$current = get_option( 'convoca_<plugin>_version', '0.0.0' );
if ( version_compare( $current, '3.0.0', '<' ) ) {
    // migrate 2.x → 3.0.0
    upgrade_to_3_0_0();
    update_option( 'convoca_<plugin>_version', '3.0.0' );
}

Migraciones planificadas para 3.0¶

Garantía¶

• Las migraciones son idempotentes (ejecutables N veces sin daño)
• Se ejecutan en transacción SQL cuando hay cambios de BD
• Verificadas por el health check (versión + estado de tablas)

6. Compatibilidad entre plugins¶

Matriz de dependencias declarada¶

Reglas¶

1. Activación ordenada: el plugin requiere core activo (ya implementado, con wp_die amigable)
2. Integración por hooks: los plugins se comunican SOLO vía hooks/REST públicos (nunca clases privadas de otro plugin)
3. Degradación elegante: si un dependiente débil no está activo, el feature se oculta sin errores (patrón class_exists/function_exists)
4. Verificación: health check valida los 6 namespaces REST + flujos pagados en cada ejecución

7. Guía para desarrolladores externos¶

Publicada en wiki (docs.getconvoca.app)¶

• Arquitectura: theme 100% presentacional, API solo en plugins
• REST: lista de endpoints por namespace con permisos
• Hooks: HOOKS.md regenerado desde el código por plugin
• Shortcodes: tabla con parámetros y ejemplos
• Extensiones: patrón para añadir providers (ej: Email_Verifier, canales publisher)

Principios para contribuidores¶

1. Nunca tocar el theme para lógica de negocio (solo presentación)
2. Prefijos obligatorios: convoca_* (funciones/hooks/opciones), _convoca_* (metadatos)
3. Los hooks se documentan en el código (generan HOOKS.md automáticamente)
4. Toda funcionalidad nueva requiere: código + test (health check o PHPUnit) + wiki
5. Cambio de API → deprecación (2 versiones) antes de eliminar

Setup de desarrollo¶

# Clonar ecosistema
git clone [email protected]:josecarlosnieto91/convoca-core.git
git clone [email protected]:josecarlosnieto91/convoca-members.git
# ... (8 repos)
# PHPUnit
composer install
vendor/bin/phpunit
# Health check contra demo
git clone [email protected]:josecarlosnieto91/convoca-health-check.git
./bin/convoca-health --ssh=andromeda --path=/var/www/demo.getconvoca.app/public

8. Checklist de transición a v3.0¶

• G2 completado (PHPUnit CI verde)
• Publicar API-REFERENCE.md (inventario completo de la API congelada)
• Publicar guía de desarrolladores en wiki
• Migraciones upgrade_to_3_0_0 implementadas y probadas
• Health check incluye check de versión y tablas
• CHANGELOG v3.0.0 redactado
• Etiqueta v3.0.0 en los 8 repos + release notes

9. Riesgos y decisiones pendientes¶