Asterisk, la central PBX de código abierto, ha sido una solución con la que he trabajado por bastante tiempo. Hoy podemos indicar que Asterisk es más que una simple PBX ya que cuenta con una gran cantidad de carácteristicas adicionales la que han permitido consolidar a Asterisk como una solución para sistemas de comunicación. Actualmente goza de una gran popularidad y es utilizada por un gran numero de organizaciones en gran nivel en todo el mundo y para distintos tipos de usos.
Esta artículo se enfoca en mostrar como poder contribuir con código al proyecto Asterisk. Esto era algo que tenía ganas hace un tiempo, porque sería algo totalmente diferente a lo que venía haciendo hasta ahora y generalmente se traducía a desarrollar soluciones sobre Asterisk para nuevos sistemas o funcionalidades agregadas pero no en core de su código.
La idea de este artículo es dejar a modo de resumen sobre la experiencia, servir de guía y nuevas personas se animen a poner sus cambios en el proyecto.
Inicio
Cuando empezé a mirar y probar cambios en el código Asterisk se estaba usando Subversion y Reviewboard como plataformas para contribución de parches. Una semana después de empezar mi tarea de contribuir, el proyecto se movió a GIT y Gerrit, Jira se sigue manteniendo. Cambiar a GIT es un gran avance, ya que permite trabajar de manera mucho más comoda, puedes realizar tu trabajo y aislar funcionalidades mediante ramas e integrar de forma más fácil, asi como también realizar las pruebas de código.
Para empezar a contribuir lo primero que se debe hacer es crearse una cuenta en asterisk.org y firmar un acuerdo de licencia con Digium, esto es para que tus contribuciones pueden ser agregadas al código de Asterisk. Este acuerdo de licencia permite a Digium poder comercializar versiones de Asterisk con los cambios que has introducido.
Luego desde Gerrit debes confirmar la cuenta (Settings->Profile), ahí debes agregar tu nombre de usuario y confirmar.
El código
Cofirmada la cuenta, te bajas el código a la maquina que vas a empezar a testear, programar o hackear. En mi caso, el nombre de usuario que uso es roramirez. Entonces para clonar mi rama hago.
git clone ssh://roramirez@gerrit.asterisk.org:29418/asterisk.git
Si te aparecieran errores de SSL, asegurate que tu distribución tenga los CA certificate apropiados.
Si vas usar el clonado por ssh, asegurate agregar en Gerrit tu llave pública.
El comando clone genera una versión «trunk» del código, que es la rama de desarrollo. Si quisiera bajarme una rama particular debo hacer
git clone -b rama URL
O si ya estuviese en la master para cambiarme a la x versión
git checkout 13.5.0
Antes de poder publicar tus cambios es necesario agregar en tu proyecto un hook de git para hacer las contribuciones. Para eso ejecutas
git review -s
Debes tener instalado antes git-review. Lo instalas con PIP de la siguiente manera
pip install git-review
Para mas comandos de git te recomiendo leer el siguiente enlace, ahí encuentras información para utilizar GIT mediante CLI de manera sencilla.
Manos a la obra
Ahora, ¿que hacer?. Bueno siempre es bueno tratar de entender el código o la parte que deseas modificar. Si no tienes ideas por donde partir, busca en los Issues en Jira o visita la siguiente página donde puedes encontrar issues que son buenos para poder iniciarse en el proyecto.
Luego que ya pensaste que vas hacer o quieres testear el código, antes de poner manos a la obra es importante setear antes de compilar el Flag de modo de desarrollo:
./configure --enable-dev-mode
Modificas los archivos, aplicas compilación, instalación y pruebas tu cambio.
make && make install
La estructura del código (árbol de código) del proyecto es bastante explicativa, separadas por directorio donde están agrupados aplicaciones, modulos, codec, configuraciones, etc.. Así que en caso no es tán difícil perderse donde está cada cosa. Algo que es bueno apoyarse es de la función ast_debug que puedes usar como la usas los printf, puts, console.log .
Ejemplo:
ast_debug(3, "Testing debug %s\n", parameter);
Esto en el nivel 3 de debug 3 vas a ver la línea de testing.
Un dato de ayuda, por ejemplo, si estás modificando el archivo cdr/cdr_csv.c y quieres compilar y probar, para hacer esto mas rapido es:
- hacer unload al modulo: module unload cdr_csv
- compilar: make
- copiar el .so: cp cdr/cdr_csv.so /usr/lib/asterisk/modules/
- vuelves a cargar el modulo: module load cdr_csv
Publicar tu contribución
Ya que tienes listo tu cambio funcionando es hora que lo prepares para su publicación. Antes de ser agregado al core pasa por revisión mediante la plataforma gerrit, donde encargados revisión de cambios en el proyecto te haran llegar comentarios o sugerencias en caso de ser necesarias a modificar.
Algo importante a considera antes de publicar un cambio.
- Si es una nueva característica o bug deberías crear un issue en Jira. Así se permite traquear la información del cambio con lo agregado en el issue que es muy util para cuando se quiere revisar la historia del codigo en el proyecto y porque está cada línea de código.
Cuando tengas que escribir el mensaje del commit, ten encuenta:
- La extensión de caracteres no debe sobre pasar los 75 caracteres.
- Debe contener en la primera línea un resume del commit incluyendo el componente modificado. Luego una línea en blanco y luego el detalle de lo que hace el cambio.
- Si resulve un issue deberías poner ASTERISK-IDISSUE #close
Ejemplo:
chan_sip.c: Validation on module reload Change validation on reload module because now used the cli function for reload. The sip_reload() function never fail and ever return NULL for this reason on reload() now use the call the sip_reload() and return AST_MODULE_LOAD_SUCCESS. This problem is dectected on reload by PUT method on ARI, getting always 404 http code when the module is reloaded. ASTERISK-25325 #close Reporte by: Rodrigo Ramírez Norambuena
- Si agregarás una nueva característica agrega la nota en el archivo CHANGES
- Si tu cambio trae algo que considerar para la nueva versión agregarla la nota en el archivo UPGRADE-VERSION.txt correspondiente.
Luego, para enviar el cambio haces
git review
Si todo lo que hiciste está bien junto a tu código, el cambio pasará al core luego de ser aprobado. En caso que e tu cambio en Gerrit haya recibido comentarios y tengas que realizar modificaciones. Una forma fácil de traerte a tu repositorio local el cambio es mediante
git review -d n
Donde n es el id de tu patch en Gerrit
Ahí haces las modificaciones pertinentes, agregas las archivos y aplicas las actualizaciones a ese cambio mediante
git commit --amend git review
Información util de como usar Gerrit en el proyecto Asterisk la encuentras en el wiki Gerrit Usage. También puedes consultar, ya que es muy útil la información, la documentación generada mediante Doxygen ya que encuentras las API, descripción, ejemplos y mucho mas.
Con los datos anteriores ya cuentas con la información para poder contribuir con el proyecto Asterisk. Así que espero algún día espero poder ver tu commit en el proyecto. Happy Coding!.