عودة

كيفية كتابة git commits واضحة، مفهومة، ومطابقة للمعاير'

منذ 3 أشهر
مدة القراءة 0 د
# devops

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

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

المحتوي:

سيتناول هذا المقال أهم القواعد والممارسات التي يجب اتباعها لكتابة Commits واضحة ومفهومة، بحيث تكون متناسبة مع المعايير المقبولة، مما يسهم في تعزيز فاعلية عملية التطوير وتسهيل عملية فهم التغييرات بوجه عام.

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

لماذا يجب عليك الالتزام بمعايير كتابة Commits جيدة؟

افتح أي مشروع برمجي واطلع على تاريخ Commits المشروع git log، ستجد أنه يحتوي على العديد من الرسائل التي لا توضح بشكل واضح التغييرات التي تم إجراؤها. مثلا :

fix bug
refactor
update

أسأل نفسك سؤل بسيط: هل يمكنك فهم ما تم تغييره في هذه الرسائل؟، هنا سيتبين لك أهمية كتابة رسائل Commits واضحة ومفهومة، حيث تعكس هذه الرسائل فهم المطور للتغييرات التي قام بها وتوجيهه للمطورين الآخرين الذين قد يعملون على نفس المشروع.

تكوين رسالة الـ commit

  • بشكل بسيط
git commit -m <message>
  • أو بشكل مفصل
git commit -m <message> -m <description>

مثال:

git commit -m "feat: add new feature" -m "this feature will allow users to add new posts"

ما هي معايير كتابة Commits الجيدة؟

  • أبدأ أول رسالة Commit بحرف كبير
  • استخدم الفعل المناسب للتغييرات التي تم إجراؤها مثل Add - Update - Fix - Remove
  • كن واضح عند كتابة الرسائل، لتوضيح الغرض من التغييرات التي تم إجراؤها
  • طول الرسالة لا يزيد عن 50 حرفًا في أول سطر ولا يزيد عن 72 حرفًا في محتوى الرسالة

ومن الجيد أن تسأل نفسك هذه الأسئلة قبل الالتزام برسالة Commit:

  • لماذا أقوم بإجراء هذه التغييرات؟
  • ماهي التأثيرات التي ستحدثها هذه التغييرات؟
  • هل هناك أي تغييرات أخرى مرتبطة بهذه التغييرات؟

مثل علي رساله غير وضحة

git commit -m "add padding"

في هذه الحالة يجب أن تكون الرسالة أكثر وضوحًا وتوضح الغرض من التغييرات التي تم إجراؤها، مثل:

git commit -m "Add padding to the header section to prevent the content from being cut off"

Conventional Commits (الإلتزمات التقليدية):

مجموعة من المعايير ، لكتابة رسائل Commits واضحة ومفهومة، مما يُسهل بناء أدوات مُأتمتهه للتحكم بالتغييرات والإصدارات.، وأيضا متوفقة مع SemVer، عن طريق تحديد المميزات ، والإصلاحات والتغيرات features, fixes and breaking changes في رساذل الـ commits

بُنية رسالة الـ commit

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

  • type: يحدد نوع التغييرات التي تم إجراؤها، ويمكن أن يكون من الأنواع التالية:

    • feat: إضافة ميزة جديدة
    • fix: إصلاح خطأ
    • docs: تغييرات في الوثائق
    • style: تغييرات لا تؤثر على الكود مثل تغييرات في الـ CSS
    • refactor: تغييرات في الكود لا تضيف أي ميزة أو تصليح
    • perf: تغييرات في الكود تحسين أداء النظام
    • test: إضافة اختبارات جديدة أو تغييرات في الاختبارات
    • build: تغييرات في عملية البناء مثل تغييرات في ملفات الـ tailwind config
    • ci: تغييرات في عملية النشاء مثل تغييرات في ملفات الـ Travis
    • chore: تغييرات في العمليات الأخرى مثل تغييرات في ملفات الـ Docker
    • revert: إسترجاع commit سابق

  • scope: هو جزء اختياري من رسالة الـcommit ويتم استخدامه لتحديد نطاق التغييرات التي تمت. يمكن أن يكون هذا النطاق أي شيء يحدد الجزء الخاص من المشروع الذي تم التغيير فيه، مثل اسم المكون أو الوحدة أو الطبقة.

على سبيل المثال، إذا كنت تعمل على تحسينات في واجهة المستخدم للصفحة الرئيسية، قد تكتب رسالة الالتزام الخاصة بك كالتالي:

git commit -m "feat(homepage UI): Improve responsiveness on mobile devices"

في هذا السياق، "homepage UI" هو النطاق الذي يحدد أن التغييرات التي تمت تتعلق بواجهة المستخدم للصفحة الرئيسية.

  • description: هو جزء إجباري من رسالة الـ commit ويتم استخدامه لوصف التغييرات التي تمت بشكل واضح ومفهوم. ويجب أن تكون كل حروفه صغيره

  • body: هو جزء اختياري من رسالة الـ commit ويتم استخدامه لوصف أكثر تفصيلا للتغيرات. وأيضا، يمكنك كتابة ال break changes هنا علي النحو التالي:

BREAKING CHANGE: <description>
  • footer: هو جزء اختياري من رسالة الـ commit ويتم استخدامه لإضافة معلومات إضافية مثل رقم الـ issue أو رقم الـ pull request.

مثال كامل علي Conventional Commit :

fix: fix foo to enable bar

This fixes the broken behavior of the component by doing xyz.

BREAKING CHANGE
Before this fix foo wasn't enabled at all, behavior changes from <old> to <new>

Closes MDFR-1234

ما هي أدوات الـ commit التي تدعم Conventional Commits؟

ملخص:

  • كتابة رسائل ال commits الجيده تساعد علي فهم التغييرات التي تم إجراؤها وتوجيهه للمطورين الآخرين الذين قد يعملون على نفس المشروع، وتسهل عملية فحص الأخطاء، وتسريع عمليات الدمج، وتسهيل عمليات التصحيح والتحسين.
  • أيضا، يمكنك استخدام الإلتزامات التقليدية لكتابة رسائل الـ commits بشكل واضح ومفهوم، مما يُسهل بناء أدوات مُأتمتهه للتحكم بالتغييرات والإصدارات.

المصادر:

ماهر الجميل © 2024