Changelog Generator

Tier: POWERFUL
Category: Engineering
Domain: Release Management / Documentation

Overview

Bu beceriyi, Conventional Commits'ten tutarlı ve denetlenebilir sürüm notları üretmek için kullanın. Commit ayrıştırma, semantic bump mantığı ve changelog işlemesini ayırarak, takımlar sürümleri otomatikleştirirken editoryal kontrolü kaybetmemesini sağlar.

Core Capabilities

• Conventional Commit kurallarını kullanarak commit mesajlarını ayrıştırma
• Commit akışından semantic bump (major, minor, patch) algılama
• Keep a Changelog bölümlerini (Added, Changed, Fixed, vb.) işleme
• Git aralıklarından veya sağlanan commit girdisinden sürüm girdileri oluşturma
• Dedicated linter scripti ile commit formatını uygulama
• Machine-readable JSON çıkışı aracılığıyla CI entegrasyonunu destekleme

When to Use

• Bir sürüm etiketi yayınlamadan önce
• CI sırasında sürüm notlarını otomatik olarak oluşturmak için
• PR kontrolleri sırasında geçersiz commit mesajı formatlarını engellemek için
• Paket changeloglarının kapsamlı filtrelemeyi gerektiren monorepolarda
• Ham git geçmişini kullanıcı tarafından görülecek notlara dönüştürürken

Key Workflows

1. Git'ten Changelog Entry'si Oluşturma

python3 scripts/generate_changelog.py \
  --from-tag v1.3.0 \
  --to-tag v1.4.0 \
  --next-version v1.4.0 \
  --format markdown

2. stdin/Dosya Girdisinden Entry Oluşturma

git log v1.3.0..v1.4.0 --pretty=format:'%s' | \
  python3 scripts/generate_changelog.py --next-version v1.4.0 --format markdown

python3 scripts/generate_changelog.py --input commits.txt --next-version v1.4.0 --format json

3. CHANGELOG.md Güncelleme

python3 scripts/generate_changelog.py \
  --from-tag v1.3.0 \
  --to-tag HEAD \
  --next-version v1.4.0 \
  --write CHANGELOG.md

4. Merge'den Önce Commit'leri Lint Etme

python3 scripts/commit_linter.py --from-ref origin/main --to-ref HEAD --strict --format text

Veya dosya/stdin:

python3 scripts/commit_linter.py --input commits.txt --strict
cat commits.txt | python3 scripts/commit_linter.py --format json

Conventional Commit Kuralları

Desteklenen türler:

• feat, fix, perf, refactor, docs, test, build, ci, chore
• security, deprecated, remove

Breaking changes:

• type(scope)!: summary
• Footer/body içinde BREAKING CHANGE:

SemVer eşlemesi:

• breaking -> major
• non-breaking feat -> minor
• diğerleri -> patch

Script Interfaces

• python3 scripts/generate_changelog.py --help
  • Git veya stdin/--input öğesinden commit'leri okur
  • Markdown veya JSON işler
  • İsteğe bağlı yerinde changelog prepend işlemi
• python3 scripts/commit_linter.py --help
  • Commit formatını doğrular
  • --strict modunda ihlaller için sıfır olmayan değer döndürür

Common Pitfalls

1. Merge commit mesajlarını sürüm commit ayrıştırması ile karıştırma
2. Sürüm notları haline gelemeyecek belirsiz commit özeti kullanma
3. Breaking changes için migration rehberliği eklemeyi unutma
4. Docs/chore değişikliklerini kullanıcı tarafından görülecek özellikler olarak ele alma
5. Tarihsel changelog bölümlerinin üzerine yazma yerine prepend yapma

Best Practices

1. Commit'leri küçük ve amaca yönelik tutun.
2. Multi-package repo'larda commit mesajlarını kapsamlı yapın (feat(api): ...).
3. PR pipeline'larında linter kontrolleri uygulayın.
4. Yayınlamadan önce oluşturulan markdown'ı gözden geçirin.
5. Changelog oluşturma başarılı olduktan sonra sürümleri etiketleyin.
6. Gerektiğinde manuel hazırlama için [Unreleased] bölümü tutun.

References

• references/ci-integration.md
• references/changelog-formatting-guide.md
• references/monorepo-strategy.md
• README.md

Release Governance

Öngörülebilirlik için bu sürüm akışını kullanın:

1. Hedef sürüm aralığı için commit geçmişini lint edin.
2. Commit'lerden changelog taslağı oluşturun.
3. Müşteri netliği için ifadeleri manuel olarak ayarlayın.
4. Semver bump önerisini doğrulayın.
5. Changelog onaylandıktan sonra sürümü etiketleyin.

Output Quality Checks

• Her bullet kullanıcı açısından anlamlı, uygulama gürültüsü değil.
• Breaking changes migration eylemini içerir.
• Security fixes Security bölümünde izole edilir.
• Hiç girdisi olmayan bölümler atlanır.
• Bölümler arasında yinelenen bullet'ler kaldırılır.

CI Policy

• Tüm PR'lerde commit_linter.py --strict çalıştırın.
• Geçersiz conventional commit'lerde merge'i engelleyin.
• Tag push'unda otomatik olarak taslak sürüm notları oluşturun.
• Main branch'deki CHANGELOG.md içine yazmadan önce insan onayı gerektirin.

Monorepo Guidance

• Commit kapsamlarını paket adlarıyla hizalı tutmayı tercih edin.
• Package-specific sürümler için commit akışını kapsamına göre filtreleyin.
• Altyapı çapındaki değişiklikleri root changelog'ta tutun.
• Paket changeloglarını sahiplik netliği için paket köklerine yakın depolayın.

Failure Handling

• Geçerli conventional commit bulunamazsa: erken başarısız olun, yanıltıcı boş notlar oluşturmayın.
• Git aralığı geçersizse: hata çıkışında açık aralığı yüzeye çıkarın.
• Write hedefi eksikse: güvenli changelog header iskeleti oluşturun.