Скорочуйте посилання в нотатках до випусків і відстежуйте кожне завантаження

Нотатки до випусків поширюються далі, ніж майже все, що пише команда розробників. Ніхто їх не вимірює. Ви вставляєте посилання на завантаження в опис випуску, хтось копіює його у Slack, маркетинг додає його до розсилки, а мейнтейнер публікує його в X. Через шість місяців половина цих посилань веде на файл, якого вже не існує, і жодне не розповіло вам нічого. Щоб правильно скорочувати посилання в нотатках до випусків, потрібні три речі: одне стабільне коротке посилання «latest», яке ви перенаправляєте під час кожного випуску, окреме посилання з мітками для кожного каналу в кожній версії та робочий процес на події release: published, який створює їх обидва, щоб нікому не доводилося про це пам'ятати.

Ось і вся відповідь. Решта цієї статті присвячена тому, як під'єднати все це без безладу та що саме дані про кліки можуть і не можуть розповісти вам потім.

Я бачив, як багато проєктів вручну працюють із посиланнями в нотатках до випусків GitHub, і причина збоїв завжди однакова: хтось посилається на ресурс із номером версії, посилання цитують у дописі на форумі або у відповіді Stack Overflow, а наступний випуск непомітно залишає його без власника. Якщо ви вже керуєте посиланнями як кодом, описаний нижче підхід добре поєднується з короткими посиланнями під керуванням Terraform, з тією відмінністю, що посилання на випуски змінюються за розкладом, яким ви не керуєте вручну.

Чому посилання в нотатках до випусків застарівають і втрачають атрибуцію

Тут приховано дві окремі проблеми. Для них потрібні різні виправлення.

Перша - застарівання посилань. GitHub надає стабільні URL для сторінки випуску (/releases/latest) і для файлів через /releases/latest/download/asset-name, але другий варіант працює лише тоді, коли ресурс має ідентичну назву в усіх випусках, як зазначено в офіційній документації GitHub про посилання на випуски. Більшість конвеєрів збірки додають версію до назви файлу, тож app-2.3.0.dmg перетворюється на app-2.4.0.dmg, і URL завантаження «latest», який працював минулого тижня, тепер повертає 404. Посилання на документацію теж застарівають, коли сайт документації реорганізовують. Ширші закономірності описано в нашій стратегії запобігання застаріванню посилань; нотатки до випусків - лише місце, де проблема болить найсильніше, бо посилання поширюються найдалі.

Друга проблема - атрибуція, і вона тихіша. REST API GitHub справді повертає download_count для кожного ресурсу випуску, що важливіше, ніж усвідомлює більшість людей. Але він не повідомляє, звідки надійшло завантаження. Сплеск у 4 000 завантажень наступного дня після випуску міг бути спричинений розсилкою, дописом на Hacker News або CI одного корпоративного клієнта, який циклічно завантажує двійковий файл. Посилання, вставлені у Slack і приватні повідомлення, повністю втрачають джерело переходу, що є мініатюрною версією проблеми атрибуції темних соціальних каналів.

Стабільне посилання на останню версію, яке ви перенаправляєте для кожного випуску

Створіть одне коротке посилання, скажімо get.example.dev/latest, і ставтеся до нього як до вказівника. Його використовуватимуть кожна сторінка документації, бейдж README та скрипт інсталяції. Під час кожного стабільного випуску ви оновлюєте адресу, на яку воно вказує. Слаг ніколи не змінюється, тож ніщо з того, де його процитували, не зламається.

У Elido цей вказівник є звичайним посиланням. Ви створюєте його один раз за допомогою POST /v1/workspaces/{workspace_id}/links, передаючи domain_id вашого брендованого домену, slug і destination_url. Збережіть id із відповіді 201. Перенаправлення - це PATCH /v1/workspaces/{workspace_id}/links/{link_id} із новим destination_url і нічим іншим; слаг, мітки та історія кліків залишаються на місці.

Залиште 302. Посилання Elido за замовчуванням використовують 302, і для цього є причина: 301 за замовчуванням можна кешувати відповідно до RFC 9110, тож браузер, який побачив перенаправлення минулого місяця, може більше ніколи не запитати його знову. Вказівник, який браузери пам'ятають назавжди, більше не є вказівником. Докладніше - у статті Перенаправлення 301 і 302 для коротких посилань.

Заздалегідь вирішіть одну річ. Чи має посилання на останню версію вести до файлу чи до сторінки випуску? Я б вів його на сторінку випуску для всього, що має більше ніж одну збірку для платформи, а окремі посилання на останню версію для платформ (/latest-mac, /latest-linux) залишив би лише тоді, коли вашій документації з інсталяції справді потрібен прямий файл. Що менше вказівників переміщується, то менше шансів неправильно перенаправити щось.

Мітки окремих випусків для посилань у нотатках до випусків GitHub

Посилання на останню версію відповідає на запитання «чи досі працює посилання». Воно не може відповісти, «який канал спрацював», бо всі натискають той самий слаг. Для цього кожен випуск під час публікації отримує власний невеликий набір посилань, по одному на канал.

Ось частину, яку пропускає більшість посібників з UTM. Додавання utm_source=slack до URL github.com не дає нічого корисного, бо ви ніколи не побачите аналітику GitHub. UTM мають сенс лише тоді, коли призначенням є сайт, який ви вимірюєте, наприклад ваша документація або власна сторінка завантаження. Коли призначенням є GitHub, окреме коротке посилання для кожного каналу і є атрибуцією: клік підраховується під час перенаправлення, ще до того, як його побачить GitHub.

Позначайте кожне посилання окремого випуску версією та каналом (["release", "v2.4.0", "slack"]), бо саме за мітками ви зможете згодом знову отримати цей набір: GET .../links?tags=v2.4.0 перелічує все для одного випуску. Зберігайте будь-які значення UTM простими й однаковими між випусками. У посібнику з угод щодо назв UTM є правила, які я б скопіював.

Створення посилань на події публікації випуску

У суміжному посібнику описано загальне створення посилань у CI, тож цей розділ зосереджується на частинах, специфічних для випусків. Тригером є release з типом активності published. Згідно зі списком подій робочих процесів GitHub, published спрацьовує як для стабільних випусків, так і для попередніх випусків, включно з попередніми випусками, опублікованими з чернетки. Саме тому крок перенаправлення нижче перевіряє прапорець 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}')"

Підсумок завдання дає тому, хто публікує оголошення, готовий список посилань, а 409 під час повторного запуску означає, що слаг уже існує, тож повторно запущений робочий процес не завершується помилкою й не створює дублікати. Посилання для розсилки мало б вести на вашу документацію з UTM у призначенні; тут я залишив його на сторінці випуску, щоб приклад був коротким.

Три підводні камені, які коштували мені цілого дня

Перший - непомітний. Якщо ваш конвеєр випуску публікує випуск за допомогою стандартного GITHUB_TOKEN, цей робочий процес ніколи не запускається, оскільки події, створені за допомогою GITHUB_TOKEN, не запускають нові робочі процеси. Немає помилки, пропущеного завдання чи чогось іншого. Натомість публікуйте за допомогою токена GitHub App.

Другий - крапки. Я перетворюю v2.4.0 на v2-4-0 для слага, бо рядки версій із крапками у попередньому перегляді чатів схожі на розширення файлів, а деякі клієнти дивно перетворюють їх на посилання.

Третій - не дозволяйте робочому процесу редагувати тіло випуску, якщо це не обов'язково. Це працює (gh release edit --notes-file), але переписує текст, який щойно затвердила людина, і створює події edited, на які можуть реагувати інші автоматизації. Підсумок кроку менш хитрий і значно безпечніший. Повторні спроби мають власну статтю: ліміти швидкості API та ідемпотентність.

Якщо ви досі вставляєте посилання на випуски вручну, описаний вище робочий процес потребує близько двадцяти хвилин налаштування. Створіть безкоштовний робочий простір Elido, спрямуйте на нього брендований домен і дозвольте наступній мітці створити власні посилання.

Як відстежувати кліки в нотатках до випусків за каналами

Після двох або трьох випусків дані починають відповідати на запитання, на які лічильник GitHub не може.

Порівняння каналів - найпростіший випадок. Отримайте посилання з мітками версії, а потім прочитайте зведення кліків кожного посилання в області link_id. Якщо v2-4-0-news перевершує v2-4-0-social у п'ять разів протягом трьох випусків поспіль, ви дізналися, де насправді перебувають ваші користувачі, і це рідко те місце, яке припускала команда. Оголошення з найбільшою кількістю вподобань часто не є тим, що надсилає людей на завантаження, тож очікуйте спротиву, коли вперше покажете цифри, і дочекайтеся третього випуску поспіль, перш ніж хтось перепише план запуску на їхній основі.

Посилання на останню версію має менш очевидний трюк. Кожен клік записує призначення, до якого воно на той момент перейшло, тож розподіл аналітики за призначенням у межах посилання на останню версію розділяє його трафік за версіями. Після перенаправлення ви можете спостерігати, як частка старого призначення зменшується, і бачити, як довго поодинокі користувачі продовжують приходити зі сторінок у кеші та старих закладок. Це ваша реальна крива оновлення, виміряна на верхньому рівні воронки.

Два чесні обмеження. Кліки - це не завантаження: хтось може перейти на сторінку випуску й піти, а download_count GitHub залишається джерелом правди для завершених отримань. Крім того, боти натискають посилання на випуски, особливо засоби отримання попереднього перегляду посилань у чатах, тож аналізуйте тенденції між випусками, а не довіряйте одному дню. На сторінці функції аналітики перелічено доступні на кожному плані розподіли.

Як зберігати старі посилання на випуски активними

Посилання окремих випусків ніколи не переміщуються. v2-3-0-slack у березні веде на мітку v2.3.0 і через п'ять років усе ще веде туди, чого й очікує людина, яка читає старий допис на форумі. Змінюється лише посилання на останню версію і лише для стабільних випусків.

Єдиний випадок, коли варто змінити старе посилання, - відкликаний випуск. Якщо v2.4.0 вийшов із помилкою, що призводить до втрати даних, не видаляйте його посилання; перенаправте кожне посилання v2-4-0-* на v2.4.1 тим самим викликом PATCH і додайте коротку примітку до опису випуску. Видалення залишає людей, які зберегли посилання, у глухому куті саме в той момент, коли виправлення їм найбільше потрібне. Новіша версія краща за 404. Завжди.

Для проєктів, які також зберігають старі посилання на випуски в README, скриптах інсталяції та метаданих менеджера пакунків, посібник зі скорочувачів URL для розробників розповідає, де ще короткі посилання корисні. Повний набір REST-можливостей описано на сторінці API та SDK.

Читайте наріжну статтю → Керуйте короткими посиланнями як Terraform

Пов'язані матеріали в блозі

• Стратегія запобігання застаріванню посилань - ширший план дій для посилань, які мають пережити сторінку, на яку вони ведуть.
• Швидкий старт з API скорочувача URL - автентифікація, SDK і виклик створення, використаний у робочому процесі.
• CLI скорочувача URL - ті самі операції з термінала для окремих випусків.
• Бот Slack для скорочення URL - скорочення посилань там, де насправді з'являється оголошення про випуск.
• Перенаправлення 301 і 302 - чому посилання, яке можна перенаправляти, має залишатися тимчасовим.
• Короткі посилання з GitHub Actions - загальний крок створення або оновлення для будь-якого робочого процесу.