Changesets ile Monorepo Yönetimi

Changesets, monorepolarda birbirine bağlı paketlerin sürümlerini ve değişiklik günlüklerini (CHANGELOG) yöneten bir araç. Kendi tanımıyla: “A tool to manage versioning and changelogs with a focus on multi-package repositories.”

Tek paketli bir projede sürüm numarasını elle artırmak idare eder. Ama on paketin birbirine bağımlı olduğu bir monorepoda, bir pakette yapılan değişikliğin hangi paketlerin sürümünü etkilediğini takip etmek hızla içinden çıkılmaz hale gelir. Changesets bu takibi değişikliği yapan kişiye, değişikliği yaptığı anda yaptırır.

#Nasıl çalışır?

Her değişiklikle birlikte .changeset klasörüne küçük bir Markdown dosyası eklenir. Bu dosya hangi paketlerin etkilendiğini, her birinin Semantic Versioning’e göre ne kadar artacağını (patch, minor, major) ve değişikliğin kısa açıklamasını içerir. Sürüm çıkarma zamanı geldiğinde birikmiş dosyalar birleştirilir, sürümler artırılır ve günlükler kendiliğinden yazılır.

#Kurulum

npm install --save-dev @changesets/cli
npx changeset init

init komutu .changeset klasörünü ve config.json dosyasını oluşturur. Paketleriniz npm’de herkese açık yayımlanacaksa "access": "public" ayarını yapın; birlikte sürüm alması gereken paketleri fixed ya da linked ile gruplayabilirsiniz.

#Günlük iş akışı

Bir değişikliği bitirdiğinizde, commit’ten önce:

npx changeset

Komut size hangi paketleri değiştirdiğinizi, her birinin ne kadar artacağını ve değişikliğin özetini sorar, sonra şöyle bir dosya üretir:

---
'@acme/ui': minor
'@acme/forms': patch
---

Button bileşenine loading durumu eklendi.

Bu dosya kodla birlikte aynı pull request’te commit’lenir. Böylece inceleme yapan kişi, değişikliğin hangi paketleri ve nasıl etkilediğini de görür.

#Sürüm çıkarmak ve yayımlamak

npx changeset version
npx changeset publish

version birikmiş changeset dosyalarını tüketir, package.json sürümlerini artırır, bağımlı paketlerin sürüm aralıklarını günceller ve her paketin CHANGELOG.md dosyasını yazar. publish ise sürümü değişen paketleri npm’e yayımlar ve git etiketlerini oluşturur.

#GitHub Actions ile otomatik yayın

Ana dala birleşen changeset’ler için changesets/action bir “Version Packages” pull request’i açar ve onu güncel tutar. Bu PR birleştirildiğinde paketler otomatik yayımlanır:

name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - uses: changesets/action@v1
        with:
          publish: npx changeset publish
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Sonuç olarak sürüm numarası artık bir kişinin hafızasına bağlı değil: her değişiklik kendi açıklamasıyla gelir, sürümler ve günlükler bu açıklamalardan üretilir.

#Güncelleme notu

Bu yazının ilk hali 2023’te Medium’da yayımlandı ve “devam edecek” notuyla yarım kalmıştı. Burada kurulum, günlük iş akışı, sürüm çıkarma ve CI ile otomatik yayın bölümlerini ekleyerek tamamladım.