From 8a28ce3a7e944a8f067baaf910dee70cd5e0b9dd Mon Sep 17 00:00:00 2001 From: Jonathan Teran Date: Fri, 25 Sep 2026 09:53:44 -0300 Subject: [PATCH] docs: update pipeline examples, installation guide, add badges --- README.md | 62 ++++++++++++++++++++++++------------------------------- 1 file changed, 27 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 66856cc..fa632d8 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ # Git Flow +[![PyPI Version](https://img.shields.io/pypi/v/git-flow-envs)](https://pypi.org/project/git-flow-envs/) +![Python Version](https://img.shields.io/python/required-version-toml?tomlFilePath=https://git.jonathanteran.dev/jt/git-flow/raw/branch/main/pyproject.toml) + 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/). @@ -9,27 +12,12 @@ 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: +Se puede instalar con `pip` ejecutando el siguiente comando: `pip install git-flow-envs`. Sin +embargo, se sugiere utilizar [pipx](https://github.com/pypa/pipx) (seguir la documentación para +instalarlo), ya que aisla las dependencias de la herramienta en un `venv`. Una vez instalado, +simplemente ejecutamos `pipx install git-flow-envs` -```sh -cd ~/Downloads -git clone ssh://git@git.jonathanteran.dev:59169/jt/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 -``` +Luego podemos verificar que se haya instalado correctamente ejecutando: `git-flow --help` ## Configuración @@ -46,10 +34,10 @@ El comando solicitará 2 opciones: - **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 - - [x] Github - - [x] Gitea - - [x] Gitlab + - [x] Bitbucket + - [x] Github + - [x] Gitea + - [x] Gitlab La configuración del remoto requiere tener un Access Token para poder crear los PRs y tags automáticamente. Ver la sección [Remotos soportados](#remotos-soportados) para las instrucciones @@ -60,13 +48,13 @@ El comando solicitará 2 opciones: ## Utilización -Git Flow cuenta con los siguientes comandos para guiar el workflow (ver `git-flow -h` para +Git Flow cuenta con los siguientes comandos para guiar el workflow (ver `git-flow --help` para más información): - `init`: Inicializa el repositorio para utilizar git-flow (ramas principales y remoto). - `new`: Crea una nueva rama siguiendo CB. - `commit`: Crea un commit siguiendo CC. -- `merge`: Mergea la rama actual a una de las ramas principales. +- `merge`: Mergea la rama actual a uno de los entornos. - `tag`: Crea un tag sobre el ultimo merge siguiendo SemVer (ver [Tag](#tag)). - `release`: Prepara la rama actual para pasarse al siguiente entorno configurado. - `branch ls`: Lista las ramas del repositorio, agrupadas por entorno objetivo. @@ -153,12 +141,11 @@ jobs: steps: - uses: actions/checkout@v4 with: - fetch-depth: 0 + fetch-depth: 10 - uses: astral-sh/setup-uv@v3 - run: uv run git-flow tag --token=${{ secrets.GIT_FLOW_TOKEN }} - - run: uv build - run: uv publish --token=${{ secrets.PYPI_TOKEN }} ``` @@ -177,11 +164,14 @@ Ejemplo de pipeline (GitLab CI) para taggear automáticamente en cada push a una # .gitlab-ci.yml tag: image: python:3.14 + variables: + GIT_DEPTH: 10 rules: - if: $CI_COMMIT_BRANCH == "main" script: - pip install uv - - uv run git-flow tag --token=$GIT_FLOW_TOKEN + # GitLab hace checkout en detached HEAD, por lo que la rama se indica explícitamente + - uv run git-flow tag --target=$CI_COMMIT_BRANCH --token=$GIT_FLOW_TOKEN - uv build - uv publish --token=$PYPI_TOKEN ``` @@ -203,6 +193,9 @@ ver el archivo `bitbucket-pipelines.yml` como ejemplo: # bitbucket-pipelines.yml image: python:3.14 +clone: + depth: 10 + pipelines: branches: 'main': @@ -245,19 +238,18 @@ jobs: steps: - uses: actions/checkout@v4 with: - fetch-depth: 0 + fetch-depth: 10 - uses: astral-sh/setup-uv@v3 - run: uv run git-flow tag --token=${{ secrets.GIT_FLOW_TOKEN }} - - run: uv build - run: uv publish --token=${{ secrets.PYPI_TOKEN }} ``` ## Taggeo automático por pipeline -En todos los casos, `git-flow tag` detecta que se está ejecutando desde un pipeline (no encuentra -`.repository-token` en el repositorio) y usa el token pasado por `--token=` tanto para crear -el tag en el remoto como para pushear el commit del `CHANGELOG.md` generado, en vez de crear el tag -únicamente en forma local como sucede al ejecutarlo manualmente sin remoto configurado. +En todos los casos, al pasar `--token=` `git-flow tag` asume que se está ejecutando desde un +pipeline: obtiene los commits del último PR / MR y el último tag por API del remoto, y usa el token +tanto para crear el tag en el remoto como para pushear el commit del `CHANGELOG.md` generado (con +`--update-changelog`), en vez de resolver todo en forma local. -- 2.54.0