Raccourcir les liens des notes de version et suivre chaque téléchargement

Les notes de version voyagent plus loin que presque tout ce qu'écrit une équipe d'ingénierie. Personne ne les mesure. Vous collez un lien de téléchargement dans le corps de la version, quelqu'un le copie dans Slack, le marketing l'ajoute à la newsletter, un mainteneur le publie sur X. Six mois plus tard, la moitié de ces liens pointent vers un fichier qui n'existe plus et aucun ne vous a rien appris. Pour raccourcir correctement les liens des notes de version, il vous faut trois choses : un lien court stable vers la "latest" que vous repointez à chaque version, un lien balisé distinct par canal pour chaque version, et un workflow déclenché par l'événement release: published qui crée les deux afin que personne n'ait à s'en souvenir.

C'est toute la réponse. La suite de cet article explique comment relier tout cela sans créer de désordre, et ce que les données de clics peuvent ou ne peuvent pas vous apprendre ensuite.

J'ai vu beaucoup de projets gérer manuellement les liens des notes de version GitHub, et le scénario d'échec est toujours le même : quelqu'un crée un lien vers un artefact versionné, le lien est cité dans un fil de forum ou une réponse Stack Overflow, puis la version suivante le laisse silencieusement orphelin. Si vous gérez déjà vos liens comme du code, l'approche ci-dessous s'intègre à côté des liens courts gérés dans Terraform, à ceci près que les liens de version changent selon un calendrier que vous ne contrôlez pas manuellement.

Pourquoi les liens des notes de version deviennent obsolètes et perdent leur attribution

Deux problèmes distincts se cachent ici. Ils nécessitent des corrections différentes.

Le premier est l'obsolescence des liens. GitHub vous fournit des URL stables pour la page de la version (/releases/latest) et pour les fichiers, via /releases/latest/download/asset-name, mais la seconde ne fonctionne que si l'artefact conserve un nom identique d'une version à l'autre, comme l'indique la documentation GitHub sur les liens vers les versions. La plupart des pipelines de build inscrivent la version dans le nom de fichier : app-2.3.0.dmg devient donc app-2.4.0.dmg, et l'URL de téléchargement "latest" qui fonctionnait la semaine dernière renvoie maintenant une 404. Les liens de documentation deviennent eux aussi obsolètes lorsqu'un site de documentation est réorganisé. Les tendances générales sont décrites dans notre stratégie de prévention de l'obsolescence des liens ; les notes de version sont simplement l'endroit où le problème frappe le plus fort, parce que les liens voyagent le plus loin.

Le deuxième problème est l'attribution, et il est plus discret. L'API REST de GitHub fournit bien un download_count pour chaque artefact de version, ce qui est déjà plus que ce que la plupart des gens réalisent. En revanche, elle n'indique pas d'où vient le téléchargement. Un pic de 4 000 téléchargements le lendemain de la sortie peut venir de la newsletter, d'un fil Hacker News ou du CI d'un seul client professionnel qui récupère le binaire en boucle. Les liens collés dans Slack et les messages privés suppriment entièrement le référent : c'est le problème de l'attribution sociale obscure en miniature.

Un lien stable vers la dernière version à repointer à chaque version

Créez un lien court, par exemple get.example.dev/latest, et traitez-le comme un pointeur. Chaque page de documentation, badge de README et script d'installation l'utilise. À chaque version stable, vous mettez à jour sa destination. Le slug ne change jamais, donc rien de ce qui le cite ne casse.

Dans Elido, ce pointeur est un lien ordinaire. Vous le créez une fois avec POST /v1/workspaces/{workspace_id}/links, en transmettant le domain_id de votre domaine de marque, le slug et la destination_url. Enregistrez l'id de la réponse 201. Le repointage consiste en un PATCH /v1/workspaces/{workspace_id}/links/{link_id} avec une nouvelle destination_url et rien d'autre ; le slug, les tags et l'historique des clics restent inchangés.

Gardez une 302. Les liens Elido utilisent par défaut une 302, et il y a une raison de ne pas changer cela ici : une 301 est normalement mise en cache conformément à la RFC 9110, si bien qu'un navigateur qui a vu la redirection du mois dernier peut ne plus jamais la demander. Un pointeur dont les navigateurs se souviennent pour toujours n'est plus un pointeur. Pour en savoir plus, consultez 301 contre 302 pour les liens courts.

Décidez d'une chose dès le départ. Le lien vers la dernière version doit-il pointer vers le fichier ou vers la page de la version ? Je le ferais pointer vers la page de la version dès qu'il existe plusieurs builds pour différentes plateformes, et je ne garderais des liens vers la dernière version par plateforme (/latest-mac, /latest-linux) que si votre documentation d'installation a réellement besoin d'un fichier direct. Moins il y a de pointeurs mobiles, moins vous risquez de mal les repointer.

Balisage par version des liens des notes de version GitHub

Le lien vers la dernière version répond à la question « le lien fonctionne-t-il toujours ? ». Il ne peut pas répondre à « quel canal a fonctionné ? », car tout le monde clique sur le même slug. Pour cela, chaque version reçoit son propre petit ensemble de liens, un par canal, créés au moment de la publication.

Voici la partie que la plupart des guides sur les UTM omettent. Ajouter utm_source=slack à une URL github.com ne sert à rien, car vous ne verrez jamais les statistiques de GitHub. Les UTM ne sont utiles que lorsque la destination est un site que vous mesurez, comme votre documentation ou votre propre page de téléchargement. Lorsque la destination est GitHub, le lien court distinct par canal fournit l'attribution : le clic est comptabilisé lors de la redirection, avant même que GitHub ne le voie.

Balisez chaque lien propre à une version avec la version et le canal (["release", "v2.4.0", "slack"]), car les tags vous permettent de retrouver l'ensemble plus tard : GET .../links?tags=v2.4.0 liste tout ce qui concerne une version. Gardez des valeurs UTM simples et identiques d'une version à l'autre. Le guide des conventions de nommage UTM contient les règles que je suivrais.

Créer des liens lors de l'événement de publication d'une version

Un guide connexe couvre la création générique de liens dans le CI ; cette section reste donc centrée sur les aspects propres aux versions. Le déclencheur est release avec le type d'activité published. Selon la liste des événements de workflow GitHub, published se déclenche aussi bien pour les versions stables que pour les préversions, y compris les préversions publiées à partir d'un brouillon, ce qui explique précisément pourquoi l'étape de repointage vérifie le drapeau 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}')"

Le résumé du job fournit à la personne qui publie l'annonce une liste de liens prête à l'emploi, et un 409 lors d'une nouvelle exécution signifie que le slug existe déjà : un workflow relancé n'échoue donc pas et ne crée pas de doublon. Le lien de la newsletter pointerait vers votre documentation avec des UTM dans la destination ; je l'ai laissé pointer vers la page de la version ici pour que l'exemple reste court.

Trois pièges qui m'ont coûté un après-midi

Le premier est silencieux. Si votre pipeline de version publie la version avec le GITHUB_TOKEN par défaut, ce workflow ne s'exécute jamais, car les événements créés avec GITHUB_TOKEN ne déclenchent pas de nouvelles exécutions de workflow. Aucune erreur, aucun job ignoré, rien. Publiez plutôt avec un jeton d'application GitHub.

Deuxièmement, les points. Je convertis v2.4.0 en v2-4-0 pour le slug, car les chaînes de version contenant des points ressemblent à des extensions de fichier dans les aperçus de discussion, et certains clients les transforment en liens de manière étrange.

Troisièmement, ne laissez pas le workflow modifier le corps de la version sauf si vous y êtes obligé. Cela fonctionne (gh release edit --notes-file), mais le texte qu'une personne vient d'approuver est réécrit, et des événements edited sont déclenchés, auxquels d'autres automatisations peuvent réagir. Le résumé de l'étape est moins astucieux et bien plus sûr. Les nouvelles tentatives ont leur propre article : limites de débit de l'API et idempotence.

Si vous collez encore les liens de version à la main, le workflow ci-dessus demande environ vingt minutes de configuration. Commencez avec un espace de travail Elido gratuit, associez-y un domaine de marque et laissez le prochain tag créer ses propres liens.

Comment suivre les clics sur les notes de version par canal

Après deux ou trois versions, les données commencent à répondre aux questions auxquelles le compteur de GitHub ne peut pas répondre.

La comparaison par canal est la plus simple. Récupérez les liens balisés avec une version, puis lisez le résumé des clics de chaque lien en le limitant par link_id. Si v2-4-0-news devance v2-4-0-social de cinq pour un pendant trois versions consécutives, vous avez appris où se trouvent réellement vos utilisateurs, et c'est rarement là où l'équipe le pensait. L'annonce qui recueille le plus de mentions « J'aime » n'est souvent pas celle qui envoie le plus de personnes vers le téléchargement ; attendez-vous donc à des objections la première fois que vous montrez les chiffres, et attendez la troisième version consécutive avant que quelqu'un ne réécrive le plan de lancement en fonction d'eux.

Le lien vers la dernière version cache une astuce moins évidente. Chaque clic enregistre la destination vers laquelle il a été résolu à cet instant, si bien que la ventilation des statistiques par destination, limitée au lien vers la dernière version, répartit son trafic par version. Après un repointage, vous pouvez voir la part de l'ancienne destination diminuer et observer combien de temps des retardataires continuent d'arriver depuis des pages mises en cache et d'anciens favoris. Voilà votre véritable courbe d'adoption, mesurée en haut du tunnel.

Deux limites honnêtes. Les clics ne sont pas des téléchargements : quelqu'un peut accéder à la page de la version puis repartir, et le download_count de GitHub reste la source de vérité pour les récupérations terminées. De plus, les robots cliquent sur les liens de version, en particulier les récupérateurs d'aperçus de liens dans les applications de discussion ; étudiez donc les tendances sur plusieurs versions plutôt que de faire confiance à une seule journée. La page de la fonctionnalité de statistiques indique quelles ventilations sont disponibles avec chaque formule.

Garder les anciens liens de version actifs

Les liens propres à chaque version ne bougent jamais. v2-3-0-slack pointe vers le tag v2.3.0 en mars et y pointe toujours cinq ans plus tard, ce qu'attend une personne qui lit un ancien fil de forum. Seul le lien vers la dernière version change, et uniquement pour les versions stables.

Le seul cas où vous devriez modifier un ancien lien est celui d'une version retirée. Si v2.4.0 est publiée avec un bug entraînant une perte de données, ne supprimez pas ses liens ; repointez chaque lien v2-4-0-* vers v2.4.1 avec le même appel PATCH et une courte note dans le corps de la version. Supprimer ces liens conduit les personnes qui les ont enregistrés dans une impasse précisément au moment où elles ont le plus besoin du correctif. Une version plus récente vaut mieux qu'une 404. À chaque fois.

Pour les projets qui conservent également d'anciens liens de version dans leurs README, leurs scripts d'installation et les métadonnées des gestionnaires de paquets, le guide des raccourcisseurs d'URL destiné aux développeurs explique où les liens courts sont encore utiles. L'ensemble de l'API REST est présenté sur la page API et SDK.

Lire le contenu pilier → Gérer vos liens courts comme du Terraform

Articles associés sur le blog

• Stratégie de prévention de l'obsolescence des liens - le guide général pour les liens qui doivent survivre à la page vers laquelle ils pointent.
• Démarrage rapide de l'API de raccourcisseur d'URL - authentification, SDK et appel de création utilisés dans le workflow.
• CLI du raccourcisseur d'URL - les mêmes opérations depuis un terminal, pour les versions ponctuelles.
• Bot Slack de raccourcissement d'URL - raccourcir les liens là où l'annonce de version arrive réellement.
• 301 contre 302 - pourquoi un lien que l'on peut repointer doit rester temporaire.
• Liens courts depuis GitHub Actions - l'étape générique de création ou de mise à jour pour n'importe quel workflow.