Si hay algún proyecto en GitHub en el cual deseas colaborar para corregir un error o para sugerir nuevas características, esta completa guía es lo que necesitas saber antes de comenzar a ser colaborador de proyectos en GitHub.
Para empezar, para quienes aún no lo sepan, GitHub es una manera muy efectiva de colaborar en proyectos de programación. Ya que te proporciona un lugar para que cualquier persona con una conexión a Internet pueda tener un medio para poder compartir código con el mundo de forma gratuita (además de las excelentes herramientas que ofrece GitHub cómo las de inspección de código y visualización del historial de «commits«). GitHub ha sido adoptado por muchos proyectos grandes de código abierto (Open Source) como su lugar principal para la colaboración y la contribución.
Pero, ¿cómo te puedes unir y contribuir a un proyecto? Claro, primero debes saber cómo usar Git para registrar (track) cambios en los archivos y subir (push) esos archivos a un servidor. Pero además hay grandes beneficios que obtienes al involucrarse en proyectos grandes de código abierto y GitHub es sin duda el mejor lugar para empezar. En esta guía, vamos a hablar de algunas reglas para colaborar en proyectos de código abierto, y te darán el conocimiento y la intuición que necesitas para involucrarte.
Comienza con pequeñas contribuciones
Una de las cosas más importantes para entender cuando empezar con la colaboración en proyectos de código abierto es reconocer tu papel. A menudo, hay un montón de cosas que tú como desarrollador puedes hacer que no implican ser un programador muy inteligente. De hecho, el miedo de ser un mal programador es a menudo una razón por qué las personas no se involucran en proyectos de código abierto, para empezar. No tengas miedo de empezar poco a poco: en lugar de tratar de arreglar un error importante o reescribir un módulo completo, trata de encontrar cosas como las deficiencias de documentación o pruebas entre dispositivos y parches, o incluso simples errores de sintaxis y gramática (como este en GitHub del usuario mzgol).
Este tipo de tareas son una buena manera de abrirte las puertas como un colaborador del proyecto, sin tratar de tomar más de lo que puedes manejar. Inscríbete al sitio CodeTriage para conseguir Problemas en proyectos de GitHub que son enviados automáticamente a tu bandeja de entrada. Si llega algún problema a tu bandeja de entrada y te sientes seguro de que puedes asumir, trabajar en él y enviar un pull request. (Más abajo en este artículo hablaremos de cómo hacerlo).
Aprende el ecosistema del proyecto
La mayoría de los proyectos de código abierto han adoptado un conjunto de convenciones, cómo un esfuerzo para hacer más eficaz la colaboración. Esto puede incluir un vocabulario específico, una forma de contribuir y dar formato a mensajes de los commits, un cierto ritmo de colaborar que los contribuyentes han aceptado, o incluso normas sintácticas que se han establecido. Antes de tratar de involucrarte con un proyecto, lee todos los documentos relacionados con estas cosas. Por ejemplo, GitHub ha estandarizado un archivo llamado CONTRIBUTING.md (échale un vistazo a las directrices para involucrarse con jQuery, y tómalo cómo ejemplo). Estas guías son mantenidas por las personas que también mantienen el código base y la rama principal.
Otra forma de entender el ecosistema de un proyecto es simplemente mirar el código base existente y el git log. Leyendo los mensajes de los commits y buscando el estilo del código se puede decir mucho acerca de un proyecto. Lee la documentación del proyecto, y adopta el vocabulario usado para que tus contribuciones mantengan la continuidad y tengan una voz similar.
Una vez que eres parte del ecosistema cultural del proyecto, ¿cómo contribuyes realmente con código?
El flujo de trabajo de los «pull-request» para contribuir con código
El flujo de trabajo para contribuir código puede parecer intimidante al principio. Pero la cosa más importante que debes recordar es seguir las pautas y normas señaladas por el proyecto en el que estás trabajando (como ya hemos comentado). El flujo de trabajo general que soporta GitHub es bastante simple.
- Haz un fork del repositorio a tu propia cuenta en GitHub.
- Clona el repositorio de tu cuenta a tu computadora local.
- Crea una rama nueva con el tema en cuestion y haz los cambios.
- Haz un push de tu rama hacia tu fork.
- Usa el visor de diferencias (Diff Viewer) de GitHub para crear un pull request a través de una discusión.
- Haz los cambios solicitados.
- El pull request es combinado (por lo general en la rama master) y la rama del tema se elimina del upstream en el repositorio de destino.
Dentro de este flujo de trabajo, puedes ver muchas variaciones de un determinado proyecto a otro. Por ejemplo, los estándares para nombrar ramas temáticas varían. Algunos proyectos utilizan los estándares como bug_345, donde 345 es el ID # del issue en GitHub que ha sido presentado. Algunos proyectos prefieren mensajes de commit más cortos que otros.
Ahora te presento la explicación de los comandos de cada uno de los 7 pasos del flujo de trabajo para contribuir con código.
– Paso 1: Haz un fork
En el sitio de Github en la página del repositorio presiona el botón Fork.
Cómo hacer un fork
Haciendo el fork (bifurcando)
– Paso 2: Clona el repositorio
Clona el repositorio usando la URL que está en el sidebar:
git@github.com:carlosleopoldo/bootstrap.git
Clonando el repo en GitHub
– Paso 3: Añade el upstream remoto
Cambiate dentro de la carpeta del repositorio clonado y después en este punto, puedes añadir el upstream remoto:
cd bootstrap
git remote add upstream git@github.com:twbs/bootstrap.git
Esto ahora te permitirá que hacer un pull de cambios del origen localmente y combinarlos, así:
git fetch upstream
git merge upstream/master
– Paso 4: Crea una nueva rama y cámbiate a ella con checkout
Sin embargo, antes de hacer tus propios cambios, crea una rama para el tema:
git checkout -b mejora_345
– Paso 5: Haz un commit
Ahora, puedes hacer tus cambios y crear un commit que registre solamente esos cambios.
git commit -am "Se ha agregado una carita feliz a la documentación."
– Paso 6: Haz un push
Enseguida, haz un push de la rama tema hacia tu propio fork del proyecto.
git push origin mejora_345
– Paso 7: Crea un Pull Request
Por último, se creará un pull request. En primer lugar, ve a tu fork del repositorio. Es posible que veas un mensaje que dice «your recently pushed branches«, y si es así, puedes elegir «Compare and Pull Request«. De lo contrario, puedes seleccionar tu rama en el menú desplegable, y luego hacer clic en «Pull Request» o «Compare» en la parte superior derecha del repositorio.
Creando un pull request usando el botón «Compare and Pull Request«
Creando un pull request usando el menú desplegable de las ramas.
Cualquiera de ellos te llevará a una página donde puede crear un pull request y hacer comentarios sobre la solicitud. Esta página también incluye una visualización de los cambios realizados. Esto hace que sea fácil para el administrador del proyecto ver lo que has hecho y tomar decisiones fáciles sobre si es apropiado combinar tu commit. Si tienes alguna duda, puedes pedir ayuda en los comentarios, sino quedaste conforme también puedes pedir que se limpe tu solicitud de extracción y vuelvas a enviar, y posteriormente cerrar la solicitud de extracción.
Debes tener en cuenta que es muy importante que muestres a los administradores de un proyecto pleno respeto, después de todo, siempre se puede utilizar la versión bifurcada del código, y si deciden no aceptar tu pull request, es porque tienen la posición de hacerlo. Recuerda que, de acuerdo con Zach Holman, un empleado de Github, en su artículo «Cómo GitHub usa GitHub para contruir GitHub«, los pull requests son conversaciones. Esta es la forma en que deben ser tratadas, en vez de esperar que tu commit sea aceptado, así que solamente debes esperar que se abra una la conversación sobre el código que escribiste.
Los Issues de Github + Pull Request = el Zen de la administración de proyectos
GitHub ofrece en cada repositorio una sección llamada Issues, que es una manera robusta de crear conversaciones documentados, interactivas, y automatizadas acerca de los errores o las características de un determinado proyecto. Mientras que los issues se pueden desactivar, están habilitados de forma predeterminada. Hay un montón de características impresionantes que issues ha incorporado, pero una de las características más importantes es su integración con los pull request. Un usuario puede hacer referencia a un tema en los issues en su mensaje de commit con sólo incluir la identificación numérica del issue en el mensaje de confirmación. Por ejemplo:
git commit -am "Agregando un encabezado; repara el problema #3"
Este mensaje de confirmación marcará automáticamente el issue número 3 como cerrado en que se acepta el pull request asociado. Este tipo de automatización hace de GitHub una maravillosa herramienta para la gestión de proyectos de programación.
Busca canales secundarios para colaborar
No te dejes atrapar pensando que la única forma en que puedes contribuir es a través de un pull request. A menudo, los grandes proyectos de código abierto se benefician de diferentes tipos de trabajo colaborativo. Por ejemplo, un proyecto como Ruby on Rails fue notorio porque su comunidad, podía responder a las preguntas en los foros y en los chats de IRC para ayudar a crear conocimiento sobre el framework, y también ayudar a impulsar la futura orientación del framework al hablar de las ideas y descubrir errores.
Estos canales de colaboración lo general se abren como entornos de apoyo como se ha mencionado antes, tales como foros y salas de chat. También puede haber listas de correo electrónico, reuniones (en el mundo real), o conferencias que ayudan a definir la dirección del proyecto y crear una ciudad viva, la comunidad productiva en torno al proyecto. Sin este tipo de comunidad, las solicitudes de extracción son mucho menos eficaces.
Tu actitud es muy importante
Recuerda, el código abierto es impulsado por personas que tienen la actitud de intercambiar conocimientos y crear inteligencia colaborativa es un esfuerzo que vale la pena. Tu participación en estos proyectos será más eficaz si te acercas a un proyecto determinado con una actitud inquisitiva que pregunta «¿cómo puedo ayudar?» En lugar de una actitud cerrada, que dice: «Yo voy a ayudar en lo que quiero.» La gente en el mundo del código abierto quieren trabajar con personas que realmente están impulsadas para ayudar a otras.
Conclusión
Si estás interesado en participar en un proyecto de código abierto, ¡excelente! Recuerda, si te acercas al proyecto con la actitud correcta y empiezas poco a poco, podrás ver tu nombre en un la lista de los Pull Requests fusionados con el proyecto, y lo podrán ver personas de todo el mundo que lo utilizan todos los días, esto es bueno para mejorar tu reputación cómo desarrollador. Tómate el tiempo para aprender sobre el proyecto y las personas que están involucradas con el proyecto. Desarrolla un interés genuino en ayudar al mejorar el proyecto. El poder de GitHub y el mundo de código abierto sigue creciendo todos los días, así que comienzan a colaborar con otros desarrolladores, para que puedas ser parte de ese mundo.