git-flow/README.md

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.

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: planeado

  La configuración del remoto requiere tener un API Token para poder crear los PRs automáticamente. El mismo se puede crear desde: "Atlassian Account Settings" > "Security" > "Create and Manage API Tokens" > "Create API Tokens with scopes". El token necesita el scope write:pullrequest:bitbucket

  • write:repository:bitbucket

  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.