Como contribuir con el proyecto Asterisk. Mi experiencia.

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.
Configuring a VoIP PBX

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:

  1.  hacer unload al modulo: module unload  cdr_csv
  2. compilar: make
  3. copiar el .so:   cp cdr/cdr_csv.so  /usr/lib/asterisk/modules/
  4. 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!.

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *