Git Flow

Herramienta para establecer un workflow siguiendo Conventional Commits (CC), Conventional Branch (CB), y SemVer.

Esta diseñada para facilitar la creación de commits y branches en un formato estandar, que permite derivar versiones automaticamente de los merges sobre ramas principales.

Instalación

Para instalar Git Flow, se sugiere utilizar pipx (seguir la documentación para instalarlo). Una vez instalado pipx, simplemente clonamos el repositorio en una carpeta local, y lo instalamos:

cd ~/Downloads
git clone git@bitbucket.org:sushi2717/git-flow.git
cd git-flow
pipx install .

Luego podemos verificar que se haya instalado correctamente ejecutando: git-flow -h

Para actualizarlo, hacemos un pull de los cambios recientes del repositorio, y hacemos el upgrade mediante pipx:

cd ~/Downloads/git-flow
git pull
pipx upgrade git-flow

Configuración

Para poder usar la herramienta en un repositorio, necesitamos inicializarlo:

git-flow init

El comando solicitará 2 opciones:

• Ramas principales: Ramas que representan los entornos principales del proyecto. Por ejemplo: dev,test,prod.

• Remoto (opcional): Nombre del remoto que se usará para crear PRs, y taggear merges automáticamente. Por el momento, se soportan los siguientes remotos:

  • Bitbucket
  • Github
  • Gitea

  La configuración del remoto requiere tener un Access Token para poder crear los PRs automáticamente. El mismo se puede crear desde el repositorio al que se quiere dar acceso: "Repository settings" > "Access Tokens" > "Create access token". El token necesita permiso para Write en Pull Requests.

  Luego se debe guardar el token dentro del repositorio a configurar, en el archivo .repository-token. De no especificarse, los merges y tags se harán de forma local.

Utilización

Git Flow cuenta con 5 comandos principales para guiar el workflow (ver git-flow <command> -h para más información):

• new: Crea una nueva rama siguiendo CB.
• commit: Crea un commit siguiendo CC.
• merge: Mergea la rama actual a una de las ramas principales.
• tag: Crea un tag sobre el ultimo merge siguiendo SemVer.
• release: Prepara la rama actual para pasarse al siguiente entorno configurado

El workflow para el cual se penso la herramienta es el siguiente:

1. Sobre la primer rama principal configurada (por ejemplo, dev), se crea una nueva rama con git-flow new
2. Se realizan cambios y se commitean los mismos con git-flow commit (se repite hasta que se considere que la rama esté lista para mergear)
3. Se ejecuta git-flow merge para mergear la rama al entorno que corresponda (en este caso, dev). En caso de tener un remoto configurado, el comando crea un PR para integrar el cambio. Si no, simplemente se ejecuta un git merge simple.
4. Para versionar este último merge, se ejecuta git-flow tag, ya sea localmente o desde un pipeline para que se ejecute en cada merge.
5. Una vez que la rama fue correctamente integrada a un entorno (por ejemplo, dev), se usa git-flow release para crear una nueva rama para integrar unicamente los cambios de esa rama sobre el siguiente entorno (por ejemplo, test). Si la rama original era feature/my-new-feature, se crea la rama release/test/feature/my-new-feature sobre test que tiene los cambios de la rama original.

Taggeo automático por pipeline

Éste repositorio utiliza Git Flow para el taggeo automático usando pipelines, se puede ver el archivo bitbucket-pipelines.yml como ejemplo. El comando git-flow tag soporta el pasaje del token mediante la opción --token=<TOKEN>. Ver la sección Configuración para las instrucciones de como generar este token. El mismo necesita scope write:repository:bitbucket.