Merge pull request 'docs: update pipeline examples, installation guide, add badges' (#63) from docs/update-readme into main

Reviewed-on: #63

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 <command> -h` para
+Git Flow cuenta con los siguientes comandos para guiar el workflow (ver `git-flow <command> --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.
@@ -114,6 +102,11 @@ Comportamiento:
   implica un salto de versión, se avisa y el comando termina con código de salida 1.
 - Con más de un entorno configurado, cada rama versiona por separado con el nombre del entorno como
   sufijo (por ejemplo, `v1.2.0-prod`). Con un solo entorno no se agrega sufijo.
+- Si el merge viene del entorno anterior (por ejemplo, `dev` a `test`), no se calcula una nueva
+  versión: se promueve la del entorno anterior cambiando el sufijo (si `dev` está en `v1.2.0-dev` y
+  `test` en `v1.0.0-test`, el nuevo tag es `v1.2.0-test`), sin importar los tipos de commit. Si ese
+  tag ya existe en el destino, el comando falla. En un pipeline, el merge se detecta por la rama
+  origen del PR; localmente, porque el merge trae tags del entorno anterior que el destino no tenía.
 
 ## Remotos soportados
 
@@ -148,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 }}
 ```
@@ -172,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
 ```
@@ -198,6 +193,9 @@ ver el archivo `bitbucket-pipelines.yml` como ejemplo:
 # bitbucket-pipelines.yml
 image: python:3.14
 
+clone:
+  depth: 10
+
 pipelines:
   branches:
     'main':
@@ -240,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=<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=<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.

src/git_flow/command/tag.py

@@ -37,9 +37,6 @@ def tag(target: str | None = None, token: str | None = None, update_changelog: b
         base.io_info(f"El último merge ya tiene un tag: {merge_commit_tag}")
         return
 
-    # Con varios entornos cada uno versiona por separado (v1.0.0-prod), con uno solo no hace falta
-    suffix = f"-{target}" if len(base.environments) > 1 else ""
-
     token, ci = get_token_and_ci(token)
 
     if ci and not token:
@@ -48,23 +45,52 @@ def tag(target: str | None = None, token: str | None = None, update_changelog: b
     # Con varios entornos cada uno versiona por separado (v1.0.0-prod), con uno solo no hace falta
     suffix = f"-{target}" if len(base.environments) > 1 else ""
 
-    if ci:
+    # Un merge desde el entorno anterior (por ejemplo, dev a test) promueve su versión tal cual
+    target_index = base.environments.index(target)
+    source_env = base.environments[target_index - 1] if target_index > 0 else None
+    source_suffix = f"-{source_env}"
+    promoted_tag = None
+    api = base.get_remote_api(token) if ci else None
+
+    if api:
         # Commits se obtienen por API del ultimo PR / MR mergeado
-        commits = base.get_remote_api(token).get_merge_commits(merge_commit)
+        commits = api.get_merge_commits(merge_commit)
         commits = [c for c in commits if not c.is_merge]
         # Último tag se obtiene por API filtrando por sufijo
-        current_tag = base.get_remote_api(token).get_latest_tag(suffix)
+        current_tag = api.get_latest_tag(suffix)
+
+        if source_env and api.get_merge_source_branch(merge_commit) == source_env:
+            promoted_tag = api.get_latest_tag(source_suffix)
     else:
-        # Commits se obtienen del último merge, listando hasta el primer forkpoint
         branch = Git("show", merge_commit + "^2", patch=False, format="%H").firstline()
-        fork_point = Git.get_first_fork_point(branch, target)
-        commits = Git.get_commits(fork_point, branch)
+        promoted_tag = Git.get_promoted_tag(merge_commit, source_suffix) if source_env else None
+
+        if promoted_tag:
+            # Todos los cambios que el entorno anterior trae al destino
+            commits = Git.get_commits(merge_commit + "^1", branch, first_parent=False)
+        else:
+            # Commits se obtienen del último merge, listando hasta el primer forkpoint
+            fork_point = Git.get_first_fork_point(branch, target)
+            commits = Git.get_commits(fork_point, branch)
+
         # Último tag se obtiene localmente
         current_tag = Git.get_current_tag(suffix)
 
-    next_tag = get_next_tag_from_commits(
-        [c.subject for c in commits], suffix, current_tag
-    )
+    if promoted_tag:
+        next_tag = promoted_tag.removesuffix(source_suffix) + suffix
+        base.io_info(
+            f"Merge desde {source_env}: se promueve la versión {promoted_tag} a {target}."
+        )
+
+        # Puede existir si el destino ya llegó a esa versión por otro lado (por ejemplo, un release)
+        existing = api.list_tags(suffix) if api else Git("tag", next_tag, list=True).lines()
+
+        if next_tag in existing:
+            raise GitFlowError(f"El tag {next_tag} ya existe en {target}.")
+    else:
+        next_tag = get_next_tag_from_commits(
+            [c.subject for c in commits], suffix, current_tag
+        )
 
     if not next_tag:
         base.io_warning(

src/git_flow/git.py

@@ -73,6 +73,21 @@ class Git:
             exclude=None if suffix else "*-*",
         ).firstline(check=False, print="Obteniendo tag actual")
 
+    @staticmethod
+    def get_promoted_tag(merge_commit: str, suffix: str) -> str | None:
+        """Si el merge trae tags con el sufijo indicado que la rama destino no tenía (por ejemplo,
+        un merge de dev a test trae tags *-dev nuevos), devuelve el más alto de ellos."""
+        tags = Git(
+            "tag",
+            "v[0-9]*.[0-9]*.[0-9]*" + suffix,
+            list=True,
+            merged=merge_commit + "^2",
+            no_merged=merge_commit + "^1",
+            sort="-v:refname",
+        ).lines()
+
+        return tags[0] if tags else None
+
     @staticmethod
     def get_first_fork_point(branch: str, env: str):
         # Lista de commits alcanzables por el entorno (por ejemplo, dev),
@@ -84,10 +99,14 @@ class Git:
         return Git("show", env_commits[-1] + "^", patch=False, format="%h").firstline()
 
     @staticmethod
-    def get_commits(base: str, branch: str) -> list[Commit]:
+    def get_commits(base: str, branch: str, first_parent: bool = True) -> list[Commit]:
         """Commits propios de la rama (sin merges), del más nuevo al más viejo."""
         lines = Git(
-            "log", base + ".." + branch, first_parent=True, merges=False, format="%h%x09%ae%x09%s"
+            "log",
+            base + ".." + branch,
+            first_parent=first_parent or None,
+            merges=False,
+            format="%h%x09%ae%x09%s",
         ).lines()
         commits = []
 

src/git_flow/remote/base.py

@@ -74,6 +74,11 @@ class RemoteAPI(ABC):
         viejo), sin depender del historial local."""
         pass
 
+    @abstractmethod
+    def get_merge_source_branch(self, merge_commit: str) -> str:
+        """Nombre de la rama origen del PR que generó el merge commit."""
+        pass
+
     @abstractmethod
     def list_tags(self, suffix: str = "") -> list[str]:
         """Nombres de los tags del repositorio, sin orden garantizado. `suffix` es solo una pista

src/git_flow/remote/bitbucket.py

@@ -48,12 +48,7 @@ class BitbucketRemoteAPI(RemoteAPI):
             raise GitFlowError("Ocurrió un error al crear el tag: " + response.text)
 
     def get_merge_commits(self, merge_commit: str) -> list[Commit]:
-        prs = self.get_json(self.get_endpoint(f"commit/{merge_commit}/pullrequests")).json()
-        pr = next((p for p in prs["values"] if p["state"] == "MERGED"), None)
-
-        if not pr:
-            raise GitFlowError(f"No se encontró un PR para el commit {merge_commit}")
-
+        pr = self._get_merge_pull_request(merge_commit)
         commits: list[Commit] = []
         url: str | None = self.get_endpoint(f"pullrequests/{pr['id']}/commits")
 
@@ -77,6 +72,18 @@ class BitbucketRemoteAPI(RemoteAPI):
 
         return commits
 
+    def get_merge_source_branch(self, merge_commit: str) -> str:
+        return self._get_merge_pull_request(merge_commit)["source"]["branch"]["name"]
+
+    def _get_merge_pull_request(self, merge_commit: str) -> dict:
+        prs = self.get_json(self.get_endpoint(f"commit/{merge_commit}/pullrequests")).json()
+        pr = next((p for p in prs["values"] if p["state"] == "MERGED"), None)
+
+        if not pr:
+            raise GitFlowError(f"No se encontró un PR para el commit {merge_commit}")
+
+        return pr
+
     def list_tags(self, suffix: str = "") -> list[str]:
         names: list[str] = []
         url: str | None = self.get_endpoint("refs/tags")

src/git_flow/remote/gitea.py

@@ -46,7 +46,7 @@ class GiteaRemoteAPI(RemoteAPI):
             raise GitFlowError("Ocurrió un error al crear el tag: " + response.text)
 
     def get_merge_commits(self, merge_commit: str) -> list[Commit]:
-        pr = self.get_json(self.get_endpoint(f"/commits/{merge_commit}/pull")).json()
+        pr = self._get_merge_pull_request(merge_commit)
         url = self.get_endpoint(f"/pulls/{pr['number']}/commits")
         items: list = []
         page = 1
@@ -74,6 +74,12 @@ class GiteaRemoteAPI(RemoteAPI):
             for c in reversed(items)
         ]
 
+    def get_merge_source_branch(self, merge_commit: str) -> str:
+        return self._get_merge_pull_request(merge_commit)["head"]["ref"]
+
+    def _get_merge_pull_request(self, merge_commit: str) -> dict:
+        return self.get_json(self.get_endpoint(f"/commits/{merge_commit}/pull")).json()
+
     def list_tags(self, suffix: str = "") -> list[str]:
         tags = self.get_all_pages(self.get_endpoint("/tags"), 50, size_param="limit")
 

src/git_flow/remote/github.py

@@ -44,12 +44,7 @@ class GithubRemoteAPI(RemoteAPI):
             raise GitFlowError("Ocurrió un error al crear el tag: " + response.text)
 
     def get_merge_commits(self, merge_commit: str) -> list[Commit]:
-        prs = self.get_json(self.get_endpoint(f"/commits/{merge_commit}/pulls")).json()
-        pr = next((p for p in prs if p.get("merge_commit_sha") == merge_commit), None)
-
-        if not pr:
-            raise GitFlowError(f"No se encontró un PR para el commit {merge_commit}")
-
+        pr = self._get_merge_pull_request(merge_commit)
         items = self.get_all_pages(self.get_endpoint(f"/pulls/{pr['number']}/commits"), 100)
 
         # La API los devuelve del más viejo al más nuevo
@@ -63,6 +58,18 @@ class GithubRemoteAPI(RemoteAPI):
             for c in reversed(items)
         ]
 
+    def get_merge_source_branch(self, merge_commit: str) -> str:
+        return self._get_merge_pull_request(merge_commit)["head"]["ref"]
+
+    def _get_merge_pull_request(self, merge_commit: str) -> dict:
+        prs = self.get_json(self.get_endpoint(f"/commits/{merge_commit}/pulls")).json()
+        pr = next((p for p in prs if p.get("merge_commit_sha") == merge_commit), None)
+
+        if not pr:
+            raise GitFlowError(f"No se encontró un PR para el commit {merge_commit}")
+
+        return pr
+
     def list_tags(self, suffix: str = "") -> list[str]:
         return [t["name"] for t in self.get_all_pages(self.get_endpoint("/tags"), 100)]
 

src/git_flow/remote/gitlab.py

@@ -49,14 +49,7 @@ class GitlabRemoteAPI(RemoteAPI):
             raise GitFlowError("Ocurrió un error al crear el tag: " + response.text)
 
     def get_merge_commits(self, merge_commit: str) -> list[Commit]:
-        mrs = self.get_json(
-            self.get_endpoint(f"/repository/commits/{merge_commit}/merge_requests")
-        ).json()
-        mr = next((m for m in mrs if m.get("merge_commit_sha") == merge_commit), None)
-
-        if not mr:
-            raise GitFlowError(f"No se encontró un MR para el commit {merge_commit}")
-
+        mr = self._get_merge_request(merge_commit)
         items = self.get_all_pages(self.get_endpoint(f"/merge_requests/{mr['iid']}/commits"), 100)
 
         # GitLab ya los devuelve del más nuevo al más viejo
@@ -70,6 +63,20 @@ class GitlabRemoteAPI(RemoteAPI):
             for c in items
         ]
 
+    def get_merge_source_branch(self, merge_commit: str) -> str:
+        return self._get_merge_request(merge_commit)["source_branch"]
+
+    def _get_merge_request(self, merge_commit: str) -> dict:
+        mrs = self.get_json(
+            self.get_endpoint(f"/repository/commits/{merge_commit}/merge_requests")
+        ).json()
+        mr = next((m for m in mrs if m.get("merge_commit_sha") == merge_commit), None)
+
+        if not mr:
+            raise GitFlowError(f"No se encontró un MR para el commit {merge_commit}")
+
+        return mr
+
     def list_tags(self, suffix: str = "") -> list[str]:
         # "search" soporta "$" para anclar al final del nombre
         params = {"search": suffix + "$"} if suffix else None