From aad1a666415d77e026b69ee33591c08091825d06 Mon Sep 17 00:00:00 2001 From: Jonathan Teran Carballo Date: Sat, 22 Nov 2025 18:29:42 -0300 Subject: [PATCH] docs: actualizo readme --- README.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 69 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index bdacd4a..e00ab39 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,71 @@ # Git Flow -Herramienta para establecer un workflow y versionar un repositorio +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. + +## 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 -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=`. Ver la sección [Configuración](#configuracion) para las +instrucciones de como generar este token. El mismo necesita scope `write:repository:bitbucket`.