دليل المبتدئين إلى Git: ما هو سجل التغييرات (Changelog) وكيفية إنشائه

إذا كنت مطورًا وتستخدم Git لإدارة أحد مشاريعك، فمن المؤكد أنك ترغب في مشاركة التغييرات التي أجريتها مع المستخدمين أو أعضاء الفريق. لكن قد تتساءل عن أفضل طريقة للقيام بذلك. هذا المقال هو دليلك الشامل. في الجزء الأخير من هذه السلسلة، تحدثنا عن كيفية كتابة رسالة التزام (Commit Message) جيدة، وقدمنا لمحة عامة عن فوائدها، وأشرنا إلى إمكانية توليد سجل التغييرات (Changelog). في هذا المقال، ستتعرف على ماهية سجل التغييرات، بالإضافة إلى طريقتين لإنشائه: طريقة بسيطة وأخرى أكثر تطورًا.

ما هو سجل التغييرات (Changelog)؟

سجل التغييرات (Changelog) هو ملف يضم قائمة مرتبة زمنيًا بالتغييرات التي أجريتها على مشروعك. غالبًا ما يتم تنظيمه حسب إصدار المشروع، مع ذكر التاريخ متبوعًا بقائمة بالميزات المضافة أو المحسنة أو التي تمت إزالتها.

بشكل عام، هناك طريقتان رئيسيتان لكتابة سجل التغييرات:

• الطريقة التقليدية: إنشاء ملف نصي والبدء في تعداد جميع التغييرات مع تاريخ محدد لكل منها.
• خيار المطورين (أو الخيار الأسهل): توليد سجل التغييرات تلقائيًا من رسائل الالتزام (Commit Messages) الخاصة بك.

والخبر السار هو أن هذا المقال سيركز على الطريقة الثانية، والتي تتيح لك توفير الوقت والجهد!

“سجل التغييرات هو سجل أو تدوين لجميع التغييرات الملحوظة التي طرأت على المشروع. غالبًا ما يكون المشروع موقعًا إلكترونيًا أو مشروع برنامج، وعادةً ما يتضمن سجل التغييرات سجلات للتغييرات مثل إصلاحات الأخطاء والميزات الجديدة وما إلى ذلك.” – ويكيبيديا

لماذا يُعد سجل التغييرات ضروريًا؟

قد تتساءل الآن عن أهمية سجل التغييرات ولماذا يجب أن تخصص وقتًا لإنشائه. يُعد سجل التغييرات بمثابة ملخص لجميع التغييرات التي أجريتها، ويجب أن يكون سهل الفهم لكل من المستخدمين الذين يستخدمون مشروعك والمطورين الذين يعملون عليه.

في عالم يتطور فيه كل شيء بسرعة، يحتاج المستخدم إلى معرفة ما إذا كان الموقع الإلكتروني أو البرنامج الذي يستخدمه يتغير. قد تتفاجأ، لكن الناس يحبون قراءة منشورات المدونات أو صفحات التحديثات على المواقع الإلكترونية. أما بالنسبة للمطورين، فإذا كان المشروع كبيرًا، فقد يكون من المثير للاهتمام معرفة كيفية تطور البرنامج الذي يعملون عليه. على سبيل المثال، إذا كنت تعمل على مشروع مفتوح المصدر (open-source)، فستجد غالبًا ملف CHANGELOG.md في مستودع GitHub. يهدف هذا الملف إلى إبلاغ المساهمين بأحدث التحديثات على المشروع.

أين يمكننا العثور على سجلات التغييرات؟

سجلات التغييرات موجودة في كل مكان! حسنًا، غالبًا ما تكون لها أنماط ومواقع مختلفة، لكنها موجودة حرفيًا في كل مشروع. لقد أنشأت قائمة قصيرة ببعض الأماكن التي يمكنك أن تجد فيها سجل التغييرات:

• منشور مدونة: يمكن تقديم سجل التغييرات في مقال يشارك أحدث الميزات نقطة بنقطة.
• ملف CHANGELOG.md في مستودع GitHub: هذا هو المكان الأكثر شيوعًا للمشاريع مفتوحة المصدر.
• قسم سجل التغييرات على موقعك/برنامجك المفضل: إليك مثال مع أداة إدارة المهام TickTick.
• قسم “ما الجديد” (What's new) في متجري Android و iOS: حيث يتم إبلاغ المستخدمين بالتحديثات الجديدة للتطبيقات.

التوليد التلقائي لسجل التغييرات (Changelog)

في هذا الجزء، سنقوم بتوليد أول سجل تغييرات لنا معًا. من خلال القيام بهذه المهمة، ستفهم لماذا قد يكون من المفيد الالتزام ببعض القواعد عند كتابة رسائل الالتزام (commits). الالتزام الممتاز والواضح لا يحتاج إلى تعديل ويمكن إضافته مباشرة إلى سجل التغييرات.

ملاحظة: بعض المواقع مثل Keep A Changelog تشرح أنه لا ينبغي عليك إنشاء سجل تغييرات بمجرد نسخ ولصق التزامات Git (راجع الطريقة البسيطة). في الواقع، أوصي بتجنب هذه الطريقة إذا كنت تعمل على منتج احترافي. ومع ذلك، في الوقت الحاضر، هناك بعض المولدات المتقدمة التي تسمح لك بتحويل سجلات Git الخاصة بك إلى سجلات تغييرات منظمة (راجع الطريقة المتطورة).

كيفية إنشاء سجل التغييرات (الطريقة البسيطة)

باستخدام هذه الطريقة الأولى، لا تحتاج إلى أي متطلبات مسبقة. كل ما تحتاجه هو كتابة بضعة أوامر داخل مستودع Git الخاص بك. كتذكير بسيط، عندما تكتب الأمر git log، يتم عرض قائمة بجميع التزاماتك.

$ git log
// Output
commit f6986f8e52c1f889c8649ec75c5abac003102999 (HEAD -> master, origin/master, origin/HEAD)
Author: Sam Katakouzinos <sam.katakouzinos@gmail.com>
Date: Tue Mar 10 11:41:18 2020 +1100
    docs(developers): commit message format typo
    Any line of the commit message cannot be longer *than* 100 characters!
    Closes #17006
commit ff963de73ab8913bce27a1e75ac01f53e8ece1d9
Author: Chives <chivesrs@gmail.com>
Date: Thu Feb 6 19:05:57 2020 -0500
    docs($aria): get the docs working for the service
    Closes #16945
commit 2b28c540ad7ebf4a9c3a6f108a9cb5b673d3712d
Author: comet <hjung524@gmail.com>
Date: Mon Jan 27 19:49:55 2020 -0600
    docs(*): fix spelling errors
    Closes #16942

يمكن لهذا الأمر أن يأخذ بعض المعاملات (parameters). سنستخدمها لتغيير الإخراج والحصول على شكل محسّن لتوليد سجل التغييرات الخاص بنا. بكتابة الأمر التالي، ستحصل على إخراج يظهر التزامًا واحدًا لكل سطر.

$ git log --oneline --decorate
// Output
f6986f8e5 (HEAD -> master, origin/master, origin/HEAD) docs(developers): commit message format typo
ff963de73 docs($aria): get the docs working for the service
2b28c540a docs(*): fix spelling errors
68701efb9 chore(*): fix serving of URI-encoded files on code.angularjs.org
c8a6e8450 chore(package): fix scripts for latest Node 10.x on Windows
0cd592f49 docs(angular.errorHandlingConfig): fix typo (wether --> whether)
a4daf1f76 docs(angular.copy): fix `getter` / `setter` formatting
be6a6d80e chore(*): update copyright year to 2020
36f17c926 docs: add mention to changelog
ff5f782b2 docs: add mention to changelog
27460db1d docs: release notes for 1.7.9
add78e620 fix(angular.merge): do not merge __proto__ property

هذا أفضل، لكن دعنا نرَ ما يمكننا فعله بالأمر التالي.

$ git log --pretty="%s"
// Output
docs(developers): commit message format typo
docs($aria): get the docs working for the service
docs(*): fix spelling errors
chore(*): fix serving of URI-encoded files on code.angularjs.org
chore(package): fix scripts for latest Node 10.x on Windows
docs(angular.errorHandlingConfig): fix typo (wether --> whether)
docs(angular.copy): fix `getter` / `setter` formatting
chore(*): update copyright year to 2020
docs: add mention to changelog
docs: add mention to changelog
docs: release notes for 1.7.9
fix(angular.merge): do not merge __proto__ property

باستخدام هذا الأمر، يمكنك طباعة قائمة الالتزامات بالنمط الذي تريده. يمثل %s عنوان الالتزام نفسه. يمكنك تعديل السلسلة النصية (string) لتنسيق التزامك كما يحلو لك. في حالتنا، نريد إنشاء قائمة.

$ git log --pretty="- %s"
// Output
- docs(developers): commit message format typo
- docs($aria): get the docs working for the service
- docs(*): fix spelling errors
- chore(*): fix serving of URI-encoded files on code.angularjs.org
- chore(package): fix scripts for latest Node 10.x on Windows
- docs(angular.errorHandlingConfig): fix typo (wether --> whether)
- docs(angular.copy): fix `getter` / `setter` formatting
- chore(*): update copyright year to 2020
- docs: add mention to changelog
- docs: add mention to changelog
- docs: release notes for 1.7.9
- fix(angular.merge): do not merge __proto__ property

لقد نجحت! لقد أنشأت سجل تغييرات بسيطًا.

ملاحظة: إذا كنت ترغب في المضي قدمًا وحفظ سجل التغييرات الخاص بك بشكل أسرع: بدلاً من نسخ ولصق النتيجة في ملف، أعد توجيهها إلى الطرفية (terminal) الخاصة بك عن طريق كتابة الأمر git log --pretty="- %s" > CHANGELOG.md.

كيفية إنشاء سجل التغييرات (الطريقة المتطورة)

المتطلبات المسبقة

سنستكشف الآن طريقة متطورة لإنشاء سجل التغييرات. تظل الفكرة الأساسية وراء العملية كما هي، ولكن هذه المرة سنستخدم أدوات أخرى لمساعدتنا. هل تتذكر عندما تحدثت في الجزء الأخير من هذه السلسلة عن إرشادات Git؟

ملاحظة: إرشادات Git هي مجموعة من القواعد لكتابة التزاماتك بشكل أفضل. تساعدك هذه الإرشادات على إضافة بعض الهيكل إلى التزاماتك. عندما تستخدم إرشادات لمشروعك، يمكنك استخدام أدوات لتوليد سجل التغييرات. في معظم الأحيان، تكون هذه الأدوات أفضل لأنها تسمح لك بإنشاء سجل تغييرات بتنسيق Markdown.

في هذا المثال، سنستخدم مولدًا بسيطًا يعمل مع معظم الإرشادات. اسمه generate-changelog، وهو متاح على NPM (مدير حزم Node). ستقوم هذه الأداة بإنشاء سجل تغييرات منسق، لكنها ليست الأداة التي تحتوي على معظم الميزات. لقد قررت استخدامها لأنها مثال ممتاز للمبتدئين. إذا كنت ترغب في المضي قدمًا، يرجى الرجوع إلى قائمة أدوات سجل التغييرات أدناه:

إليك بعض الأدوات التي يمكنك استخدامها:

• Github Changelog Generator
• Git Chglog
• Auto Changelog
• Conventional Changelog

ملاحظة: قبل تثبيت الأداة، يجب أن يكون لديك NPM مثبتًا على جهاز الكمبيوتر الخاص بك. إذا لم يكن لديك، أدعوك لاتباع الموقع الرسمي (سيساعدك على تثبيت Node و NPM). لتثبيت الحزمة على جهاز الكمبيوتر الخاص بك، اكتب الأمر التالي في الطرفية (terminal) الخاصة بك.

$ npm install generate-changelog -g

بمجرد الانتهاء من ذلك، تكون قد قمت بتثبيته!

كيفية استخدامه

لجعل هذه الحزمة تعمل، تحتاج إلى اتباع الإرشادات لاستخدام هذا النمط – "type(category): description [flags]". في هذا المثال، سأستخدم مستودع GitHub الخاص بـ Angular.js. الآن يمكنك كتابة أمر التوليد في الطرفية (terminal) الخاصة بك داخل مستودع GitHub الخاص بك.

$ changelog generate

سيتم إنشاء ملف CHANGELOG.md تلقائيًا وملؤه بسجلاتك بتنسيق Markdown. يمكنك العثور على مثال للإخراج (باستخدام قارئ Markdown مثل GitHub) أدناه.

الخلاصة

نأمل أن يكون هذا الدليل قد نال إعجابك وأنك أصبحت الآن تفهم كيفية إنشاء سجل تغييرات (Changelog) لمشروعك. أعتقد أنها طريقة ممتازة لتوضيح سبب أهمية كتابة رسائل التزام (commit messages) جيدة. لا تتردد في تجربة مولدات سجل التغييرات الأخرى ومشاركتنا النتائج! إذا كان لديك أي أسئلة أو ملاحظات، فلا تتردد في إبلاغي بذلك.

الخلاصة التقنية

يُعد سجل التغييرات (Changelog) أداة حيوية في دورة حياة تطوير البرمجيات، حيث يعمل كجسر تواصل فعال بين المطورين والمستخدمين. بينما توفر الطرق اليدوية البسيطة مرونة في التوثيق، فإن الاعتماد على أدوات التوليد التلقائي المرتبطة برسائل الالتزام (commit messages) المنسقة (مثل Conventional Commits) يعزز الكفاءة ويضمن الاتساق. إن تبني ممارسات الالتزام الجيدة لا يسهل فقط تتبع التغييرات، بل يمهد الطريق أيضًا لتوليد سجلات تغييرات احترافية تلقائيًا، مما يقلل الجهد اليدوي ويحسن جودة توثيق المشروع بشكل عام. هذا النهج لا يخدم فقط الشفافية وإدارة الإصدارات، بل يعكس أيضًا احترافية فريق التطوير.