Guía para contribuidores
Cómo sacar adelante tu primer pull request
El camino fiable más corto entre encontrar un issue apto para principiantes y conseguir que se fusione un pull request listo para revisión.
Empieza aquí
Elige tu punto de partida
Escoge el que mejor describa tu situación actual y sigue después las mismas fases de abajo.
Principiante total
Empieza por las herramientas, el vocabulario y un cambio que solo toque la documentación. Tu objetivo es completar un ciclo seguro de principio a fin.
Tu primer PR
Elige un issue pequeño y reciente, y mantén el diff acotado. Pide confirmación antes de empezar a programar.
Ya has contribuido antes
Usa la guía como lista de comprobación y dedica la mayor parte de tu energía a reproducir el problema y a probar la solución.
Fase 0
Instala las herramientas básicas
Solo necesitas las herramientas locales imprescindibles para clonar el repositorio, crear un branch, ejecutar las comprobaciones del proyecto y subir tu trabajo.
git
Git registra tu trabajo y permite a los mantenedores revisar exactamente qué ha cambiado.
git --versiongh
GitHub CLI te ayuda a hacer fork, clonar, autenticarte y abrir pull requests sin salir de la terminal.
gh auth login
gh repo fork OWNER/REPO --clone --remoteEditor
Usa un editor que pueda buscar en todo el repositorio, ejecutar formateadores y mostrar con claridad los archivos modificados.
code .Fase 1
Elige el issue adecuado
Un buen primer issue no es solo pequeño. Está vigente, se entiende y lo puede revisar alguien que ya mantiene el proyecto.
-
Resérvalo
Deja un comentario breve que mencione el issue exacto y pregunte si el alcance sigue teniendo sentido.
-
Lee las normas
Lee CONTRIBUTING, el README, los pull requests abiertos, los comandos de test y las notas de estilo de código antes de tocar nada.
-
Fork + branch
Crea tu propia copia y trabaja en un branch con el nombre de la tarea, no en main.
-
Prepara el entorno y reproduce
Instala las dependencias, reproduce el problema y anota el comando o la pantalla donde lo viste.
-
Entrega un diff mínimo
Cambia solo el código imprescindible. Evita las refactorizaciones de paso, las actualizaciones de dependencias y los cambios de formato que no vengan al caso.
-
Abre el PR
Explica qué ha cambiado, cómo lo has probado y qué límites tiene. Ponle fácil la primera lectura a quien revise.
Puntos de pausa
Señales de alarma antes de invertir más tiempo
Es mejor parar pronto que forzar un pull request que nadie puede revisar.
- No consigues ejecutar el proyecto en local después de seguir la instalación documentada.
- La solución exige adivinar cómo debe comportarse el producto sin la opinión de un mantenedor.
- El issue pide una funcionalidad grande, un rediseño, una migración o una decisión de arquitectura.
- Un mantenedor ha pedido que quienes contribuyen por primera vez no trabajen en esa zona.
Referencia
Glosario
- Fork
- Tu copia personal de un repositorio. Ahí subes tu branch antes de abrir un pull request.
- Branch
- Una línea de trabajo que avanza contigo. Usa un branch por issue para que tus cambios sigan siendo fáciles de revisar.
- Pull request
- Una solicitud para que los mantenedores revisen tu branch y lo fusionen en el repositorio del proyecto.
- Diff
- El conjunto de cambios más pequeño y con sentido que resuelve el issue sin limpiezas que no vienen al caso.
- CONTRIBUTING
- La lista de comprobación propia de cada proyecto sobre instalación, estilo, tests y lo que se espera de un pull request.
FAQ
Preguntas frecuentes sobre el primer PR
¿Y si el mantenedor lleva una semana sin responder?
Publica un único mensaje de seguimiento, conciso, con tu estado actual y una pregunta directa. Si sigue sin haber respuesta, elige otro issue en lugar de esperar indefinidamente.
¿Qué hago si falla la instalación?
Cuenta lo que has intentado, pega el error exacto, indica tu sistema operativo y las versiones de tus herramientas, y pregunta cuál sería el siguiente paso para depurarlo.
¿Mi primer PR puede ser solo de documentación?
Sí, si el repositorio acepta cambios de documentación. Una documentación más clara, ejemplos, erratas y enlaces rotos son contribuciones legítimas.