Metadata-Version: 2.4
Name: git-flow-envs
Version: 1.17.3
Summary: Git workflow automation to follow best practices when working with multiple environments
Author-email: Alan Facundo Biglieri <abiglieri@renatre.org.ar>, Jonathan Teran Carballo <jteran@renatre.org.ar>
Requires-Python: >=3.14
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: typer

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