Accorciare i link nelle note di rilascio e tracciare ogni download

Le note di rilascio viaggiano più lontano di quasi tutto ciò che scrive un team di ingegneria. Nessuno le misura. Incolli un link di download nel corpo della release, qualcuno lo copia in Slack, il marketing lo inserisce nella newsletter, un maintainer lo pubblica su X. Sei mesi dopo, metà di quei link punta a un file che non esiste più e nessuno ti ha detto nulla. Per accorciare bene i link nelle note di rilascio servono tre cose: un link breve stabile all'ultima versione da ripuntare a ogni release, un link taggato separato per canale per ogni versione e un workflow sull'evento release: published che li crei entrambi, così nessuno deve ricordarsene.

Questa è tutta la risposta. Il resto dell'articolo spiega come collegare il tutto senza creare confusione e che cosa i dati sui clic possono e non possono dirti in seguito.

Ho visto molti progetti gestire manualmente i link delle note di rilascio di GitHub, e il problema è sempre lo stesso: qualcuno collega un asset versionato, il link viene citato in una discussione su un forum o in una risposta di Stack Overflow, e la release successiva lo lascia silenziosamente orfano. Se gestisci già i link come codice, l'approccio qui sotto si affianca ai link brevi gestiti in Terraform, con la differenza che i link delle release cambiano secondo una cadenza che non controlli manualmente.

Perché i link delle note di rilascio diventano obsoleti e perdono l'attribuzione

Qui si nascondono due problemi distinti. Servono correzioni diverse.

Il primo è il link rot. GitHub offre URL stabili per la pagina della release (/releases/latest) e per i file, tramite /releases/latest/download/asset-name, ma il secondo funziona solo quando l'asset mantiene un nome identico tra le release, secondo la documentazione di GitHub sui link alle release. La maggior parte delle pipeline di build inserisce la versione nel nome del file, così app-2.3.0.dmg diventa app-2.4.0.dmg e l'URL di download dell'"ultima versione" che funzionava la settimana scorsa ora restituisce un 404. Anche i link alla documentazione diventano obsoleti quando un sito di documentazione viene riorganizzato. I pattern più generali sono nella nostra strategia per prevenire i link obsoleti; le note di rilascio sono semplicemente il punto in cui il problema si fa sentire di più, perché i link viaggiano più lontano.

Il secondo problema è l'attribuzione, ed è più silenzioso. L'API REST di GitHub restituisce effettivamente un download_count per ogni asset della release, più di quanto molti pensino. Quello che non restituisce è l'origine del download. Un picco di 4.000 download il giorno dopo la release potrebbe provenire dalla newsletter, da una discussione su Hacker News o dalla CI di un singolo cliente enterprise che scarica il binario in ciclo continuo. I link incollati in Slack e nei messaggi diretti eliminano completamente il referrer: è il problema della dark social attribution in miniatura.

Un link stabile all'ultima versione da ripuntare a ogni release

Crea un link breve, per esempio get.example.dev/latest, e trattalo come un puntatore. Lo usano ogni pagina della documentazione, ogni badge nel README e ogni script di installazione. A ogni release stabile aggiorni la destinazione. Lo slug non cambia mai, quindi nulla di ciò che lo ha citato si rompe.

In Elido quel puntatore è un link normale. Lo crei una volta con POST /v1/workspaces/{workspace_id}/links, passando il domain_id del tuo dominio brandizzato, lo slug e la destination_url. Salva l'id della risposta 201. Ripuntare il link significa eseguire una PATCH /v1/workspaces/{workspace_id}/links/{link_id} con una nuova destination_url e nient'altro; slug, tag e cronologia dei clic restano invariati.

Mantienilo un 302. I link Elido usano 302 per impostazione predefinita, e c'è un motivo per non cambiarlo in questo caso: un 301 è memorizzabile nella cache per impostazione predefinita secondo RFC 9110, quindi un browser che ha visto il redirect del mese scorso potrebbe non chiedere mai più la destinazione. Un puntatore che i browser ricordano per sempre non è più un puntatore. Approfondisci in 301 e 302: redirect per i link brevi.

Decidi subito una cosa. Il link all'ultima versione deve puntare al file o alla pagina della release? Io lo farei puntare alla pagina della release per qualsiasi progetto con più di una build per piattaforma, e terrei link all'ultima versione per piattaforma (/latest-mac, /latest-linux) solo se la documentazione di installazione ha davvero bisogno di un file diretto. Meno puntatori mobili significano meno possibilità di ripuntare qualcosa nel posto sbagliato.

Tag per release per i link alle note di rilascio di GitHub

Il link all'ultima versione risponde alla domanda "il link funziona ancora?". Non può rispondere a "quale canale ha funzionato?", perché tutti fanno clic sullo stesso slug. Per questo ogni release riceve il proprio piccolo insieme di link, uno per canale, creati al momento della pubblicazione.

Ecco la parte che la maggior parte delle guide sugli UTM salta. Aggiungere utm_source=slack a un URL di github.com non serve a nulla, perché non vedrai mai gli analytics di GitHub. Gli UTM sono utili solo quando la destinazione è un sito che misuri, come la tua documentazione o la tua pagina di download. Quando la destinazione è GitHub, il link breve separato per canale fornisce l'attribuzione: il clic viene conteggiato al redirect, prima che GitHub lo veda.

Tagga ogni link per release con la versione e il canale (["release", "v2.4.0", "slack"]), perché è così che potrai recuperare in seguito l'insieme: GET .../links?tags=v2.4.0 elenca tutto per una release. Mantieni tutti i valori UTM semplici e identici tra le release. La guida alle convenzioni per i nomi UTM contiene le regole che userei.

Creare link sull'evento Release published

Una guida collegata tratta la creazione generica di link nella CI, quindi questa sezione resta sugli aspetti specifici delle release. Il trigger è release con il tipo di attività published. Secondo l'elenco degli eventi dei workflow di GitHub, published scatta sia per le release stabili sia per le pre-release, comprese le pre-release pubblicate da una bozza: è proprio per questo che il passaggio di ripuntamento qui sotto controlla il flag 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}')"

Il riepilogo del job offre a chi pubblica l'annuncio un elenco di link pronto all'uso, e un 409 in caso di nuova esecuzione significa che lo slug esiste già, quindi un workflow ritentato non fallisce e non duplica nulla. Il link della newsletter punterebbe alla tua documentazione con gli UTM nella destinazione; qui l'ho lasciato sulla pagina della release per mantenere breve l'esempio.

Tre insidie che mi sono costate un pomeriggio

La prima è silenziosa. Se la tua pipeline di release pubblica la release usando il GITHUB_TOKEN predefinito, questo workflow non viene mai eseguito, perché gli eventi creati con GITHUB_TOKEN non attivano nuove esecuzioni di workflow. Nessun errore, nessun job saltato, niente. Pubblica invece con un token di GitHub App.

Secondo: i punti. Converto v2.4.0 in v2-4-0 per lo slug perché le stringhe di versione con i punti sembrano estensioni di file nelle anteprime delle chat, e alcuni client le trasformano in link in modo strano.

Terzo: non lasciare che il workflow modifichi il corpo della release, a meno che sia necessario. Funziona (gh release edit --notes-file), ma riscrive un testo appena approvato da una persona e attiva eventi edited a cui potrebbero reagire altre automazioni. Il riepilogo del job è meno ingegnoso e molto più sicuro. I retry hanno un articolo dedicato: limiti di velocità e idempotenza dell'API.

Se stai ancora incollando manualmente i link delle release, il workflow qui sopra richiede circa venti minuti di configurazione. Inizia con un workspace Elido gratuito, collegaci un dominio brandizzato e lascia che il prossimo tag crei i propri link.

Come tracciare i clic sulle note di rilascio per canale

Dopo due o tre release, i dati iniziano a rispondere alle domande a cui il contatore di GitHub non sa rispondere.

Il confronto per canale è quello più semplice. Recupera i link taggati con una versione, poi leggi il riepilogo dei clic di ogni link con ambito link_id. Se v2-4-0-news supera v2-4-0-social di cinque a uno per tre release consecutive, hai capito dove si trovano davvero i tuoi utenti, e raramente è dove pensava il team. L'annuncio con più Mi piace spesso non è quello che porta persone al download, quindi aspettati resistenza la prima volta che mostri i numeri e aspetta la terza release consecutiva prima che qualcuno riscriva il piano di lancio sulla base di quei dati.

Il link all'ultima versione ha un trucco meno evidente. Ogni clic registra la destinazione a cui è stato risolto in quel momento, quindi la suddivisione degli analytics per destinazione, limitata al link all'ultima versione, separa il traffico per versione. Dopo un ripuntamento puoi osservare diminuire la quota della vecchia destinazione e vedere per quanto tempo continuano ad arrivare visitatori da pagine memorizzate nella cache e vecchi segnalibri. Questa è la tua vera curva di upgrade, misurata all'inizio del funnel.

Due limiti da riconoscere. I clic non sono download: qualcuno può fare clic fino alla pagina della release e andarsene, e il download_count di GitHub resta la fonte di verità per i download completati. Inoltre i bot fanno clic sui link delle release, soprattutto i fetcher delle anteprime dei link nelle app di chat, quindi leggi le tendenze tra le release invece di fidarti di un singolo giorno. La pagina delle funzionalità analytics elenca le suddivisioni disponibili per ogni piano.

Mantenere attivi i vecchi link delle release

I link per release non cambiano mai. v2-3-0-slack punta al tag v2.3.0 a marzo e continua a puntarci tra cinque anni, come si aspetta chi legge una vecchia discussione su un forum. Cambia solo il link all'ultima versione e solo per le release stabili.

L'unico caso in cui dovresti modificare un vecchio link è una release ritirata. Se v2.4.0 viene pubblicata con un bug che causa perdita di dati, non eliminare i suoi link; ripunta ogni link v2-4-0-* a v2.4.1 con la stessa chiamata PATCH e una breve nota nel corpo della release. Eliminare i link lascia senza uscita chi li ha salvati proprio nel momento in cui ha più bisogno della correzione. Una versione più recente è meglio di un 404. Sempre.

Per i progetti che conservano i vecchi link delle release anche nei README, negli script di installazione e nei metadati dei package manager, la guida agli shortener di URL per sviluppatori spiega dove i link brevi sono utili. L'intera superficie REST è nella pagina API e SDK.

Leggi l'articolo cornerstone → Gestisci i tuoi link brevi come Terraform

Correlati sul blog

• Strategia per prevenire i link obsoleti - il piano più ampio per i link che devono durare più a lungo della pagina a cui puntano.
• Quickstart dell'API per lo shortener di URL - autenticazione, SDK e chiamata di creazione usata nel workflow.
• CLI dello shortener di URL - le stesse operazioni da un terminale, per release occasionali.
• Bot Slack per accorciare gli URL - accorciare i link dove arriva davvero l'annuncio della release.
• 301 e 302: redirect - perché un link ripuntabile deve restare temporaneo.
• Link brevi da GitHub Actions - il passaggio generico di creazione o aggiornamento per qualsiasi workflow.