Blog

Como contribuir a WordPress | Parte 1

25 de octubre de 2026

En esta página

Versión revisada y actualizada en octubre de 2026 contra la documentación oficial (Core Handbook, Test Handbook, repositorios wordpress-develop y Gutenberg). Pensada para personas que hacen su primera contribución de código o de pruebas.

1. Por qué contribuir al Core

WordPress es software libre y se mantiene gracias a personas y empresas que dedican tiempo al proyecto. La iniciativa Five for the Future, propuesta por Matt Mullenweg en 2014, recomienda que las organizaciones que viven del ecosistema dediquen alrededor del 5% de sus recursos a WordPress. Hoy existe una página oficial (wordpress.org/five-for-the-future) donde empresas y personas registran su compromiso.

Para quien desarrolla temas o plugins, contribuir tiene beneficios concretos: entiendes mejor las APIs de las que depende tu trabajo, te enteras antes de los cambios que vienen en cada versión y detectas incompatibilidades antes de que lleguen a producción. Además, cada contribución aceptada queda reconocida con props en el mensaje del commit y en los créditos de la versión.

No todo es código. Puedes contribuir probando parches, escribiendo pruebas automatizadas, revisando accesibilidad o mejorando documentación. Esta guía cubre sobre todo código y pruebas, que son los caminos más comunes para empezar en Core y Gutenberg.

2. Checklist: lo que necesitas antes de empezar

Cuentas y comunicación

Cuenta en WordPress.org (sirve para Trac, Slack y los blogs Make).
Acceso al Slack oficial (make.wordpress.org/chat) y unirte a los canales #core, #core-test y #core-editor. Para dudas de accesibilidad, #accessibility.
Cuenta de GitHub vinculada a tu perfil de WordPress.org (Profile → Account & Security → Connections). Sin este vínculo tus pull requests no te darán props automáticamente.

Herramientas en tu equipo

Git instalado (y opcionalmente GitHub CLI). SVN solo si prefieres trabajar con el repositorio oficial de Subversion.
Node.js 24 y npm 11 (versiones que exige hoy wordpress-develop). Se recomienda nvm para cambiar de versión con nvm use.
Docker Desktop (o una alternativa compatible como OrbStack, Colima o Rancher Desktop) instalado y en ejecución.
Composer, necesario para PHPCS y para las pruebas PHP de Gutenberg.
Un editor con soporte para ESLint y PHP_CodeSniffer.

Repositorios

Fork y clon de github.com/WordPress/wordpress-develop (Core).
Fork y clon de github.com/WordPress/gutenberg (editor de bloques).
Entorno local levantado y funcionando al menos una vez (ver sección 3).

Lecturas mínimas

Core Contributor Handbook: make.wordpress.org/core/handbook.
WordPress Coding Standards (PHP, JavaScript, CSS, HTML y accesibilidad): developer.wordpress.org/coding-standards.
Guía de Trac: “How We Use Our Bug Tracker” en el Core Handbook.
AI Guidelines de WordPress, si vas a usar herramientas de IA: make.wordpress.org/ai/handbook/ai-guidelines/.
Para Gutenberg: docs/contributors/code/getting-started-with-code-contribution.md y testing-overview.md en el repositorio.
Test Handbook: make.wordpress.org/test/handbook.

3. Preparar el entorno local de Core

El repositorio de desarrollo (wordpress-develop) no es igual al WordPress que descargas para un sitio. Incluye las pruebas automatizadas, la configuración de herramientas de compilación y el código fuente en src/. El JavaScript y el CSS se generan con un proceso de compilación (Grunt, ejecutado a través de npm).

Opción recomendada: Git + entorno Docker incluido

git clone https://github.com/<tu-usuario>/wordpress-develop.git
cd wordpress-develop
npm install
npm run build:dev
npm run env:start
npm run env:install

El sitio queda disponible en http://localhost:8889 (usuario admin, contraseña password). Mientras trabajas, ejecuta npm run dev, que vigila los cambios y recompila automáticamente. Otros comandos útiles:

npm run env:cli — <comando>: ejecuta WP-CLI dentro del contenedor.
npm run env:stop, npm run env:restart: detener y reiniciar el entorno.
npm run env:reset: reinicia el entorno y borra la base de datos.

Con este entorno, el archivo wp-tests-config.php y la base de datos de pruebas se crean automáticamente. Por defecto el servidor sirve el directorio src/ (variable LOCAL_DIR=src en .env), que funciona correctamente después de npm run build:dev. Si quieres probar la versión compilada final, ejecuta npm run build y cambia LOCAL_DIR a build.

Si usas un Mac con Apple Silicon y una versión antigua de MySQL (5.7 o anterior) o MariaDB 5.5, el README indica crear un docker-compose.override.yml que fije la plataforma linux/amd64 para la base de datos.

Opción alternativa: SVN y servidor propio

SVN sigue siendo el sistema de control de versiones oficial (los committers suben los cambios ahí), y puedes trabajar con él:

svn co https://develop.svn.wordpress.org/trunk/ wordpress-develop
cd wordpress-develop
npm install
npm run build:dev

Si usas tu propio servidor (MAMP, Local, LAMP), copia wp-config-sample.php a wp-config.php en la raíz del repositorio y configura tu base de datos. Para las pruebas, copia wp-tests-config-sample.php a wp-tests-config.php y apúntalo a una base de datos distinta.

Advertencia: la suite de PHPUnit borra y recrea tablas (DROP TABLE / CREATE TABLE). Si wp-tests-config.php apunta a la base de datos de tu sitio de desarrollo, perderás todos sus datos.

Versión de PHP

Desde WordPress 7.0 (publicado en mayo de 2026) la versión mínima de PHP soportada es 7.4; la recomendada es 8.3 o superior. Si tu cambio toca PHP, asegúrate de no usar sintaxis que no exista en PHP 7.4 (por ejemplo, match, argumentos con nombre o tipos de unión, que llegaron en PHP 8.0). El entorno Docker permite cambiar la versión con la variable LOCAL_PHP en el archivo .env.

Herramienta / archivo	Comando o ubicación	Para qué sirve
Git / SVN	git clone del fork o svn co https://develop.svn.wordpress.org/trunk/	Obtener y sincronizar el código de trunk.
Node.js / npm	npm install	Dependencias JavaScript y herramientas de compilación.
Grunt (vía npm)	npm run build:dev, npm run build, npm run dev	Compilar, minificar y vigilar cambios. No hace falta instalar grunt-cli global; puedes usar npm run grunt — <tarea>.
Docker	npm run env:start	Servidor web, PHP y base de datos aislados.
wp-config.php	Raíz del repositorio	Configuración del sitio local (automática con Docker).
wp-tests-config.php	Raíz del repositorio	Base de datos aislada para PHPUnit (automática con Docker).

4. Encontrar tickets en Trac

El trabajo de Core se organiza en Trac (core.trac.wordpress.org). Cada error o mejora es un ticket con un número, componentes y palabras clave (keywords) que indican su estado. Antes de tocar código, lee “How We Use Our Bug Tracker” en el Core Handbook.

Reportes útiles para empezar:

Good First Bugs (keyword good-first-bug): tickets acotados, revisados por el equipo de Core como aptos para principiantes. La vista “Unclaimed” muestra los que nadie ha tomado. Una tarea habitual aquí es actualizar (“refrescar”) parches viejos que ya no aplican sobre trunk.
Needs Patch (needs-patch): el problema está confirmado pero falta una propuesta de código. Los tickets marcados para la próxima versión suelen recibir revisión más rápido.
Needs Unit Tests (needs-unit-tests): falta escribir pruebas que reproduzcan el error o validen el parche. Es una buena forma de aprender cómo funciona el código por dentro.
Needs Testing (needs-testing): ya hay un parche y hace falta alguien que lo pruebe y reporte el resultado. Ideal para la primera contribución.
Next Major / Next Minor Release: tickets del ciclo de la próxima versión, filtrables por flujo de trabajo (PHP, JavaScript, documentación, UI).
Dashboard de reportes (/reports/ y /tickets/): incluye vistas personales como tus parches pendientes y tus comentarios.

Si no tienes claro si un ticket sigue vigente o cuál es el mejor enfoque, comenta en el ticket o pregunta en #core en Slack. Es normal preguntar, y ahorra trabajo en una dirección equivocada.

Los cambios de Gutenberg no van por Trac: se gestionan como issues y pull requests en GitHub (github.com/WordPress/gutenberg). Las etiquetas Good First Issue y Needs Testing cumplen el mismo papel que en Trac.

5. Flujo de trabajo: de un ticket a un parche o pull request

Antes de empezar un ticket nuevo

Parte de un trunk limpio y actualizado, para que tu cambio no arrastre restos de otros tickets.

Con Git:

git status
git checkout trunk
git pull upstream trunk
git checkout -b 12345-descripcion-corta
npm run build:dev

Con SVN:

svn diff            # ver cambios locales
svn revert -R .     # descartar todos los cambios locales
svn up              # actualizar desde el servidor
npm run build:dev

Opción A: pull request en GitHub (la más usada hoy)

Haz tus cambios en una rama de tu fork de wordpress-develop y súbela.
Abre un pull request contra WordPress/wordpress-develop. En la descripción incluye la URL completa del ticket de Trac (por ejemplo, Trac ticket: https://core.trac.wordpress.org/ticket/12345) y marca la opción que permite a los mantenedores editar tu rama.
El PR aparecerá automáticamente en el ticket de Trac. Los comentarios generales del PR se sincronizan con Trac, pero no notifican a los suscriptores del ticket, así que deja también un comentario en Trac.

Los PR no se fusionan en GitHub: un committer aplica el cambio en SVN. Un PR sin ticket de Trac asociado no se considera.

Opción B: archivo de parche en Trac

Para aplicar un parche que otra persona subió a un ticket:

npm run grunt -- patch:12345

La tarea patch (del paquete grunt-patch-wordpress, creado por Aaron Jorbin) consulta Trac, lista los parches del ticket y aplica el que elijas. También acepta la URL de un parche o de un pull request de GitHub. La alternativa manual es descargar el archivo y ejecutar patch -p0 < 12345.diff desde la raíz; -p0 es necesario porque los parches de WordPress conservan las rutas desde la raíz del repositorio (src/, tests/).

Para crear tu parche:

svn diff > 12345.diff
# o, con Git:
git diff trunk --no-prefix > 12345.diff

Nombra el archivo con el número del ticket (12345.diff o 12345.patch). Si ya hay uno con ese nombre, Trac lo renombra (12345.2.diff). No incluyas archivos generados como JavaScript minificado o CSS RTL. Súbelo con Attach file en el ticket.

Actualizar el ticket

Después de subir el parche o abrir el PR, edita las palabras clave del ticket: quita needs-patch o needs-refresh y añade has-patch (y needs-testing si hace falta que alguien lo pruebe). Cerrar o resolver tickets lo hacen normalmente los committers, así que no uses las opciones de resolución salvo que te lo indiquen.

6. Agentes de IA y skills en el repositorio de Gutenberg

Gutenberg incluye archivos pensados para asistentes de programación con IA. Funcionan por “descubrimiento progresivo”: el agente carga solo el contexto que necesita para la tarea, en lugar de leer todo de una vez.

AGENTS.md en la raíz: reglas generales del proyecto y comandos básicos (instalación, build, lint, pruebas).
AGENTS.md por directorio: por ejemplo packages/components/AGENTS.md, que se lee solo al trabajar en esa carpeta.
Skills en .agents/skills/<nombre>/SKILL.md: procedimientos para tareas concretas. Hoy existen, entre otras, testing, defensive-data-design, package-runtime-compatibility y varias de design system.
Referencias dentro de cada skill (references/): documentos más largos que el agente lee solo cuando un paso lo pide. Por ejemplo, la skill de testing enlaza references/jest.md, php.md y e2e.md.
CLAUDE.md: contiene solo la línea @AGENTS.md, para que Claude Code use el mismo archivo.

El principio del proyecto es que las reglas viven en la documentación pública (por ejemplo, docs/contributors/code/) y los archivos para agentes solo apuntan a ella. Si una regla le sirve a un agente, también le sirve a una persona, y duplicarla hace que las copias se desincronicen.

Cada SKILL.md empieza con un encabezado YAML con name y description, donde la descripción dice cuándo usarla:

---
name: testing
description: Use when writing, running, or debugging tests in the Gutenberg repository.
---

La skill de testing de Gutenberg pide, entre otras cosas, no hacer pasar una prueba debilitándola (afirmaciones más laxas, esperas añadidas o casos omitidos sin avisarlo). Si creas o modificas una skill, ejecuta:

npm run agents:setup # regenera el catálogo de skills para los agentes soportados
npm run lint:md:docs # valida el formato Markdown de la documentación

Las reglas sobre cómo usar IA al contribuir, y cómo declararlo, están en la sección 8.

8. Recomendaciones para usar IA al contribuir

WordPress permite usar herramientas de IA (GitHub Copilot, Claude Code, Codex, ChatGPT y similares) para contribuir. Desde enero de 2026 existen unas pautas oficiales, las AI Guidelines del equipo de IA (make.wordpress.org/ai/handbook/ai-guidelines/), y las plantillas de pull request de wordpress-develop y Gutenberg incluyen una sección obligatoria “Use of AI Tools”. Las pautas son una versión inicial (v0) y pueden cambiar, así que revísalas antes de cada contribución importante.

Los cinco principios

Tú eres responsable. La IA puede ayudar, pero no es contribuyente. Todo lo que envías es tuyo, lo hayas escrito o lo haya generado una herramienta. Revisa la salida de la IA como revisarías código de una persona desconocida.
Transparencia. Declara el uso significativo de IA en la descripción del PR o en un comentario del ticket de Trac. Declararlo no se considera algo negativo; ayuda a quien revisa.
Licencia compatible. WordPress es GPLv2 o posterior. No uses herramientas cuyos términos impidan usar su salida bajo GPL, no uses IA para “reescribir” código con licencia incompatible y nunca borres cabeceras de licencia o atribuciones existentes.
También aplica a lo que no es código. Imágenes, capturas, documentación y materiales de Learn deben ser compatibles con GPL. Para medios, CC0 es aceptable; evita licencias con atribución, share-alike, no comercial o sin derivados.
Calidad antes que volumen. Las pautas rechazan explícitamente el “AI slop”: descripciones genéricas, grandes bloques de código sin revisar, APIs, hooks, funciones o tickets inventados, y código sobrediseñado. Los mantenedores pueden cerrar contribuciones que muestren poca intervención humana.

Cómo declarar el uso de IA

Completa la sección “Use of AI Tools” de la plantilla del PR. Si contribuyes con un parche en Trac, ponlo en tu comentario. El formato de ejemplo que propone la plantilla de Core es:

AI assistance: Yes
Tool(s): Claude Code
Model(s): <modelo usado>
Used for: Initial code skeleton and test suggestions; final implementation
and tests were reviewed and edited by me.

No hace falta declarar ayudas triviales, como sugerir el nombre de una variable o reordenar imports. Si se descubre un uso significativo que no declaraste, el merge o commit puede retrasarse o bloquearse.

Usos recomendados

Entender código que no conoces: pedir que te explique una función, un hook o el flujo de un componente antes de cambiarlo.
Proponer un esqueleto de código, refactors o enfoques alternativos que luego evalúas tú.
Generar boilerplate que puedas validar: estructura de pruebas, data providers, fixtures.
Proponer casos límite para las pruebas y convertir pasos manuales en pruebas automatizadas.
Redactar borradores de comentarios, documentación en línea, dev notes o descripciones de PR, que después corriges.
Traducir textos, siempre con revisión de una persona que domine el idioma.
Usar los archivos AGENTS.md y las skills de Gutenberg (sección 7), que ya le dan al agente los comandos y reglas del proyecto.

Qué evitar

Enviar cambios que no entiendes del todo.
Dependencias, patrones o APIs que no siguen los estándares de WordPress.
Pedir “el mismo código que la librería X” o aceptar salida que se parezca a un proyecto conocido con licencia incompatible.
Pruebas que dependen de APIs imaginarias o de servicios externos inestables.
Enlaces, citas o números de ticket que no hayas comprobado.
Reportes de errores generados sin reproducir el problema en una instalación real.
Usar la IA como única revisión: la revisión humana es obligatoria.

Checklist antes de enviar una contribución hecha con ayuda de IA

Leí cada línea y eliminé lo que no puedo explicar.
El código cumple los estándares de código, seguridad y rendimiento de WordPress, y la versión mínima de PHP (7.4).
Comprobé que las funciones, hooks y opciones que se usan existen de verdad.
Añadí o actualicé pruebas, y revisé los nombres y casos que propuso la IA.
Ejecuté las suites relevantes e incluí los comandos en la descripción del PR.
El PR es pequeño, con commits claros, y la descripción refleja lo que hice y probé de verdad.
Completé la sección “Use of AI Tools”.
Puedo explicar en la revisión qué generó la IA y qué escribí yo.

Consejos prácticos con agentes de programación

Dale contexto concreto: el número del ticket, el archivo afectado y el comportamiento esperado. Pídele que primero lea el código y te proponga un plan antes de editar.
Pídele que escriba primero una prueba que falle y reproduzca el error; así compruebas que entendió el problema.
En Gutenberg, mantén las pruebas E2E en modo headless cuando las ejecute un agente: las opciones interactivas como –ui o –headed dejan la sesión bloqueada esperando.
No le dejes publicar por ti: comentarios en Trac, PRs y respuestas a revisiones deben salir de ti, con tus palabras y tu criterio.
Si no estás seguro de si una herramienta o su salida es compatible con GPL, pregunta en #core-ai o #core en Slack antes de enviar.

9. Cómo contribuir con pruebas a Core y Gutenberg

Hay dos formas de contribuir con pruebas, y las dos son muy valoradas: probar manualmente parches y PRs de otras personas, y escribir pruebas automatizadas.

Probar parches y PRs manualmente

Es la forma más rápida de hacer una primera contribución útil, y no necesitas escribir código.

Busca tickets con needs-testing en Trac, o PRs con la etiqueta Needs Testing en Gutenberg.
Lee el ticket o PR y sus instrucciones de prueba. Reproduce el error primero sin el parche, para confirmar que existe.
Aplica el cambio con una de las opciones descritas abajo.
Comprueba que el parche resuelve el problema, que no rompe nada cercano y que se comporta bien en distintos navegadores, temas o con teclado y lector de pantalla si aplica.
Publica un reporte en el ticket o PR. El Test Handbook ofrece una plantilla (“Patch Testing”) y el plugin Test Reports, que rellena los datos del entorno. Un reporte incluye: parche o PR probado, entorno (sistema operativo, navegador, servidor, versión de PHP y WordPress, tema, plugins), pasos seguidos, resultado esperado y obtenido, y capturas o vídeo si ayudan.

Formas de aplicar el cambio que vas a probar:

WordPress Playground: si el ticket tiene un PR, el bot deja un enlace de Playground en el PR que crea un sitio desechable con el cambio aplicado. También puedes usar playground.wordpress.net con las opciones para probar PRs de Core o de Gutenberg. No requiere instalar nada.
Entorno local de Core: npm run grunt — patch:12345 o la URL del PR.
Gutenberg local: gh pr checkout <número>, luego npm install y npm run build.

Si el parche funciona, dilo claramente. Si falla o ya no aplica sobre trunk, explica qué pasó y, en Trac, sugiere needs-refresh. Las dudas sobre pruebas se resuelven en #core-test.

10. Cierre

WordPress impulsa más del 40% de los sitios web, y cada cambio en Core o Gutenberg llega a millones de instalaciones. Por eso se valora tanto el trabajo cuidadoso: un parche bien probado, una prueba que evita una regresión o un componente usable con teclado. Un buen orden para empezar es: prepara el entorno, prueba un parche con needs-testing, escribe una prueba para un ticket con needs-unit-tests y después toma un good-first-bug. Si te atascas, pregunta en Slack.

Fuentes

Gutenberg: AGENTS.md, .agents/skills/ y docs/contributors/code/testing-overview.md en github.com/WordPress/gutenberg

Core Contributor Handbook: make.wordpress.org/core/handbook

README de wordpress-develop: github.com/WordPress/wordpress-develop

Working with Patches: make.wordpress.org/core/handbook/tutorials/working-with-patches/

GitHub Pull Requests for Code Review: make.wordpress.org/core/handbook/contribute/git/github-pull-requests-for-code-review/

Dropping support for PHP 7.2 and 7.3 (enero 2026): make.wordpress.org/core/2026/01/09/dropping-support-for-php-7-2-and-7-3/

AI Guidelines (equipo de IA de WordPress, enero 2026): make.wordpress.org/ai/handbook/ai-guidelines/

Plantilla de pull request de wordpress-develop: github.com/WordPress/wordpress-develop/blob/trunk/.github/pull_request_template.md

Accessibility Coding Standards: developer.wordpress.org/coding-standards/wordpress-coding-standards/accessibility/

WebAIM Screen Reader User Survey #10: webaim.org/projects/screenreadersurvey10/

Test Handbook (Patch Testing, Test Core Tickets with Playground, Test Gutenberg with Playground): make.wordpress.org/test/handbook