fswp-maintainer

FSWP Maintainer

Fundamental (siempre aplicado): fswp-developer/references/lean-coding.md (escribe menos, reutiliza primero), fswp-developer/references/coding-standards.md (estándares de codificación, documentación, i18n, accesibilidad), y fswp-security-engineer (entrada, salida, autorización).

El código existente es la especificación. Ejecuta un brief de cambio aprobado por fswp-architect (que ya ejecutó detect_wp_project.py). Sigue las convenciones propias del proyecto a menos que no sean seguras; las plantillas internas son para proyectos nuevos, no para reescribir el estilo de otra persona.

Modo A: Actualizar un plugin o tema existente

1. Lee primero. Lee los archivos que toca el cambio, sus invocadores y sus pruebas. Anota el prefijo, la nomenclatura, el estilo de manejo de errores, y cómo se almacenan los ajustes y los datos.
2. Reproduce. Para un error, anota los pasos y el resultado observado; confirma el fallo antes de cambiar nada. Para una funcionalidad, indica la verificación de aceptación.
3. El cambio más pequeño que funciona. Corrige la causa en el código compartido, no en un solo sitio de llamada. No reformatees código no tocado; los diffs ruidosos ocultan cambios reales y rompen el seguimiento (blame).
4. Protege la superficie pública. Los nombres de hooks, funciones y clases, las claves de opciones y meta, las rutas y formas REST, los atributos de shortcodes y las sobrescrituras de plantillas son contratos. Para cambiar uno, primero desaproba: mantén el antiguo funcionando, llama a _deprecated_function() / _deprecated_hook() (o _deprecated_argument()), documenta el reemplazo, y no lo elimines hasta una versión mayor posterior.
5. Ruta de actualización. Si los datos o el esquema cambian: incrementa una opción de versión almacenada, ejecuta una migración al cargar (no solo al activar), hazla idempotente, y prueba la actualización desde los datos de la versión anterior sin reactivar.
6. Compatibilidad. Respeta los valores declarados Requires at least y Requires PHP; protege las funciones más nuevas con function_exists()/comprobaciones de versión, o aumenta el mínimo deliberadamente y menciónalo.
7. Revisión de seguridad sobre el código tocado (fswp-security-engineer): una corrección de errores no debe agregar un nuevo punto de entrada sin autorización, nonce, saneamiento y escape.
8. Versión y registro de cambios. Corrección = parche, funcionalidad = menor, cambio disruptivo = mayor. Actualiza la versión del plugin/tema, la constante, la etiqueta Stable tag en readme.txt y el registro de cambios de forma conjunta.
9. Entrega como un parche o diff para el repositorio en el que trabaja el usuario, o un zip cuando desplieguen archivos. Incluye el resultado de la lista de verificación de paridad.

Temas: prefiere un tema hijo o cambios en theme.json/variaciones de estilo en lugar de editar un tema padre que recibe actualizaciones. Las ediciones directas a un tema padre, y las ediciones a archivos de plugins de terceros, se pierden en la siguiente actualización.

Modo B: Complemento para un producto que no posees

Un complemento es un plugin separado (o una pequeña capa de tema) que extiende un anfitrión. Estructúralo con fswp-plugin-developer (pasos 1-3 y 8), luego aplica estas reglas:

1. Extiende a través de la API pública del anfitrión. Usa acciones, filtros, registros y rutas REST documentados. Nunca edites archivos del anfitrión y evita llamar a elementos internos marcados como privados o no documentados; si es necesario, aísla la llamada en una clase adaptadora y protégela.
2. Declara la dependencia. Agrega Requires Plugins: host-slug al encabezado cuando el anfitrión esté en WordPress.org (WordPress 6.5 y posteriores lo exige). También detecta en tiempo de ejecución: verifica una clase, función o constante, o una constante de versión, no la ruta del archivo del plugin.
3. Carga en el momento adecuado. Inicializa en plugins_loaded (o en el hook propio de preparación del anfitrión) después de confirmar que el anfitrión existe; regístrate en los hooks de registro del anfitrión, no antes.
4. Falla de forma silenciosa y clara. Si el anfitrión falta o es demasiado antiguo: no hagas nada más, muestra un aviso de administración explicando lo que se necesita, y nunca causes un error fatal.
5. Rango de versiones. Indica las versiones compatibles del anfitrión en el readme y en el plan. Prueba la más baja y la más nueva compatible.
6. Declaraciones de compatibilidad. Algunos anfitriones requieren que declares soporte de funcionalidades. Ejemplo: WooCommerce espera que las extensiones declaren compatibilidad con High-Performance Order Storage y el carrito y pago basados en bloques. Lee la documentación del desarrollador del anfitrión para las llamadas de declaración actuales.
7. Propiedad de los datos. Almacena tus datos bajo tu propio prefijo; no escribas en las tablas u opciones del anfitrión. La desinstalación elimina solo tus datos.
8. Licencias y nombres. Sigue las reglas de marca y nombre comercial del anfitrión para los nombres; usa un estilo descriptivo "para X" en lugar de sugerir que es oficial.

Verificar

Entrega a fswp-qa-engineer con la lista de paridad del brief de cambio y la tabla de compatibilidad como fuente del escenario. references/safe-change-checklist.md es la lista rápida previa a la entrega.