Sürüm Notlarında Bağlantıları Kısaltın, İndirmeleri Takip Edin

Sürüm notları, bir mühendislik ekibinin yazdığı hemen her şeyden daha uzağa gider. Üstelik kimse onları ölçmez. İndirme bağlantısını sürüm gövdesine yapıştırırsınız, biri Slack'e kopyalar, pazarlama bültene koyar, bir bakımcı X'te paylaşır. Altı ay sonra bu bağlantıların yarısı artık var olmayan bir dosyayı gösterir ve hiçbiri size bir şey söylememiştir. Sürüm notlarındaki bağlantıları düzgün biçimde kısaltmak için üç şeye ihtiyacınız var: her sürümde yeniden yönlendirdiğiniz tek bir sabit "latest" kısa bağlantısı, her sürüm için kanal başına etiketli ayrı bir bağlantı ve bu ikisini sizin yerinize oluşturan, release: published olayına bağlı bir iş akışı.

Cevabın tamamı bu. Yazının geri kalanı, bunu kargaşa çıkarmadan nasıl kuracağınızı ve tıklama verisinin sonradan neyi söyleyip neyi söyleyemeyeceğini anlatıyor.

GitHub sürüm notu bağlantılarını elle yöneten çok sayıda proje gördüm ve hata hep aynı: biri sürümlü bir varlığa bağlantı verir, bağlantı bir forum başlığında ya da Stack Overflow yanıtında alıntılanır, sonraki sürüm de onu sessizce sahipsiz bırakır. Bağlantıları zaten kod olarak yönetiyorsanız, aşağıdaki yaklaşım Terraform ile yönetilen kısa bağlantıların yanına oturur; tek fark, sürüm bağlantılarının elle yönetmediğiniz bir takvimle değişmesidir.

Sürüm Notu Bağlantıları Neden Çürür ve Atıfı Kaybeder

Burada iki ayrı sorun gizli. Farklı çözümler gerektirirler.

Birincisi bağlantı çürümesi. GitHub size sürüm sayfası için (/releases/latest) ve dosyalar için (/releases/latest/download/asset-name) kararlı adresler verir, ancak GitHub'ın sürümlere bağlantı belgelerine göre ikincisi yalnızca varlık sürümler arasında aynı adı koruduğunda çalışır. Çoğu derleme hattı sürümü dosya adına yazar; böylece app-2.3.0.dmg dosyası app-2.4.0.dmg olur ve geçen hafta çalışan "latest" indirme adresi artık 404 döndürür. Doküman siteleri yeniden düzenlendiğinde doküman bağlantıları da çürür. Daha geniş kalıplar bağlantı çürümesini önleme stratejimizde var; sürüm notları bunun en çok acıttığı yer, çünkü bağlantılar en uzağa onlarda gider.

İkinci sorun atıf ve daha sessiz. GitHub'ın REST API'si her sürüm varlığında bir download_count bildirir; bu, çoğu kişinin sandığından fazlasıdır. Bildirmediği şey, indirmenin nereden geldiği. Sürümden bir gün sonraki 4.000 indirmelik bir sıçrama bültenden, bir Hacker News başlığından ya da tek bir kurumsal müşterinin CI'sının ikili dosyayı döngüyle çekmesinden gelmiş olabilir. Slack'e ve DM'lere yapıştırılan bağlantılar yönlendiren bilgisini tamamen siler; bu, küçük ölçekte karanlık sosyal atıf sorunudur.

Her Sürümde Yeniden Yönlendirdiğiniz Sabit Bir Latest Bağlantısı

Tek bir kısa bağlantı oluşturun, örneğin get.example.dev/latest, ve onu bir işaretçi olarak görün. Her doküman sayfası, README rozeti ve kurulum betiği bunu kullanır. Her kararlı sürümde nereye işaret ettiğini güncellersiniz. Slug hiç değişmez, bu yüzden onu alıntılayan hiçbir şey bozulmaz.

Elido'da bu işaretçi sıradan bir bağlantıdır. Onu bir kez POST /v1/workspaces/{workspace_id}/links ile oluşturursunuz; markalı alan adınızın domain_id değerini, slug ve destination_url alanlarını verirsiniz. 201 yanıtındaki id değerini saklayın. Yeniden yönlendirme, yalnızca yeni bir destination_url içeren bir PATCH /v1/workspaces/{workspace_id}/links/{link_id} çağrısıdır; slug, etiketler ve tıklama geçmişi yerinde kalır.

Bunu 302 olarak tutun. Elido bağlantıları varsayılan olarak 302 kullanır ve bu bağlantı için bunu değiştirmemeniz için bir neden var: 301, RFC 9110 uyarınca varsayılan olarak önbelleğe alınabilir; bu yüzden geçen ayki yönlendirmeyi görmüş bir tarayıcı bir daha sormayabilir. Tarayıcıların sonsuza dek hatırladığı bir işaretçi artık işaretçi değildir. Daha fazlası kısa bağlantılar için 301 ile 302 yönlendirmeleri yazısında.

Baştan bir şeye karar verin. Latest bağlantısı dosyaya mı, sürüm sayfasına mı işaret etmeli? Birden fazla platform derlemesi olan her şey için sürüm sayfasına işaret etmesini, platform başına latest bağlantılarını (/latest-mac, /latest-linux) ise yalnızca kurulum dokümanlarınız gerçekten doğrudan dosya istiyorsa tutmasını öneririm. Daha az hareketli işaretçi, yanlış yeniden yönlendirilecek daha az şey demektir.

GitHub Sürüm Notu Bağlantıları İçin Sürüm Başına Etiketleme

Latest bağlantısı "bağlantı hâlâ çalışıyor mu" sorusunu yanıtlar. "Hangi kanal işe yaradı" sorusunu yanıtlayamaz, çünkü herkes aynı slug'a tıklar. Bunun için her sürüm, yayım anında oluşturulan, kanal başına bir bağlantıdan oluşan küçük bir set alır.

Çoğu UTM rehberinin atladığı kısım şu: bir github.com adresine utm_source=slack eklemek işe yarar bir şey yapmaz, çünkü GitHub'ın analitiğini hiç görmeyeceksiniz. UTM'ler yalnızca hedef, ölçtüğünüz bir site olduğunda, örneğin dokümanlarınız ya da kendi indirme sayfanız için yerini hak eder. Hedef GitHub olduğunda atıf, kanal başına ayrı kısa bağlantıdır: tıklama, GitHub onu görmeden önce yönlendirmede sayılır.

Her sürüm bağlantısını sürüm ve kanalla etiketleyin (["release", "v2.4.0", "slack"]); çünkü etiketler seti sonradan geri çekmenin yoludur: GET .../links?tags=v2.4.0 bir sürümün tüm bağlantılarını listeler. UTM değerlerini sıkıcı ve sürümler arasında aynı tutun. UTM adlandırma kuralları rehberi, kopyalayacağım kuralları içeriyor.

Release Published Olayında Bağlantı Oluşturma

Kardeş bir rehber genel CI bağlantısı oluşturmayı ele alıyor; bu bölüm yalnızca sürüme özgü kısımlarda kalıyor. Tetikleyici, published etkinlik türüne sahip release olayıdır. GitHub'ın iş akışı olayları listesine göre published, kararlı sürümlerde ve taslaktan yayımlananlar dahil ön sürümlerde de çalışır; aşağıdaki yeniden yönlendirme adımının prerelease bayrağını neden kontrol ettiği tam da budur.

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}')"

İş özeti, duyuruyu paylaşacak kişiye hazır bir bağlantı listesi verir; yeniden çalıştırmada 409 ise slug'ın zaten var olduğu anlamına gelir, yani yeniden denenen bir iş akışı ne başarısız olur ne de kopya üretir. Bülten bağlantısı, hedefte UTM'lerle dokümanlarınıza işaret ederdi; örneği kısa tutmak için burada sürüm sayfasında bıraktım.

Bana bir öğleden sonraya mal olan üç tuzak

İlki sessiz. Sürüm hattınız sürümü varsayılan GITHUB_TOKEN ile yayımlıyorsa bu iş akışı hiç çalışmaz, çünkü GITHUB_TOKEN ile oluşturulan olaylar yeni iş akışı çalıştırmalarını tetiklemez. Hata yok, atlanan iş yok, hiçbir şey yok. Bunun yerine bir GitHub App belirteciyle yayımlayın.

İkincisi, noktalar. Slug için v2.4.0 ifadesini v2-4-0 yapıyorum, çünkü noktalı sürüm dizeleri sohbet önizlemelerinde dosya uzantısı gibi görünür ve bazı istemciler onları tuhaf biçimde bağlantıya çevirir.

Üçüncüsü, kesin gerekmedikçe iş akışının sürüm gövdesini düzenlemesine izin vermeyin. Çalışır (gh release edit --notes-file), ama bir insanın az önce onayladığı metni yeniden yazar ve diğer otomasyonların tepki verebileceği edited olaylarını tetikler. Adım özeti daha az zekice ama çok daha güvenli. Yeniden denemelerin kendi yazısı var: API hız sınırları ve idempotency.

Sürüm bağlantılarını hâlâ elle yapıştırıyorsanız, yukarıdaki iş akışı yaklaşık yirmi dakikalık bir kurulumdur. Ücretsiz bir Elido çalışma alanı başlatın, ona markalı bir alan adı bağlayın ve bir sonraki etiketin kendi bağlantılarını oluşturmasına izin verin.

Sürüm Notlarındaki Tıklamaları Kanala Göre Takip Etme

İki üç sürümden sonra veri, GitHub'ın sayacının yanıtlayamadığı sorulara yanıt vermeye başlar.

Kanallar arası karşılaştırma en basiti. Bir sürümle etiketlenmiş bağlantıları çekin, sonra her bağlantının tıklama özetini link_id ile daraltarak okuyun. v2-4-0-news üst üste üç sürüm boyunca v2-4-0-social bağlantısını beşe bir geçiyorsa, kullanıcılarınızın gerçekte nerede olduğunu öğrenmişsinizdir; bu çoğu zaman ekibin varsaydığı yer değildir. En çok beğeni alan duyuru, indirmeye en çok insan gönderen duyuru olmayabilir; bu yüzden sayıları ilk gösterdiğinizde itiraz bekleyin ve kimse lansman planını bunlara göre yeniden yazmadan önce arka arkaya üçüncü sürümü bekleyin.

Latest bağlantısının daha az bariz bir hilesi var. Her tıklama, o anda çözümlediği hedefi kaydeder; bu yüzden latest bağlantısıyla sınırlı, hedefe göre analitik dökümü trafiğini sürüme göre böler. Yeniden yönlendirmeden sonra eski hedefin payının düştüğünü ve gecikenlerin önbelleğe alınmış sayfalarda ve eski yer imlerinde ne kadar süre gelmeye devam ettiğini izleyebilirsiniz. Bu, huninin tepesinde ölçülen gerçek yükseltme eğrinizdir.

İki dürüst sınır. Tıklamalar indirme değildir: biri sürüm sayfasına tıklayıp çıkabilir ve tamamlanan indirmeler için gerçeğin kaynağı GitHub'ın download_count değeri olmaya devam eder. Ayrıca botlar sürüm bağlantılarına tıklar, özellikle sohbet uygulamalarındaki bağlantı önizleme çekicileri; bu yüzden tek bir güne güvenmek yerine sürümler arası eğilimleri okuyun. Analitik özellik sayfası hangi dökümlerin hangi planda bulunduğunu listeler.

Eski Sürüm Bağlantılarını Canlı Tutmak

Sürüm başına bağlantılar asla yer değiştirmez. v2-3-0-slack mart ayında v2.3.0 etiketine işaret eder ve beş yıl sonra hâlâ oraya işaret eder; eski bir forum başlığını okuyan birinin beklediği de budur. Yalnızca latest bağlantısı değişir, o da yalnızca kararlı sürümlerde.

Eski bir bağlantıya dokunmanız gereken tek durum geri çekilmiş bir sürümdür. v2.4.0 bir veri kaybı hatasıyla çıkarsa bağlantılarını silmeyin; her v2-4-0-* bağlantısını aynı PATCH çağrısıyla v2.4.1'e yönlendirin ve sürüm gövdesine kısa bir not ekleyin. Silmek, bağlantıyı kaydeden kişilere düzeltmeye en çok ihtiyaç duydukları anda çıkmaz sokak verir. Daha yeni bir sürüm, 404'ten iyidir. Her seferinde.

Eski sürüm bağlantılarını README'lerde, kurulum betiklerinde ve paket yöneticisi meta verilerinde de tutan projeler için, geliştiricilere yönelik URL kısaltıcı rehberi kısa bağlantıların başka nerelerde işe yaradığını anlatır. REST yüzeyinin tamamı API ve SDK sayfasında.

Temel yazıyı okuyun → Kısa bağlantılarınızı Terraform ile yönetin

Blogda İlgili Yazılar

• Bağlantı çürümesini önleme stratejisi - işaret ettiği sayfadan uzun yaşaması gereken bağlantılar için daha geniş rehber.
• URL kısaltıcı API hızlı başlangıcı - iş akışında kullanılan kimlik doğrulama, SDK'lar ve oluşturma çağrısı.
• URL kısaltıcı CLI - tek seferlik sürümler için aynı işlemler bir terminalden.
• Slack URL kısaltıcı botu - sürüm duyurusunun gerçekten ulaştığı yerde bağlantı kısaltma.
• 301 ve 302 yönlendirmeleri - yeniden yönlendirilebilir bir bağlantının neden geçici kalması gerektiği.
• GitHub Actions ile kısa bağlantılar - her iş akışı için genel oluştur ya da güncelle adımı.