# Git Flow

Herramienta para establecer un workflow siguiendo [Conventional Commits
(CC)](https://www.conventionalcommits.org), [Conventional Branch
(CB)](https://conventional-branch.github.io/), y [SemVer](https://semver.org/).

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](https://github.com/pypa/pipx) (seguir la
documentación para instalarlo). Una vez instalado `pipx`, simplemente clonamos el repositorio en una
carpeta local, y lo instalamos:

```sh
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`:

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

## Configuración

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

```sh
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:

  - [x] 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](#configuracion) para las
instrucciones de como generar este token. El mismo necesita scope `write:repository:bitbucket`.