أتمتة ملاحظات الإصدار بـ git-cliff: من الـ commit إلى CHANGELOG في ثوانٍ

المستوى: متوسط. الافتراض إنك بتستخدم Git وGitHub Actions، وتقدر تعدّل ملف إعدادات بسيط.

لو بتكتب ملاحظات كل إصدار بإيدك، انت بتحرق حوالي 40 دقيقة في شغل ممكن سكربت واحد يعمله في أقل من ثانية. المقال ده بيوريك إزاي تخلّي رسائل الـ commit نفسها تتحوّل لـ CHANGELOG وRelease جاهز، تلقائيًا.

حوّل رسائل الـ commit إلى سجل إصدارات يكتب نفسه

المشكلة باختصار

قبل كل إصدار، حد في الفريق بيفتح سجل الـ commits ويقعد يلخّص التغييرات في ملاحظات مقروءة. الطريقة دي بتفشل في نقطتين: بتاكل وقت، وبتنسى تغييرات مهمة لما الإصدار يكبر. لو فريقك بيطلّع إصدار أسبوعيًا، ده ~35 ساعة ضايعة في السنة على مهمة متكرّرة بالكامل.

المفهوم الأساسي: رسالة الـ commit كبيانات مش كلام

تخيّل إنك بتحزّم أغراض بيت في كراتين. لو كتبت على كل كرتونة "مطبخ" أو "كتب"، هتعرف تعمل قائمة محتويات في دقيقة. لكن لو الكراتين من غير عناوين، هتفتح كل واحدة عشان تعرف جواها إيه. رسائل الـ commit زي عناوين الكراتين بالظبط.

علميًا، ده اسمه Conventional Commits: اتفاقية بتخلّي أول كلمة في الرسالة تحدّد نوع التغيير. feat لميزة جديدة، fix لإصلاح، perf لتحسين أداء. لما الرسائل تبقى منظّمة بالشكل ده، أداة زي git-cliff تقدر تقرأها وتصنّفها وتبني منها ملف CHANGELOG بدون أي تدخل يدوي.

الحل: git-cliff في ثلاث خطوات

1. ثبّت الأداة: cargo install git-cliff أو نزّل الملف التنفيذي الجاهز من صفحة الإصدارات.
2. حط ملف إعداد cliff.toml في جذر المشروع يحدّد شكل المخرج وطريقة التصنيف.
3. شغّل أمر واحد يبني الملف من كل تاريخ الـ commits.

[changelog]
header = "# سجل التغييرات\n"
body = """
{% for group, commits in commits | group_by(attribute="group") %}
### {{ group }}
{% for commit in commits %}
- {{ commit.message }}
{% endfor %}
{% endfor %}
"""

[git]
conventional_commits = true
filter_unconventional = true
commit_parsers = [
  { message = "^feat", group = "ميزات جديدة" },
  { message = "^fix",  group = "إصلاحات" },
  { message = "^perf", group = "تحسينات الأداء" },
]

# يبني CHANGELOG.md لكل التاريخ ويربطه بوسم الإصدار
git cliff --tag v1.2.0 --output CHANGELOG.md

على مستودع فيه مئات الـ commits، الأمر ده بيخلص في أقل من ثانية. النتيجة ملف مقسوم لأقسام واضحة: ميزات، إصلاحات، تحسينات.