يبدأ تقرير الخطأ البرمجي المفيد بخطوات واضحة، ثم يفصل ما حدث عما كان متوقعًا حدوثه. [1] سنحوّل شكوى عن قائمة مهام إلى بلاغ يمكن مراجعته؛ التطبيق والمهام والنتائج في هذا المثال مؤلفة للتعليم، وليست عيبًا رصدناه في برنامج حقيقي.
الخلاصة السريعة
اكتب ما فعلته وبأي ترتيب، وما الذي ظهر، وما الذي توقعت ظهوره ولماذا. أضف الحالة اللازمة لتكرار المشكلة، واترك السبب غير المثبت سؤالًا مفتوحًا.
- اختر عنوانًا يحدد الفعل والعَرَض، مثل عودة المهمة المكتملة بعد فرز قائمة غير المكتمل.
- سجّل الإصدار والحالة الأولية وبيانات الاختبار؛ لا تكتف بعبارة أحدث نسخة أو حساب عادي.
- في مثالنا ثلاث مهام: اثنتان غير مكتملتين وواحدة مكتملة. نعرض غير المكتمل أولًا، ثم نفرز القائمة.
- النتيجة المتوقعة بقاء مهمتين، بينما تعود الثالثة في النتيجة المفترضة رغم بقاء المرشح مختارًا؛ لا يثبت ذلك حذف البيانات.
- اكتب عدد المحاولات وشروط كل مجموعة إذا ظهر الخلل أحيانًا، ولا تحول عينة صغيرة إلى حكم على جميع المستخدمين.
- أرفق دليلًا يخدم الخطوات، أو مثالًا مصغرًا يحفظ المشكلة؛ افصل صور التوضيح عن لقطات الاختبار الفعلية.
- ابحث عن بلاغ مطابق، ثم تابع المعلومة الجديدة والإصدار الذي اختبرته؛ تغيير حالة البلاغ لا يغني عن مراجعة ما وصل إلى نسختك.
سمِّ المشكلة قبل اقتراح حلها
توصي إرشادات Mozilla بعنوان يصف المشكلة بوضوح، وخطوات دقيقة، مع الفصل بين الوقائع والتخمينات. [1] في مثالنا لا نكتب التطبيق سيئ أو أصلحوا قاعدة البيانات. نختار عنوانًا أقرب إلى المشهد: عودة المهمة المكتملة بعد فرز قائمة غير المكتمل. يستطيع القارئ من هذا العنوان تحديد الجزء الذي سيفحصه والفعل الذي سبق ظهور العَرَض.
العنوان المقترح لا يقول إن الفرز حذف بيانات أو أفسد الحساب؛ هذه تفسيرات لم نقدم عليها دليلًا. وهو لا يَعِد بأن المشكلة تخص جميع القوائم أو الأجهزة. نحتفظ بوصف ضيق يمكن اختباره، ثم نوسع نطاقه إذا توفرت نتائج أخرى. إذا أثبت الفحص لاحقًا سببًا مختلفًا، يظل وصف المشهد مفيدًا بدل أن يصبح العنوان كله مضللًا.
ابدأ المتن بجملة توضح أثر المشكلة في المهمة التي تحاول إنجازها. يمكن أن نقول إن المستخدم يريد مراجعة الأعمال المتبقية، لكن القائمة تعيد عرض عمل مكتمل بعد الفرز. لا نضيف خسارة مالية أو ضياع وقت لم نقسه. يوضح هذا السياق سبب اهتمامنا بالخلل، بينما تبقى التفاصيل العملية في الخطوات التالية حتى لا تختلط الشكوى بطريقة تكرارها.
وإذا لاحظت في الجلسة نفسها مشكلة أخرى في لون الزر، فاسأل هل هي جزء من المشهد نفسه أم قضية مستقلة. يمكن حفظها في ملاحظة منفصلة إلى أن يتضح ارتباطها. لا تجعل بلاغ القائمة دفترًا لكل ما أزعجك في التطبيق؛ فكل مطلب إضافي يحتاج وصفه ونتيجته، وقد يصعب معرفة أي عَرَض عولج إذا جمعتها بلا علاقة.
حدد الحالة التي بدأت منها
نؤلف تطبيقًا نسميه دفتر المهام التجريبي، ونعطي نسخة المثال الرقم 0.3. توجد فيه مهمة إصلاح المصباح ومهمة شراء الأقلام، وكلتاهما غير مكتملة، ومهمة ترتيب الكتب وهي مكتملة. هذه بيانات صغيرة نعرفها كلها، فلا يحتاج من يقرأ البلاغ إلى حساب خاص أو نسخة من أعمال شخص حقيقي كي يفهم التفاوت الذي سنصفه.
نحدد أيضًا نقطة البداية: القائمة تعرض المهام الثلاث، ولا يوجد بحث نصي مفعّل. ثم نختار مرشح غير المكتمل فتظهر المهمتان الأوليان. هذا الشرط مهم في قصتنا؛ إذا بدأ المراجع من قائمة تعرض الجميع ثم ضغط الفرز، فلن يرى تعارضًا في ظهور ثلاثة صفوف. تحتاج الخطوات إلى بداية تتيح مقارنة الفعل بالنتيجة التي يفترض أن يحافظ عليها.
في تقرير فعلي اكتب اسم التطبيق وإصداره كما يظهر لك، ونظام التشغيل والمتصفح عندما يتعلق الأمر بتطبيق ويب. اذكر ما عرفته واترك المجهول معلنًا. لا تكتب أحدث نسخة فقط، لأن العبارة تفقد معناها حين يقرأ شخص البلاغ بعد تحديث آخر. ولا تنقل رقم إصدار من جهاز ثانٍ إلى البطاقة التي تصف ما حدث على جهازك الأول.
يمكنك إضافة اللغة أو حجم النافذة أو نوع الحساب إذا كانت جزءًا من ظهور المشكلة التي تراجعها. لكن لا تدّع أن العامل مؤثر لمجرد أنك سجلته. نفرق في البطاقة بين وصف البيئة وبين نتيجة مقارنة تثبت أن تغيير عنصر فيها غيّر السلوك. جمع المعلومات اللازمة بداية جيدة، أما تفسير دور كل عنصر فمرحلة تحتاج دليلها الخاص.
اكتب خطوات يستطيع شخص آخر اتباعها
في بلاغ المثال نرتب الأفعال هكذا: افتح نسخة قائمة المهام المذكورة، وتحقق من وجود المهام الثلاث وحالاتها، ثم اختر غير المكتمل، وبعد ظهور مهمتين اضغط زر الترتيب حسب الاسم. نجعل مشاهدة المهمتين نقطة تحقق قبل الفرز. إذا لم يصل المراجع إليها، فهو لم يبدأ من الحالة التي يتناولها البلاغ، حتى لو ضغط الزر الأخير نفسه.
حدد وسيلة التفاعل عندما تؤثر في وصف التجربة. بدل فعلت الفرز، قل ضغطت زر الترتيب بالماوس، أو انتقلت إليه بلوحة المفاتيح وفعلته. لا نقرر مسبقًا أن الطريقتين تعطيان نتيجة مختلفة؛ نحن نحفظ ما استعملناه كي يستطيع الآخر إعادة المحاولة. وإذا كنت لا تتذكر وسيلة التفاعل في الواقعة الأولى، لا تكمل الذاكرة بتفصيل اخترعته لاحقًا.
وتجنب الخطوات التي تقفز فوق إعداد لازم، مثل استعمل القائمة المعتادة ثم أعد ما فعلته أمس. ما تعرفه أنت عن بياناتك قد لا يعرفه المطور. في المقابل، لا يلزم شرح كل حركة لا تغير الحالة. راجع التسلسل واسأل عن كل خطوة: هل يحتاجها القارئ للوصول إلى نقطة الاختلاف، أم أنها مجرد تفصيل جانبي يمكن اختصاره دون فقدان شيء؟
قبل الإرسال، اقرأ التعليمات من بدايتها باعتبارك شخصًا لم يشاهد الواقعة. هل تحتوي أسماء الأزرار على ما يكفي لتمييزها؟ هل ذكرت انتظار ظهور القائمة قبل الفرز؟ هل يستطيع المراجع معرفة متى انتهت الخطوات؟ هذه مراجعة لوضوح النص، ولا تعني أنك نفذت تجربة ثانية فعلًا؛ إذا أعدت التنفيذ، سجّل نتيجته مستقلة عن مجرد إعادة قراءة البلاغ.
قارن النتيجة الفعلية بالنتيجة المتوقعة
تطلب إرشادات Mozilla وصف النتيجتين بدقة بعد خطوات التكرار. [1] نعطي للمثال قاعدة صريحة: الفرز يعيد ترتيب المهام الظاهرة ولا يغير مرشح حالتها. بناءً عليها نتوقع بقاء مهمتين غير مكتملتين. أما النتيجة المفترضة للخلل فهي ظهور المهام الثلاث، ومنها ترتيب الكتب، مع استمرار ظهور غير المكتمل بوصفه المرشح المختار على الشاشة.
وصف الشاشة لا يثبت أن الحالة المحفوظة لمهمة ترتيب الكتب تغيرت. قد تظهر في القائمة مع بقاء علامتها مكتملة، كما نفترض هنا. لهذا نكتب عادت المهمة المكتملة إلى النتائج، ولا نكتب أعاد البرنامج المهمة إلى غير مكتملة. يحدد الفرق ما شاهدناه فعلًا، ويمنع انتقال المراجع من مشكلة عرض إلى مشكلة تعديل بيانات لم تقدمها المعطيات.
عند التعامل مع برنامج حقيقي، وضح أساس توقعك: تعليمات الميزة، أو مواصفة متفق عليها، أو سلوك سابق رصدته مع ذكر نسخته. وإذا كان الأمر مجرد تفضيل، فاكتب ذلك بدل تقديمه بوصفه شرطًا مثبتًا. يمكنك أن تطلب توضيح السلوك المتوقع قبل تصنيف المشكلة، خصوصًا إذا كان اسم الزر مختصرًا أو كانت الميزة تجمع أكثر من وظيفة.
والجدول التالي يضغط الفرق دون استبدال خطوات البلاغ. يحتفظ بحالة المرشح والمهام الظاهرة قبل الفعل وبعده، لكنه لا يعرض شفرة التطبيق أو يسمي سبب الخلل. يمكن للمطور أن يضع فرضيات بعد قراءته؛ تظل تلك الفرضيات منفصلة عن البطاقة إلى أن يفحصها. التقرير الجيد يتيح بدء التحقيق من وصف مشترك، ولا يشترط أن يحمل إصلاحه جاهزًا.
| الحالة | عدد المهام الظاهرة | المهمة المكتملة |
|---|---|---|
| قبل الفرز، بعد الترشيح | 2 | مخفية |
| المتوقع بعد الفرز | 2 | مخفية |
| النتيجة المفترضة للخلل | 3 | ظاهرة بعلامة مكتملة |
صف التكرار المتقطع دون تعميم
لنفتح فرعًا آخر من المثال تختلف فيه الملاحظة بحسب المحاولة. نعطي خمس محاولات بالماوس تظهر المشكلة في اثنتين منها، وأربع محاولات بلوحة المفاتيح لا تظهر فيها. نكتب المجموعتين كما هما، مع أن كل هذه الأعداد مؤلفة. لا نختصرها إلى الفرز معطل دائمًا أو لوحة المفاتيح تصلح المشكلة؛ فهاتان عبارتان أوسع من النتائج المعطاة.
يمكن القول إن مجموع محاولات هذا الفرع تسع، وإن ظهور المشكلة سجل مرتين، لكن جمعها يخفي طريقة التفاعل. في بلاغنا نفضل الاحتفاظ بالمجموعتين لأن الفرق بينهما قد يوجه سؤالًا مفيدًا للفحص. ولا نستخدم نسبتهما حكمًا على كل جهاز أو مستخدم؛ هذه عينة محددة بمدخلاتها، ولم نعط تصميم اختبار يتيح تعميمها على جمهور التطبيق.
اذكر أيضًا كيف أعدت الحالة بين المحاولات. إذا بدأت مرة من قائمة جديدة ومرة من الصفحة التي بقيت مفتوحة بعد خلل سابق، فقد قارنت بدايتين مختلفتين. لا يلزم أن يكون هذا هو السبب؛ المطلوب إظهاره للمراجع. وإذا لم تحفظ تلك التفاصيل، فقل إنها لم تسجل بدل ملء الخانات لاحقًا بما تتمنى أنك فعلته في كل مرة.
أما إذا وقعت المشكلة مرة واحدة ولم تستطع تكرارها، فقدم ما بقي لديك من وقت حدوثها وخطوات تتذكرها ورسالة ظاهرة، مع التصريح بحدود الذاكرة. لا تختلق تسلسلًا مضمونًا كي يبدو البلاغ أقوى. يمكن أن يكون التقرير مفيدًا بما يحمله من ملاحظة محددة، بينما تظل كيفية إعادة الظهور سؤالًا مطلوبًا وليست نتيجة حصلت عليها بالفعل.
اختر مرفقًا يضيف دليلًا
تشير إرشادات Chromium إلى إرفاق صور عندما تساعد، وإلى إعداد اختبار مبسط إذا أمكن اختزال المشكلة إليه. [2] في مثالنا يمكن أن تخدم لقطة ما قبل الفرز وأخرى بعده المقارنة، بشرط أن تبينا المرشح وحالة المهمة. أما صورة عامة للحاسوب، مثل صورة افتتاح هذا المقال، فتوفر سياقًا بصريًا ولا تثبت وقوع الخلل.
راجع المرفق قبل مشاركته، واستخدم بيانات اختبار بدل كشف أعمالك أو بيانات الآخرين. تأكد من عدم ظهور كلمة مرور أو رمز جلسة أو اسم عميل في الصورة أو السجل. لا تجعل طلب معلومات إضافية إذنًا تلقائيًا لإرسال كل الملفات. وإذا احتاج الفريق إلى مادة خاصة، فاتفق على قناة مناسبة ونطاق محدد بدل نشرها في بلاغ عام يراه الجميع.
يشرح MDN أن المثال المصغر لمشكلة ويب ينبغي أن يكون صغيرًا ومستقلًا قدر الإمكان، مع إزالة الأجزاء غير المرتبطة، وأن السلوك غير المتوقع قد يرتبط بالشفرة أو المتصفح أو الوثائق أو المواصفة. [3] اختصار المشروع هنا وسيلة لعزل السؤال، وليس دليلًا تلقائيًا على أن المتصفح هو المسؤول لمجرد ظهور المشكلة داخل نافذته.
إذا أنشأت نسخة مصغرة، فتحقق من أن الخطوات ما زالت تظهر المشكلة المقصودة فيها. حذف المرشح من مثالنا يزيل جوهر التعارض ولو أبقى زر الفرز. اكتب ما تغير في النسخة وما بقي، وأرفق طريقة فتحها وتشغيلها عند الحاجة. وإذا لم تتمكن من إعدادها، اذكر ذلك؛ لا تسمِّ ملفًا فارغًا أو لقطة شاشة مثالًا قابلًا للتنفيذ لمجرد صغر حجمه.
راجع البلاغ وتابع نتيجته
ينصح MDN بالبحث عن بلاغات موجودة قبل إنشاء بلاغ جديد، وإضافة معلومات نافعة إذا وجدت تطابقًا. [3] ابحث في حالتنا عن الفرز والترشيح وعودة المهام المكتملة، ثم اقرأ الخطوات والإصدار. تشابه العنوان وحده لا يحسم أن مشكلتك هي نفسها، كما أن اختلاف كلمة واحدة لا يجعل فتح بلاغ جديد أفضل من توضيح الحالة في البلاغ المناسب.
يمكن ترتيب النسخة النهائية في حقول قصيرة: العنوان، والإصدار والبيئة، والحالة الأولية، والخطوات، والمتوقع، والفعلي، وعدد المحاولات، والمرفقات. ابدأ فيها ببيانات المثال المعروفة واترك نظام التشغيل غير معين إن لم تعط قيمته. هذا قالب مقترح للتنظيم؛ اتبع أيضًا حقول الجهة المستقبلة، ولا تحذف معلومة لازمة لمجرد أنها لا تناسب السطر الذي أعددته مسبقًا.
وتوضح وثائق Chromium أن وضع البلاغ في حالة أصلح لا يعني وصول الإصلاح فورًا إلى كل قنوات الإصدار؛ يلزم الانتباه إلى النسخة التي تتضمنه. [2] لذلك إذا طُلب منك التحقق، دوّن الإصدار الذي اختبرته فعلًا والخطوات التي أعدتها. لا تؤكد اختفاء المشكلة اعتمادًا على تغير عنوان الصفحة أو حالة البلاغ وحدهما.
عند ظهور نتيجة جديدة، أضفها مع شروطها بدل كتابة لا يزال لا يعمل فقط. يمكنك أن تقول إن المرشح بقي مختارًا وإن المهمة المكتملة ظهرت بعد الفرز في محاولة محددة، أو إن الحالة لم تتكرر في الاختبار الذي نفذته. احتفظ بالفصل بين الملاحظة والسبب حتى النهاية؛ فوضوح البلاغ يسهّل المراجعة، لكنه لا يضمن موعد الإصلاح أو يحدد وحده من يتحمله.
المصادر ومتابعة القراءة
- Mozilla: إرشادات كتابة تقارير الأخطاء (يفتح في نافذة جديدة)bugzilla.mozilla.org
- Chromium: إرشادات الإبلاغ ودورة معالجة الخلل (يفتح في نافذة جديدة)chromium.org
- MDN: متى وكيف تبلغ عن أخطاء المتصفح (يفتح في نافذة جديدة)developer.mozilla.org
أُعدّ هذا المقال بصياغة عربية أصلية بالاستناد إلى المصادر أعلاه، وهو مدخل تمهيدي إلى الموضوع. اقرأ منهجية المحتوى وحدوده.