Saltar a contenido

Lineamientos para contribuir a un proyecto

Se deben seguir los siguientes lineamientos para contribuir al desarrollo de un proyecto. Esto garantiza que la trazabilidad y el versionamiento sean robustos.

Git Workflow

Se utiliza Gitflow con la siguiente estructura de branches:

  • main branch: solo guarda los releases oficiales. Cada release debe estar identificado con su respectivo tag que hace alusión a la versión del código (ver Etiquetas (Git tags)). Este es el branch principal del proyecto. A este branch no se le pueden hacer commits directamente, par aplicar cambios en el, se debe hacer un pull request desde el dev branch o un hotfix/ branch.

    Sobre el main branch están configuradas unas GitHub Actions que cuidan que se apliquen las mejores prácticas cuando se lleve una actualización a este branch. Además, se encargan de desplegar la documentación en GitHub Pages.

  • dev branch: funciona como integrador de los distintos ajustes, cambios, correcciones, mejoras o adiciones (bug fixes o features) que se están desarrollando. Este es el branch del que se deben crear los forks para desarrollar correcciones, mejoras o adiciones en el código.

  • bugfix/ branches: Cada corrección debe residir en su propio branch. Siempre se deben crear a partir del dev branch.

  • feature/ branches: Cada nuevo cambio, mejora o adición debe residir en su propio branch. Siempre se deben crear a partir del dev branch.

  • release/ branches: Cuando se tienen acumulados varios cambios, mejoras, correcciones y/o adiciones, se crea un branch de este tipo desde el dev branch. Esto inicia el ciclo de release y a partir de este momento no se pueden añadir nuevas mejoras o cambios al código, en este branch, que no estén relacionadas con la corrección de errores, la documentación o tareas específicas orientadas al proceso de release.

  • hotfix/ branches: Usadas para reparar rápidamente errores en la versión de producción (main branch). Este es el único branch que se puede (y debe) crear a partir del main branch. Una vez terminada la corrección se fusiona nuevamente (a través de un pull request) con el main branch, con el release branch actual y con el dev branch. La fusión con el main branch debe llevar su respectiva tag con el número de versión actualizado.

Mensaje Commits

Es obligatorio incluir un mensaje en cada commit. El mensaje debe utilizar la siguiente plantilla:

<tipo>[alcance (opcional)]: <asunto> (Si se aplica, este commit...)
(ejemplos:)
fix: corrige error en la función de carga de datos
feat(parser): agrega soporte para nuevos formatos de archivo
|<--------------------  Usar máximo 75 caracteres  ---------------------->|

(cuerpo opcional) Explique por qué se realiza el cambio y qué está cambiando.
Si el cambio es grande, use viñetas para organizar la información.
(ejemplo:)
- Descripción del cambio 1
|<--------  Trate de limitar cada línea a máximo 75 caracteres  --------->|

(pie de página opcional)
Descripción: Provea links o claves a cualquier ticket, artículo u otro
recurso relevante para el commit
Indique si el commit produce un BREAKING CHANGE
(ejemplo:)
Closes: #23
BREAKING CHANGE: Se cambia la forma en que se maneja ...
|<--------  Trate de limitar cada línea a máximo 75 caracteres  --------->|

----------------------------- FIN DEL COMMIT ------------------------------

<tipo> puede ser:
    fix             corrección de error o errores
    feat            nueva característica o funcionalidad
    data            versionamiento de datos
    refactor        ajusta o mejora del código; no se cambia funcionalidad
    chore           cambia configuración CI/CD, pre-commits (prek), etc.; no se cambia el código de producción
    docs            cambios a la documentación
    style           formato (e.g. agregar comas que faltaban); no se cambia el código
    perf            mejora rendimiento
    test            añadir o ajustar tests; no se cambia el código de producción
    build           cambios en los procesos para build el código
    ci              cambios en los procesos de continuos integration
    revert          revierte un commit previo

---------------

Recuerde...
    Empezar con minúscula la línea del asunto. Tanto el <tipo> como el <asunto>
    Usar el modo imperativo en la línea del asunto
    No terminar la línea del asunto con punto
    Separar la línea del asunto del cuerpo del commit (descripción) con una línea en blanco
    Usar el cuerpo del commit para explicar el qué y el por qué, no el cómo
    Puede usar múltiple líneas con "-" para viñetas en el cuerpo del commit

Etiquetas (Git tags)

Se usa SemVer como lineamiento para administrar y denotar el versionamiento. Para nombrar las etiquetas (tags) se debe usar la forma v0.0.0.

Para ver las versiones disponibles, consulte las tags en este repositorio.