Checklist para liberar un proyecto Open Source en Github

Github nos permite liberar cualquier proyecto en el que hayamos estado trabajado en privado. En ocasiones, nuestra intención es simplemente compartirlo sin más pretensiones como un pet project o como ejemplo de alguna kata que hemos estado preparado. Pero cuando queremos comenzar un proyecto Open Source un poco más serio, como una librería que queramos compartir con el resto de desarrolladores, quizás debamos pararnos a pensar un poco más antes de publicar nuestro código en Github si cumple una serie de pasos previos.

Vamos a repasar una serie de puntos interesantes para cualquier proyecto Open Source. Un pequeño checklist de recomendaciones, desde la visión tanto de un maintainer de proyectos de software Open Source como de un desarrollador que se encuentra un proyecto en Github y quiere usarlo.

Razones por las que liberar tu código como Open Source

Hay muchas razones por qué un desarrollador u organización querría hacer Open Source un proyecto. Algunos ejemplos para ilustrar la situación sería:

• Pura colaboración. Quizás estemos desarrollando un proyecto por nuestra cuenta, lo hayamos mencionado en algún grupo de slack o meetup de desarrolladores, y nos lancemos a hacerlo abierto para que el resto de desarrolladores sean contributors ayudándonos a avanzar.
• De forma individual simplemente buscar hacer público alguno de tus pet project. De esta forma la gente verá cómo programas y encuentres futuras colaboraciones.
• Transparencia: Existen muchas instituciones que ven el Open Source como la forma de hacer público en lo que están trabajando para que cualquiera pueda revisarlo sin problema.

Deja claro el objetivo, las expectativas y cómo utilizar/colaborar

“Release early, release often” es una de las frases más repetidas cuando pensamos en liberar un proyecto software. Hacer público un proyecto open source es sólo el principio. Por ello, lo primero que debemos hacer es dejar claras las expectativas a cualquier desarrollador que se encuentre con él.

Fundamentalmente necesitamos clarificar lo máximo posible los siguientes puntos:

• El objetivo del proyecto. ¿Qué es? Por ejemplo: una kata, una librería, un framework en construcción, etc..
• Las instrucciones y dependencias que necesita para ser ejecutado
• Un changelog accesible sobre los cambios de versiones y las versiones disponibles.

Checklist de tareas antes de liberar un proyecto Open Source

El clásico README

Es el lugar principal y donde cualquier desarrollador irá a buscar información. Debe estar localizado como un fichero de texto markdown en la raíz del proyecto. Github hace especial énfasis de que cada proyecto cuente con su correspondiente README.

Revisa el nombre Quizás el nombre sea lo primero que creaste, al menos, cuando le dedicaste horas de trabajo en privado, pero ahora que va a ser público debes asegurate que antes de lanzarlo no entra en conflicto con ninguno ya existente y ni mucho menos con alguna marca registrada.

Añade una descripción al proyecto Debemos explicar el objetivo, las motivaciones por las que existe este proyecto. También debemos enumerar las características del proyecto, incluyendo sus funcionalidades.

Cómo debo usarlo o integrarlo Si nos encontramos con un nuevo proyecto, lo más razonables es poder ser capaces de instalarlo, hacerlo arrancar o integrar en nuestra aplicación. Así que es fundamental que buena parte del README se trate de explicar las dependencias y las instrucciones para poder usarlo/integrarlo. Y no te olvides de explicar los test de los que cuenta, seguro que alguien que quiera probar su integridad o colaborar le será de ayuda lanzar los tests antes de crear una build desde el código.

Facilita la forma de descargar el artifact o la build Lo más habitual es que hayamos usado algun gestor de dependencias o un sistema de construcción del proyecto, ya sea con node, maven, gradle, makefile, etc… así como que el binario del proyecto se pueda descargar de algún lugar como maven central o con un sencillo npm.

Automatiza todo lo que puedas Es fundamental que a parte de que lo expliques en el README cuentes con un sencillo script que facilite la vida a los desarrolladores que quieran construir por ellos mismos la build. Usa bash, gradle, ant, maven, npm, etc.. para tu proyecto.

No te olvides del marketing Aprovecha para incluir algun logo o imagen que represente tu proyecto, nunca se sabe cuando alguien quiere hablar de él quizás, algún blog. Incluir un imagen representativa de tu librerías nunca es mala idea. Y si no lo tienes claro, piensa en los animales de la portadas de los libros de O’Really.

Añade una licencia

Liberar algo al público se debe hacer con cuidado. Revisa los componentes que utilizas y decide una libería acorde a tus intenciones y que cumpla los requisitos de tu proyecto. Entre las más populares se encuentran la Apache 2, MIT o GPL. Si te lías con los derechos y obligaciones que implican puedes consultar alguna recomendaciones de Github o alguna de estas webs: Choose a License o TLDR Legal.

¿Cómo contribuir?

Esta sección va indicada especialmente para tus futuros colaboradores, así que se claro indicando una serie de issues abiertas para ir empezando, así como un pequeño roadmap con las tareas a futuro del proyecto.

Y es fundamental que dejes a disposición de los contributors un checkstyle del código del proyecto y una serie de reglas para incorporar contribuciones como un codestyle o algun hook preparado. Así como los pasos a realizar una Pull Request, ahora que Github permite los template eso debería ser obligatorio para que no se les escape ningún apartado que explica en la PR. Es recomendable que lo expliques en un fichero CONTRIBUTING.

Changelog

Añade un listado con los cambios de cada versión. Es fundamental para tus usuarios conocer que se va incorporando progresivamente en cada “salto de versión”. Respeta el versionado estándar utilizando adecuadamente la numeración de MAJOR.MINOR.PATCH.

Intenta separar cada cambio del siguiente modo:

• Nuevos componentes que has introducido, ya sean componentes, APIs nuevas, funcionalidades, etc..
• Elementos deprecated, es decir, lo que en próximas versiones será eliminado y remplazado por otros elementos. No olvides indicar el que se debería usar o la estrategia de migración.
• Elementos que han sido eliminados. Recuerda la retrocompatilidad. No borres nada en un cambio de versión que no haya sido anteriormente marcado como deprecated.
• Y por fin, los bugs que se han ido resolviendo en cada nueva versión. Añade si es posible la issue correspondiente para poder hacer un mejor seguimiento del problema que originaba. Seguro que alguien que se haya dado cabezazos con él se sentirá reconfortado al ver que ya está solucionado.