GitHub
April 15, 2022

5 consejos para mejorar tu proyecto en GitHub

En los √ļltimos a√Īos, GitHub se ha convertido en el sitio donde se encuentran los proyectos OpenSource m√°s populares (y siendo de Microsoft, quien lo hubiera dicho).

Ya porque creaste una herramienta genial y quieres que sea libre y mantenida con ayuda de los miembros de la comunidad o quieres usarla como portafolio para encontrar trabajo, debes trabajar en mejorarla y hacerla m√°s digerible a los nuevos usuarios y/o contribuidores.

Recordemos que los controles de versiones surgieron para ayudar a varios a contribuir en un mismo proyecto. Si no sigues un est√°ndar y no ayudas a comprender de que va ese repositorio, pueden que los devs se sientan un poco perdidos por lo que decidan irse. Aqu√≠ te dejo 5 recomendaciones para mejorar la visiblidad de tu proyecto e incrementar las posibilidades de que te contraten o te hagan un Pull Request ūüėČ.

Pero, ¬Ņy esto qu√© es? ¬°READ ME!

Personaje Mauricio de la serie humorística AIda. Tomado de tenor.

Es, literalmente, la primera pregunta que se hace la persona que abre tu repositorio por primera vez. ¬ŅDe qu√© va este proyecto? ¬ŅQu√© tecnolog√≠as usa? ¬ŅC√≥mo puedo ejecutarlo en mi m√°quina si lo clono?

Es para eso que existen los READMEs. Si en tu repositorio local creas un fichero llamado README.md, GitHub se encargará de mostrar el contenido que pongas ahí es por eso que este debe ser una de los primeros ficheros que debes crear. Es lo primero que se lee.

Proyecto de código abierto Threadly https://github.com/ragnarok22/threadly

Este fichero es el encargado de contener la información básica y necesaria de tu proyecto. Entre la información que contiene debería estar lo siguiente:

  1. Nombre del proyecto: Es el identificativo de tu proyecto. Todo proyecto debe tener un nombre.
  2. Descripción corta: Es una descripción corta de que es lo que hace tu software.
  3. Badges o insignias: Son etiquetas cortas y visuales que muestran información relevante de tu proyecto como son: licencia, coverage, versión del lenguaje de programación que usa, entre otros. Con esta herramienta es muy fácil de hacerlas.
  4. Instalaci√≥n: Despu√©s que la persona clone el proyecto debe instalar dependencias y levantar el proyecto localmente. ¬ŅC√≥mo lo hace? Aunque est√©s usando un est√°ndar del lenguaje de programaci√≥n que uses (yarn, npm para Node por ejemplo) debes de ponerlo. Quiz√°s la persona que lo est√° levantando nunca ha hecho esto o no conoce el proceso. Debes guiarlo paso a paso para que pueda instalarlo y ejecutarlo localmente.
  5. Despliegue: Si es de licencia abierta y la persona puede desplegarlo c√≥mo desee y d√≥nde desee, debes explicarle como compilarlo o desplegarlo ūüöÄ.
  6. Cómo contribuir: Cada proyecto tiene estándares, metodologías y ciclos de vida. La persona que quiera contribuir debe seguir estas normas para que, no importa la cantidad de colaboradores que tenga, el código se mantenga limpio y uniforme.

Además del README, GitHub recomienda agregar un código de conducta, una licencia (Aunque sea Software Libre y Open Source debe tener una licencia) y una plantilla para los issues, así tendrán una guía de cómo deben reportar los bugs o hacer sugerencias. Aquí te dejo un editor de README realmente genial que te puede hacer este proceso un poco más sencillo.

Probando, probando... 1, 2, 3

Bart Simpson. Tomado de tenor.

No me pongas carita. Hay que hacerlas. Las pruebas son una parte importante del software. No importa que ejecutes tu programa, des click y funcione, las pruebas te ayudan a documentar el comportamiento que deseas y el que no. Leyendo los tests ya tenemos una idea de que es lo que se espera de una parte del código y validamos que este funcione bien. Claro, tener tests no asegura tener el 100% de los casos cubiertos pero si nos cubre de todos los herrores que podamos imaginar.

Cada framework, librería o lenguaje de programación tiene su propia forma de escribir tests e incluso algunas librerías que te ayudan a realizarlo. Te toca leerlas y aprender.

Hay 2 tipos de tests que debes realizar: tests unitarios y tests de integración.

Los tests unitarios son aquellos que pruebas una fracción de tu código. Un ejemplo de esto es una función, dónde le das ciertos parámetros y esperas determinada salida. Si no es así, pues es tiempo de arreglar esa función.

Los tests de integración son aquellos que prueban como funcionan determinada acción en su conjunto. Una vez que realizas los tests unitarios y pruebas que cada pieza funciona bien por separado, es momento de probar que funcionan bien en conjunto. Muy importante si piensas agregar integración continua (Continous integration, CI).

Estos 2 tipos de tests son lo más usados y, en mi opinión, los más importantes a la hora de trabajar en equipos.

Documenta tu código

tomado de tenor

Ya tengo el README, ¬Ņpara qu√© necesito agregar m√°s documentaci√≥n? La persona que llega a tu repositorio sabe de que va tu software, ve que funciona bien y quiere agregar una funcionalidad. Clona el repo y va directo al c√≥digo. Y ¬Ņahora qu√©? Hay m√©todos que implementaste y de seguro ese desarrollador necesita reutilizar o quiz√°s mejorar.

Un código bien documentado es un buen código. No estoy diciendo que debas agregar comentarios a todas tus funciones, variables e ifs pero es bueno hacerlo en la mayoría de ellas. Agregar una descripción corta de que hace, los parametros que espera y que es la salida que da.

Muchos IDEs (Entorno de Desarrollo Integrado) usan estos comentarios para completar la ayuda y mostrarsela al desarrollador cuando llame a ese método o clase.

Documentación de un método mostrada en PyCharm

Documenta tu software

Stephen Colbert. Tomado de tenor.

¬ŅM√°s documentaci√≥n? ¬ŅEn serio? Recuerda que este c√≥digo tambi√©n le pertenece a los dem√°s, entre m√°s expliques su funcionamiento mejor. ¬ŅTe imaginas tener que escribirle personalmente y explicarle todo a cada persona que se interese por tu repo? ūü§Į

Ya tienes un README con un resumen breve de qu√© es tu proyecto, con tu c√≥digo bien documentado para que el desarrollador sepa c√≥mo usarlo o mejorarlo, ¬ŅPara qu√© agregar m√°s documentaci√≥n? Ya tu sabes c√≥mo funciona tu software y la persona que contribuye tiene una idea, pero ¬Ņy tus usuarios? ūüė≥

Es algo que siempre se nos olvida, el usuario. Picamos c√≥digo como el mejor carnicero y se nos olvida cocinarlo a nuestro clientes. Seguro que cuando compras alg√ļn electrodom√©stico este trae un manual de instrucciones con elementos t√©cnicos que, por lo general no entiendes y otra parte con pasos sencillos de c√≥mo usarlo. As√≠ tambi√©n funciona la documentaci√≥n.

Esta documentación es más descriptiva. La documentación para tus usuarios finales es bastante variable ya que depende de qué es tu software. Si es una aplicación desktop debe explicar cómo descargarlo, instalarlo y configurarlo. Las principales funcionalidades y cómo usarlas. Si es una aplicación web debes explicar cómo desplegarla para que pueda tener su propia instancia. Estos son algunos ejemplos que se me ocurren. Lo que si debe contener son las funcionalidades que tiene, cómo usarlas y aprovecharlas.

La parte técnica es una explicación profunda para tus contribuidores. Explica paso a paso cómo instalar las herramientas que necesitas y el software en cuestión para su desarrollo. Los principales errores que pueden surguir en estos pasos y cómo resolverlos.

Por lo general, un software bien estructurado tiene una capa te abstracción que te ayuda a eliminar tareas tediosas y repetitivas cómo por ejemplo leer un fichero de configuración sin tener que comprobar si existe o crearlo. Esta parte es importante documentarla para que la persona que quiera contribuir a tu proyecto no reimplemente algo que ya está hecho.

Hay varias herramientas que te ayudan en la creación de estas documentaciones e incluso te la despliegan para que esté online para todo aquel que desee leerla. En mi caso pythonero uso Sphinx y Read the Docs.

Prueba y despliega autom√°ticamente

El continous integration y continous deployment (CI/CD) quiz√°s no es tan necesario para los contribuyentes pero sin dudas te ayuda a mantener en forma tu repositorio en forma y que no se produzcan errores inesperados y tu ni te enteres.

Con los GitHub actions puedes ejecutar las pruebas unitarias y de integraci√≥n en cada Pull Request o commit en una rama determinada y saber si esos nuevos cambios pasan todas las pruebas. ¬ŅTe imaginas que tu repositorio se vuelva popular y tengas decenas o cientos de Pull Request diarios? ¬ŅC√≥mo vas a probar que todo este c√≥digo se mantenga, al menos, funcional? Al tener muchas personas que contribuyan a tu c√≥digo, tarde o temprano se va a producir un error. Es de esperar. Estos tests automatizados te ayudar√°n a mantener tu c√≥digo libre de bugs y errores a la hora de integrar el c√≥digo de otra persona (dependiendo de la calidad de los tests que hayas escrito antes ūüėČ)

Al tener tantos cambios hay que lanzar nuevas versiones, ¬Ņno es as√≠? Con el continous deployment puedes automatizar el despliegue o compilaci√≥n de tu software con cada release que hagas.

Los procesos autom√°ticos en GitHub te brinda la posibilidad de hacer todas estas pruebas y despliegues autom√°ticos.

Bonus: Habla sobre tu proyecto

Tomado de tenor.

La comunicaci√≥n es la clave. ¬ŅC√≥mo van a saber tus posibles contribuidores que existe tu proyecto si no lo dices?

GitHub tiene una forma de organizar tus proyectos con etiquetas y agrega informaci√≥n relevante para que las personas dentro del sitio puedan encontrar m√°s f√°cilmente tu repositorio pero esto no es lo √ļnico.

Sección About. Se encuentra a la derecha de tu repositorio

Para que las personas se enteren de lo que hiciste debes decirlo. L√≥gica b√°sica. Redacta un peque√Īo post y una imagen de lo que has hecho. Comp√°rtelo en tus redes sociales pero no te quedes ah√≠. Entra en las comunidades que tengan que ver con las tecnolog√≠as que usaste y tambi√©n publica ah√≠. Si tienes alg√ļn medio de comunicaci√≥n como un canal de Telegram, podcast, blog tambi√©n habla sobre tu proyecto.

Las habilidades blandas que posee un desarrollador es lo que lo hace destacar. Un desarrollador que sepa comunicar, que sepa trabajar en equipo o domine habilidades de marketing, copy writing, es un gran activo para cualquier compa√Ī√≠a. Ah√≠ lo dejo :).

Conclusiones

Quizás te parezca esto un poco abrumador si no tienes nada de esto hecho o nunca lo has hecho. Con agregar un README explicativo tienes y vas agregando el resto de las cosas con calma. Recuerda que lo más importante es poder usar el software, por eso hice mucho énfasis en la documentación. Es la forma decirle al que quiera contribuir: esto está así y esta es su estructura, básate en esto y mejóralo!

Hace poco liber√© el c√≥digo fuente de Threadly, por lo que si deseas contribuir aqu√≠ te dejo el repositorio del frontend. Cu√°ndo agregue algunos pasos que mencion√© aqu√≠ liberar√© el c√≥digo fuente del API ūüėÖ (lo s√©, shame of me).

Si te interesa m√°s publicaciones como esta puedes unirte a mi canal de Telegram o escribirme por Twitter.

Si crees que este contenido te aportó valor, considera retornar ese valor dejándome un aporte en paynest.