Acorta enlaces en las notas de versión y registra cada descarga

Las notas de versión llegan más lejos que casi cualquier otra cosa que escriba un equipo de ingeniería. Nadie las mide. Pegas un enlace de descarga en el cuerpo de la versión, alguien lo copia en Slack, marketing lo incluye en la newsletter y un mantenedor lo publica en X. Seis meses después, la mitad de esos enlaces apuntan a un archivo que ya no existe y ninguno te ha contado nada. Para acortar correctamente los enlaces de las notas de versión necesitas tres cosas: un enlace corto estable "latest" que redirijas en cada lanzamiento, un enlace etiquetado separado por canal para cada versión y un flujo de trabajo en el evento release: published que cree ambos para que nadie tenga que acordarse.

Esa es toda la respuesta. El resto de esta publicación explica cómo conectarlo todo sin crear un desorden y qué pueden y qué no pueden decirte después los datos de clics.

He visto muchos proyectos gestionar a mano los enlaces de las notas de versión de GitHub, y el fallo siempre es el mismo: alguien enlaza a un recurso con versión, el enlace aparece citado en un hilo de un foro o en una respuesta de Stack Overflow y la siguiente versión lo deja huérfano en silencio. Si ya gestionas los enlaces como código, el enfoque siguiente encaja junto a enlaces cortos gestionados en Terraform, con la diferencia de que los enlaces de las versiones cambian según un calendario que no controlas manualmente.

Por qué los enlaces de las notas de versión caducan y pierden atribución

Aquí se esconden dos problemas distintos. Necesitan soluciones diferentes.

El primero es la caducidad de los enlaces. GitHub te da URL estables para la página de la versión (/releases/latest) y para los archivos, mediante /releases/latest/download/asset-name, pero el segundo solo funciona cuando el recurso conserva un nombre idéntico entre versiones, según la documentación de GitHub sobre cómo enlazar a versiones. La mayoría de los flujos de compilación incorporan la versión al nombre del archivo, así que app-2.3.0.dmg se convierte en app-2.4.0.dmg y la URL de descarga "latest" que funcionaba la semana pasada ahora devuelve un 404. Los enlaces de la documentación también caducan cuando se reorganiza un sitio de documentación. Encontrarás los patrones generales en nuestra estrategia para evitar la caducidad de enlaces; las notas de versión son simplemente el lugar donde más duele, porque sus enlaces viajan más lejos.

El segundo problema es la atribución, y es más silencioso. La API REST de GitHub sí informa de un download_count en cada recurso de versión, algo que más gente debería saber. Lo que no informa es de dónde llegó la descarga. Un pico de 4.000 descargas el día después del lanzamiento podría proceder de la newsletter, de un hilo de Hacker News o del proceso de CI de un único cliente empresarial descargando el binario en bucle. Los enlaces pegados en Slack y en mensajes directos eliminan por completo el referente, que es el problema de la atribución social oscura en miniatura.

Un enlace estable a la última versión que rediriges en cada lanzamiento

Crea un enlace corto, por ejemplo get.example.dev/latest, y trátalo como un puntero. Todas las páginas de documentación, las insignias del README y los scripts de instalación lo usan. En cada versión estable, actualizas el destino al que apunta. El slug nunca cambia, así que nada de lo que lo haya citado se rompe.

En Elido, ese puntero es un enlace normal. Lo creas una vez con POST /v1/workspaces/{workspace_id}/links, pasando el domain_id de tu dominio de marca, el slug y la destination_url. Guarda el id de la respuesta 201. Redirigirlo es un PATCH /v1/workspaces/{workspace_id}/links/{link_id} con una nueva destination_url y nada más; el slug, las etiquetas y el historial de clics se mantienen.

Déjalo en 302. Los enlaces de Elido usan 302 de forma predeterminada, y hay una razón para no cambiarlo en este caso: una 301 se puede almacenar en caché de forma predeterminada según RFC 9110, así que un navegador que vio la redirección del mes pasado quizá no vuelva a preguntar. Un puntero que los navegadores recuerdan para siempre deja de ser un puntero. Encontrarás más información en redirecciones 301 frente a 302 para enlaces cortos.

Decide una cosa de antemano. ¿El enlace a la última versión debería apuntar al archivo o a la página de la versión? Yo lo dirigiría a la página de la versión para cualquier proyecto con compilaciones para más de una plataforma y mantendría enlaces a la última versión por plataforma (/latest-mac, /latest-linux) solo si la documentación de instalación necesita realmente un archivo directo. Cuantos menos punteros móviles haya, menos cosas podrás redirigir mal.

Etiquetado por versión para los enlaces de las notas de versión de GitHub

El enlace a la última versión responde a "¿sigue funcionando el enlace?". No puede responder a "¿qué canal funcionó?", porque todo el mundo hace clic en el mismo slug. Para eso, cada versión recibe su propio conjunto pequeño de enlaces, uno por canal, creados al publicarse.

Esta es la parte que omiten la mayoría de las guías de UTM. Añadir utm_source=slack a una URL de github.com no sirve de nada, porque nunca verás los análisis de GitHub. Los UTM solo tienen sentido cuando el destino es un sitio que mides, como tu documentación o tu propia página de descargas. Cuando el destino es GitHub, el enlace corto separado por canal es la atribución: el clic se cuenta en la redirección, antes de que GitHub llegue a verlo.

Etiqueta cada enlace de una versión con la versión y el canal (["release", "v2.4.0", "slack"]), porque las etiquetas son la forma de recuperar después el conjunto: GET .../links?tags=v2.4.0 muestra todo lo correspondiente a una versión. Mantén los valores UTM sencillos e idénticos entre versiones. La guía de convenciones para nombrar UTM contiene las reglas que yo copiaría.

Crear enlaces en el evento de publicación de una versión

Una guía relacionada cubre la creación genérica de enlaces en CI, así que esta sección se centra en los aspectos específicos de las versiones. El activador es release con el tipo de actividad published. Según la lista de eventos de flujo de trabajo de GitHub, published se activa tanto para versiones estables como preliminares, incluidas las versiones preliminares publicadas desde un borrador, y por eso el paso de redirección comprueba la marca prerelease.

name: release-links
on:
  release:
    types: [published]

jobs:
  links:
    runs-on: ubuntu-latest
    env:
      API: https://api.elido.app/v1/workspaces/${{ vars.ELIDO_WORKSPACE_ID }}
      DOMAIN_ID: ${{ vars.ELIDO_DOMAIN_ID }}
      TAG: ${{ github.event.release.tag_name }}
      PAGE: ${{ github.event.release.html_url }}
      ELIDO_TOKEN: ${{ secrets.ELIDO_TOKEN }}
    steps:
      - name: Create one link per channel
        run: |
          v=$(echo "$TAG" | tr '.' '-')
          for ch in slack social news; do
            body=$(jq -n --argjson d "$DOMAIN_ID" --arg s "$v-$ch" \
              --arg u "$PAGE" --arg t "$TAG" --arg c "$ch" \
              '{domain_id:$d, slug:$s, destination_url:$u, tags:["release",$t,$c]}')
            code=$(curl -s -o /dev/null -w '%{http_code}' -X POST "$API/links" \
              -H "Authorization: Bearer $ELIDO_TOKEN" \
              -H "Content-Type: application/json" -d "$body")
            case "$code" in 201|409) ;; *) echo "create $ch failed: $code"; exit 1;; esac
            echo "- $ch: https://get.example.dev/$v-$ch" >> "$GITHUB_STEP_SUMMARY"
          done

      - name: Repoint the latest link
        if: ${{ !github.event.release.prerelease }}
        run: |
          curl -sf -X PATCH "$API/links/${{ vars.ELIDO_LATEST_LINK_ID }}" \
            -H "Authorization: Bearer $ELIDO_TOKEN" \
            -H "Content-Type: application/json" \
            -d "$(jq -n --arg u "$PAGE" '{destination_url:$u}')"

El resumen del trabajo proporciona a quien publica el anuncio una lista de enlaces lista para usar, y un 409 al volver a ejecutarlo significa que el slug ya existe, así que un flujo de trabajo reintentado no falla ni duplica nada. El enlace de la newsletter apuntaría a tu documentación con UTM en el destino; aquí lo he dejado en la página de la versión para mantener breve el ejemplo.

Tres problemas que me costaron una tarde

El primero es silencioso. Si tu flujo de publicación publica la versión usando el GITHUB_TOKEN predeterminado, este flujo de trabajo nunca se ejecuta, porque los eventos creados con GITHUB_TOKEN no activan nuevas ejecuciones de flujos de trabajo. Sin error, sin trabajo omitido, nada. Publica con un token de GitHub App.

Segundo, los puntos. Convierto v2.4.0 en v2-4-0 para el slug porque las cadenas de versión con puntos parecen extensiones de archivo en las vistas previas de los chats y algunos clientes las convierten en enlaces de forma extraña.

Tercero, no dejes que el flujo edite el cuerpo de la versión salvo que sea necesario. Funciona (gh release edit --notes-file), pero reescribe texto que una persona acaba de aprobar y activa eventos edited a los que pueden reaccionar otras automatizaciones. El resumen del paso es menos ingenioso y mucho más seguro. Los reintentos tienen su propia publicación: límites de velocidad e idempotencia de la API.

Si todavía pegas a mano los enlaces de las versiones, el flujo anterior requiere unos veinte minutos de configuración. Empieza con un espacio de trabajo gratuito de Elido, apunta un dominio de marca hacia él y deja que la siguiente etiqueta cree sus propios enlaces.

Cómo registrar los clics de las notas de versión por canal

Después de dos o tres versiones, los datos empiezan a responder preguntas que el contador de GitHub no puede responder.

La comparación por canal es la sencilla. Recupera los enlaces etiquetados con una versión y después lee el resumen de clics de cada enlace, delimitado por link_id. Si v2-4-0-news supera a v2-4-0-social por cinco a uno durante tres versiones seguidas, has aprendido dónde están realmente tus usuarios, y rara vez es donde el equipo suponía. El anuncio con más Me gusta a menudo no es el que envía a la gente a la descarga, así que espera resistencia la primera vez que muestres las cifras y aguarda a la tercera versión consecutiva antes de que alguien reescriba el plan de lanzamiento basándose en ellas.

El enlace a la última versión tiene un truco menos evidente. Cada clic registra el destino que resolvió en ese momento, así que el desglose de análisis por destino, limitado al enlace a la última versión, separa su tráfico por versión. Después de redirigirlo puedes observar cómo cae la proporción del destino antiguo y cuánto tiempo siguen llegando usuarios rezagados desde páginas almacenadas en caché y marcadores antiguos. Esa es tu curva de actualización real, medida en la parte superior del embudo.

Dos límites honestos. Los clics no son descargas: alguien puede hacer clic hasta la página de la versión y marcharse, y el download_count de GitHub sigue siendo la fuente de verdad para las descargas completadas. Además, los bots hacen clic en los enlaces de las versiones, especialmente los que recuperan vistas previas de enlaces en las aplicaciones de chat, así que lee las tendencias entre versiones en lugar de confiar en un solo día. La página de la función de análisis enumera los desgloses disponibles en cada plan.

Mantener activos los enlaces antiguos de las versiones

Los enlaces de cada versión nunca se mueven. v2-3-0-slack apunta a la etiqueta v2.3.0 en marzo y sigue apuntando allí dentro de cinco años, que es lo que espera alguien que lee un hilo antiguo de un foro. Solo cambia el enlace a la última versión y solo en las versiones estables.

El único caso en el que deberías tocar un enlace antiguo es cuando se retira una versión. Si v2.4.0 se publica con un error que provoca pérdida de datos, no elimines sus enlaces; redirige todos los enlaces v2-4-0-* a v2.4.1 con la misma llamada PATCH y una nota breve en el cuerpo de la versión. Eliminarlo deja en un callejón sin salida a quienes guardaron el enlace justo cuando más necesitan la corrección. Una versión más nueva gana a un 404. Siempre.

Para los proyectos que también mantienen enlaces antiguos de versiones en READMEs, scripts de instalación y metadatos de gestores de paquetes, la guía de acortadores de URL para desarrolladores explica dónde más resultan útiles los enlaces cortos. Toda la superficie REST está en la página de API y SDK.

Lee el artículo principal → Gestiona tus enlaces cortos como Terraform

Relacionado en el blog

• Estrategia para evitar la caducidad de enlaces - el enfoque más amplio para enlaces que deben sobrevivir a la página a la que apuntan.
• Inicio rápido de la API de un acortador de URL - autenticación, SDK y la llamada de creación que se usa en el flujo de trabajo.
• CLI del acortador de URL - las mismas operaciones desde un terminal, para versiones puntuales.
• Bot de Slack para acortar URL - acortar enlaces donde realmente llega el anuncio de la versión.
• Redirecciones 301 frente a 302 - por qué un enlace que puedes redirigir debe seguir siendo temporal.
• Enlaces cortos desde GitHub Actions - el paso genérico de creación o actualización para cualquier flujo de trabajo.