Pull Request: cómo contribuir a proyectos abiertos

¿Qué es una solicitud de extracción?

Una solicitud de extracción es una solicitud para incluir tus cambios en la rama principal del proyecto. Imagina que has encontrado un proyecto interesante de código abierto, has encontrado un error en él o se te ha ocurrido una mejora. No puedes cambiar directamente el código en el repositorio de otra persona, pero puedes proponer tus cambios a través de una PR.

El proceso es el siguiente: creas una copia del proyecto, haces cambios en tu versión y luego le pides al propietario del proyecto que «extraiga» (pull) tus cambios. De ahí el nombre: Pull Request.

Preparación para crear una Pull Request

Antes de empezar a hacer cambios, es importante prepararse adecuadamente.

Explora el proyecto

Tómate el tiempo para estudiar el proyecto en el que quieres contribuir. Lee el archivo README, estudia la estructura del código, mira las solicitudes de extracción existentes, tanto abiertas como ya cerradas. Esto ayudará a comprender el estilo de codificación del proyecto y los requisitos para los cambios.

Busca el archivo CONTRIBUTING

Muchos proyectos tienen un archivo CONTRIBUTING.md con reglas de contribución. Puede describir los requisitos del código, el proceso de creación de relaciones públicas, la configuración del entorno de desarrollo y otra información importante. Asegúrate de seguir estas reglas.

Comprueba los problemas

Antes de empezar, consulta la sección Problemas. Es posible que alguien ya esté trabajando en una tarea similar o que tu idea ya se haya discutido. Si quieres corregir un error o añadir una nueva función, es mejor crear primero un Issue y discutirlo con los encargados del mantenimiento.

Bifurcación y clonación del repositorio

El primer paso técnico es crear un fork del proyecto.

Crear una bifurcación

En GitHub, esto se hace con un solo botón "Fork" en la esquina superior derecha de la página del repositorio. Fork crea una copia del repositorio en tu cuenta, donde puedes experimentar libremente.

Clona el fork

Ahora clona tu fork en una máquina local:

git clone https:// github.com/tu-nombre-de-usuario/nombre-del-proyecto.git
cd название-проекта

Añadir upstream remote

Para sincronizar su fork con el repositorio original, agréguelo como upstream:

git remote add upstream https:// github.com/propietario/nombre-proyecto.git

Ahora tienes dos remotos: origin (tu fork) y upstream (repositorio original).

Creación de una rama para cambios

Nunca trabaje directamente en la rama principal o maestra. Crea siempre una rama separada para cada tarea:

git checkout -b fix-navigation-bug

El nombre de la rama debe ser descriptivo y reflejar la esencia de los cambios. Buenos ejemplos: feature-add-dark-mode, fix-login-error, docs-update-readme.

Modificaciones

Ahora puedes empezar a trabajar en el código.

Sigue el estilo del proyecto

Utiliza el mismo estilo de codificación que en el proyecto. Presta atención a la sangría, el nombre de las variables y la estructura de los archivos. Muchos proyectos usan linters y formateadores: ejecútalos antes de confirmar.

Haz commits atómicos

Un compromiso es un cambio lógico. Esto simplifica la revisión del código y facilita la reversión de los cambios si es necesario. Los mensajes de confirmación deben ser informativos:

git add .
git commit -m "Fixed a bug with navigation freezing when scrolling quickly"

Mensaje malo: "correcciones" o "arreglo". Bueno: describe exactamente lo que se ha hecho y por qué.

Escribe pruebas

Si el proyecto utiliza pruebas, asegúrate de añadir pruebas para tu código. También asegúrate de que todas las pruebas existentes pasen:

npm test
# o
pytest

Creación de una solicitud de extracción

Cuando los cambios estén listos, envía la rama a tu fork:

git push origin fix-navigation-bug

Ahora en GitHub en su tenedor aparecerá el botón "Comparar y solicitar extracción". Púlselo.

Complete la descripción de PR

Descripción Pull Request es tu oportunidad de explicar qué hiciste y por qué. Una buena descripción incluye:

Qué ha cambiado: breve descripción de los cambios.

Por qué: explicación del motivo de los cambios, enlace a Issue si lo hay.

Cómo probar: instrucciones para comprobar los cambios.

Capturas de pantalla: si los cambios afectan a la interfaz de usuario, añade capturas de pantalla del antes y el después.

Ejemplo de descripción:

# # Descripción
Исправлен баг с зависанием навигационного меню при быстрой прокрутке страницы.

# # Problemas relacionados
Closes #234

# # Cambios
- Добавлен debounce для обработчика скролла
- Оптимизирован расчёт позиции меню
- Добавлены unit-тесты для новой логики

# # Pruebas
1. Откройте страницу с длинным контентом
2. Быстро прокрутите вниз и вверх
3. Навигация должна плавно следовать за скроллом без задержек

Proceso de revisión de código

Después de crear el PR, comienza el proceso de revisión del código.

Prepárate para las correcciones

Los encargados del mantenimiento pueden solicitar cambios. Esto es normal y no significa que tu código sea malo. La revisión del código ayuda a mejorar la calidad y mantener la coherencia del proyecto.

Responde a los comentarios

Si el revisor ha dejado un comentario, respóndelo. Si estás de acuerdo con el comentario, haz los cambios. Si no estás de acuerdo, argumenta tu posición de manera educada y constructiva.

Realiza correcciones en la misma rama

Todos los commits adicionales en tu rama se añadirán automáticamente a la PR:

# hacemos correcciones
git add .
git commit -m "Code review comments taken into account: improved error handling"
git push origin fix-navigation-bug

Sincronización con la rama principal

Mientras se está revisando, la rama principal del proyecto puede avanzar. Es importante mantener su rama actualizada:

# obtenemos cambios del repositorio original
git fetch upstream

# cambiar a main
git checkout main

# actualizamos nuestro main
git merge upstream/main

# volvemos a nuestra rama
git checkout fix-navigation-bug

# incorporamos los cambios de main
git merge main

Si hay conflictos, resuélvelos y haz un commit.

Errores comunes y cómo evitarlos

Relaciones públicas demasiado grandes

Una solicitud de extracción debe resolver una tarea. Si has corregido un error y has añadido una nueva característica al mismo tiempo, divídelo en dos PR separadas. Las solicitudes de extracción grandes son difíciles de revisar y se aceptan con menos frecuencia.

Cambios en archivos de terceros

No cambies el formato o el estilo de los archivos que no estén relacionados con tu tarea. Esto crea ruido en las relaciones públicas y complica la revisión.

Falta de descripción

Es poco probable que se acepte un PR sin descripción o con la descripción "fijo". Tómese el tiempo para una descripción normal.

Ignorar CI/CD

Si el proyecto tiene configuradas comprobaciones automáticas (pruebas, linters), asegúrate de que se aprueben. No se considerarán las solicitudes de extracción con pruebas fallidas.

Después de aceptar el PR

Cuando se acepte tu PR y se incorpore a la rama principal, puedes eliminar tu rama de trabajo:

# eliminar localmente
git branch -d fix-navigation-bug

# eliminar en GitHub
git push origin --delete fix-navigation-bug

Actualiza tu fork:

git checkout main
git pull upstream main
git push origin main

Consejos para principiantes

Empieza poco a poco

No intentes hacer una gran refactorización de inmediato. Comienza con tareas simples: corregir errores tipográficos en la documentación, errores menores, agregar ejemplos. Esto te ayudará a familiarizarte con el proceso sin estrés innecesario.

Busca las etiquetas «good first issue»

Muchos proyectos marcan las tareas adecuadas para principiantes con etiquetas especiales: good first issue, beginner friendly, help wanted. Empieza por ellas.

No tengas miedo de hacer preguntas

Si algo no está claro, pregunta en Issue o en el chat del proyecto. La comunidad de código abierto suele ser amigable con los principiantes que intentan entenderlo.

Ten paciencia

Los encargados del mantenimiento suelen hacerlo en su tiempo libre. Es posible que tu PR no lo vea de inmediato, esto es normal. Si ha pasado más de una semana, puedes recordárselo educadamente.

Etiqueta en open-source

Sé amable

Comunícate con respeto, incluso si no están de acuerdo contigo. Recuerda que hay una persona viva al otro lado de la pantalla.

Acepta las críticas de forma constructiva

La revisión de código no es una crítica a ti como desarrollador, sino una forma de mejorar el código. Toma los comentarios como una oportunidad para aprender algo nuevo.

Agradece la ayuda

Si te ayudaron a resolver un problema o dedicaron tiempo a revisarlo, dales las gracias. Esto motiva a las personas a seguir invirtiendo tiempo en el proyecto.

Conclusión

Crear solicitudes de extracción es una habilidad que se desarrolla con la práctica. La primera PR puede parecer intimidante, pero con cada proceso posterior se vuelve más fácil y natural. No tengas miedo de cometer errores, así es como aprendemos.

Participar en proyectos de código abierto no solo mejora tus habilidades técnicas, sino que también abre las puertas a la comunidad de desarrolladores, te ayuda a crear un portafolio y a adquirir experiencia con proyectos reales. Empieza poco a poco, ten paciencia y presta atención a los detalles, y pronto te convertirás en un colaborador seguro de sí mismo.

Kodik es una plataforma educativa para desarrolladores principiantes, donde encontrarás cursos claros sobre programación en Python, JavaScript, HTML, CSS y otras tecnologías populares.

Únete a nuestro Canal de Telegram, donde compartimos artículos útiles, analizamos conceptos complejos en términos sencillos y ayudamos a los principiantes a dar sus primeros pasos en el mundo del desarrollo.