¿Como contribuir con el desarrollo de un módulo de Node.js usando github?

Se asume que se tienen conocimientos básicos de git, github, Node.js, Sistemas basados en UNIX

Tomaremos como ejemplo el módulo YUIDocs el cuál nos permite la generación de documentación automática. Este módulo puede ser instalado mediante el comando:

npm install -g yuidocjs

De esta estamos instalando YUIDocs de manera global en nuestra PC.

/usr/local/lib/node_modules 

En node_modules podemos ver todos los módulos de Node.js que han sido instalados hasta el momento, y ahora también YUIDocs (yuidoc).

También se habrá creado un link simbólico que apunta al fichero definido por el módulo como su ejecutable:

/usr/local/bin

Si se quiere saber qué fichero es el que se ha definido como ejecutable de un módulo abrimos el fichero package.json que se encuentra en la raíz del módulo y buscamos la sentencia:

“bin”:  {“yuidoc ” :  ”./lib/cli.js”} 

en este caso, la misma le indica a npm que debe crear un link simbólico cuyo nombre es “yuidoc ” y que el mismo va a apuntar al fichero ”./lib/cli.js” .

Buscamos en github el repositorio de desarrollo del módulo, y le hacemos fork.

Clonamos nuestro fork en nuestra carpeta local,

git clone [email protected]:yui/yuidoc.git

Agregamos un remote del repositorio original para estar sincronizados con las actualizaciones que se le hagan al módulo por parte de sus desarrolladores.

git remote add upstream git://github.com/darielnoel/yuidoc.git

Sincronizamos el módulo con la última versión.

git pull upstream master

El anterior proceso se encuentra muy bien explicado en el sitio oficial de YUI3.

Bueno hasta aquí ya tenemos el módulo, en nuestra PC, sincronizado con los últimos cambios hechos al mismo por sus desarrolladores, y pudiéramos empezar a modificarlo. Una práctica recomendable es crear una nueva rama para cada nueva funcionalidad, y trabajar en ella por ejemplo:

git checkout -b funcionalidadX upstream/master

Esto nos da la posibilidad de que si llegamos a un punto en el que queremos ir a la versión original simplemente nos cambiamos a la rama master y listo.

git checkout master

¿Cómo probar que nuestros cambios funcionan realmente como esperamos?

Suponiendo que estemos en la raíz de la carpeta que contiene el módulo que descargamos para que se instalen localmente las dependencias del módulo hacemos:

npm install .

Luego creamos un link simbólico del fichero descrito en package.json como el bin, en nuestro ejemplo lib/cli.js.

ln -s /rutaAlModuloQueClonaste/bin/cli.js usr/local/bin/yuidoc

De esta manera ejecutará el módulo nuestro y no el módulo que se ha instalado globalmente cuando hagamos:

yuidoc --help