بلدي بوابة ارتكاب المفضل

تقريبا. العابرة. : يشير هذا المنشور الصادر عن مبرمج بريطاني ، والذي أصبح نجاحًا كبيرًا على الإنترنت الناطقة باللغة الإنجليزية ، إلى التزام من Git قبل 6 سنوات. تم تسجيله في أحد مستودعات الخدمة الرقمية الحكومية المفتوحة - وهي خدمة مخصصة لتطوير الخدمات الرقمية في المملكة المتحدة ودعم مشروع GOV.UK. الالتزام بحد ذاته مثير للاهتمام ليس بالتغييرات في الكود بقدر ما هو مهم مع الوصف الذي يرافقهم ...


صورة من xkcd # 1296

أنا أحب ارتكاب الأوصاف في بوابة. عند استخدامها بشكل صحيح ، يمكن أن يطلق عليها واحدة من أقوى الأدوات لتوثيق تطور قاعدة الكود أثناء وجودها. أريد أن أوضح وجهة نظري بمثال الوصف المفضل لدي.

يعود هذا الالتزام إلى الوقت الذي عملت فيه في الخدمة الرقمية الحكومية. مؤلفها هو مطور يدعى دان كارلي ، ولديه عنوان غير ملحوظ إلى حد ما: "تم تحويل القالب إلى US-ASCII لإصلاح الخطأ ".

"لقد قمت بتنفيذ العديد من الاختبارات في فرع الميزة لمطابقة محتويات` / etc / nginx / router_routes.conf`. لقد عملوا جيدًا إذا تم تشغيلهم باستخدام أوامر `bundle exec rake spec` أو` bundle exec rspec modules / router / spec`. ولكن عند تشغيل حزمة bundle exec rake ، فشلت كل كتلة يجب:

ArgumentError: invalid byte sequence in US-ASCII 

في النهاية ، وجدت أنه بعد استثناء التعبير `.with_content (//)` ، تختفي جميع الأخطاء. عدم وجود أحرف غريبة في ملف المواصفات. وأيضًا أنه يمكن تشغيله عن طريق استدعاء Puppet في نفس المترجم:

  rake -E 'require "puppet"' spec 

يبدو أن هذا القالب هو الملف الوحيد في قاعدة بياناتنا المشفرة باستخدام "utf-8". جميع الملفات الأخرى في 'us-ascii':

  dcarley-MBA:puppet dcarley$ find modules -type f -exec file --mime {} \+ | grep utf modules/router/templates/routes.conf.erb: text/plain; charset=utf-8 

أخفقت محاولة لتحويلها إلى US-ASCII بسبب وجود حرف واحد يشبه المساحة:

  dcarley-MBA:puppet dcarley$ iconv -f UTF8 -t US-ASCII modules/router/templates/routes.conf.erb 2>&1 | tail -n5 proxy_intercept_errors off; # Set proxy timeout to 50 seconds as a quick fix for problems # iconv: modules/router/templates/routes.conf.erb:458:3: cannot convert 

بعد استبداله (يدويًا) ، أصبح الملف مرة أخرى "US-ASCII":

  dcarley-MBA:puppet dcarley$ file --mime modules/router/templates/routes.conf.erb modules/router/templates/routes.conf.erb: text/plain; charset=us-ascii 

الآن الاختبارات تعمل! لا يمكن إرجاع ساعة كاملة من حياتي ... "

استطراد صغير: أحد فوائد تطوير المصادر المفتوحة التي تمارس في GDS هو أنه يمكنك مشاركة أمثلة كهذه خارج المنظمة التي أنشأتها. لا أعرف من الذي اقترح هذا المفهوم أولاً على GDS - بحلول الوقت الذي التحقت فيه بالمؤسسة ، كان يستخدم بالفعل على نطاق واسع - لكنني ممتن للغاية لهذا الشخص.

لماذا أحب هذا الالتزام

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

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

يكشف سبب التغييرات

إن أفضل وصف للالتزامات لا يوضح فقط ما الذي تغير ، بل يشرح أيضًا السبب . في حالتنا:

لقد قمت بتنفيذ العديد من الاختبارات في فرع الميزة لمطابقة محتويات `/ etc / nginx / router_routes.conf`. لقد عملوا جيدًا إذا تم تشغيلهم باستخدام أوامر `bundle exec rake spec` أو` bundle exec rspec modules / router / spec`. ولكن عند تشغيل حزمة bundle exec rake ، فشلت كل كتلة يجب:

  ArgumentError: invalid byte sequence in US-ASCII 

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

يمكن أن يكون هذا النوع من المعلومات ذا قيمة حقيقية ، ومن السهل للغاية خسارته ، حيث يميل الناس إلى نسيان تعقيدات عملهم ، والانتقال إلى فرق أخرى ، ثم مغادرة الشركة في النهاية.

جيد للبحث

أحد العناصر الرئيسية لهذا الوصف هو الخطأ نفسه ، والذي بدأت به عمليات البحث الإضافية:

ArgumentError:
تسلسل بايت غير صالح في US-ASCII

يمكن لأي شخص يواجه هذا الخطأ البحث في قاعدة الشفرة ، إما عن طريق تشغيل git log --grep "invalid byte sequence" ، أو باستخدام GitHub يرتكب البحث . في الواقع ، بناءً على نتائج البحث ، فعل الكثيرون ذلك بالفعل واكتشفوا من ومتى واجهوا هذه المشكلة وكيف تم حلها أخيرًا.

يوفر صورة كاملة

تفاصيل رسالة الالتزام كيف تبدو المشكلة ، وكيف تم التحقيق فيها وحلها. على سبيل المثال:

في النهاية ، وجدت أنه بعد استثناء التعبير `.with_content (//)` ، تختفي جميع الأخطاء. عدم وجود أحرف غريبة في ملف المواصفات. وأيضًا أنه يمكن تشغيله عن طريق استدعاء Puppet في نفس المترجم الفوري.

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

يجعل الجميع أكثر ذكاء قليلا

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

• يمكنك تمرير وسيطة -exec find على تنفيذ أمر مع كل ملف موجود ؛
• تؤدي إضافة \+ في نهاية الأمر إلى إجراء شيء مثير للاهتمام (تمرير عدة أسماء ملفات إلى أمر file ، ولا يتم تنفيذ الأمر مرة واحدة لكل ملف) ؛
• file --mime يتيح file --mime اكتشاف نوع ملف MIME ؛
• هناك فائدة iconv .

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

تطور التعاطف والثقة

الآن الاختبارات تعمل! لا يمكن إرجاع ساعة كاملة من حياتي ...

الفقرة الأخيرة تضيف القليل من الإنسانية. عند قراءة هذه الكلمات ، من الصعب ألا تشعر بخيبة أمل دان ، الذي اضطر لقضاء ساعة كاملة في البحث عن خطأ خفي ، والرضا عن تصحيحه.

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

ارتكاب جيد يهم

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

إذا كنت تريد معرفة المزيد عن إيجابيات التوصيفات الجيدة للتعهدات وبعض الأدوات التي تجعل من السهل هيكلة التعديلات ، يمكنني أن أوصي بالمواد التالية:

• " سرد القصص من خلال أعمالك " بقلم جويل تشيبيندال ؛
• " فرع في الوقت المناسب " بقلم تيك سليمان.

PS من المترجم

اقرأ أيضًا في مدونتنا:

• " جيت يحدث! 6 أخطاء جيت نموذجية وكيفية اصلاحها "؛
• " خدعة رائعة لجعل مشرف مشروع مفتوح المصدر يوميًا " ؛
• " ما الذي تشترك فيه مشروعات المصادر المفتوحة الناجحة الكبيرة؟ ".