مختبر المقاييس: قياس التدفق عبر GitHub

المواصفة الفنية الإصدار 1.0

---

الميثاق (المنافيستو)

“نحن نقيس النظام، لا الإنسان”

في مختبر المقاييس، نؤمن أن المطور لا يفشل بمفرده، بل يعلق في نظام سيء الصنع. الانخفاض في الإنتاجية ليس كسلاً بشرياً، بل هو احتكاك منظومي (Systemic Friction) يسرق حالة التدفق (Flow) من المهندس.

هدف هذا الدليل هو تحويل GitHub من مجرد مخزن للكود إلى “مرصد” لقياس صحة العملية البرمجية، مع التركيز الكامل على تحسين المسارات التي يمر بها الكود، وضمان أن القياس يُستخدم كأداة للتمكين وليس للرقابة.

---

وحدات القياس (Metric Blocks)

[Metric_Card]

1. زمن دورة المهمة (Cycle Time)

• الحالة المثالية: تدفق مستمر، مهام صغيرة تدمج فور انتهائها.
• الاحتكاك: بقاء الكود عالقاً في “البرزخ التقني” بين الانتهاء والدمج.
• المنطق: يمثل الوقت من أول التزام (Commit) حتى دمج طلب السحب. كلما قل هذا الزمن، قلّ الحمل المعرفي (Cognitive Load) على المطور، وزادت ثقة الفريق في حركة الكود.
• التنفيذ الفني عبر GitHub:
  • البداية: pull_request.created_at (أو تاريخ أول commit).
  • النهاية: pull_request.merged_at.

[Metric_Card]

2. زمن استجابة المراجعة (Review Turnaround)

• الحالة المثالية: استجابة سريعة، نقاشات تقنية مثمرة في أقل من 4 ساعات.
• الاحتكاك: انتظار المطور لأيام للحصول على موافقة، مما يضطره لتبديل السياق (Context Switching).
• المنطق: مراجعة الكود هي عنق الزجاجة الأكبر في تدفق المهام. قياس زمن الانتظار يحدد ما إذا كانت ثقافة المراجعة في الفريق تعاونية أم تعطلية.
• التنفيذ الفني عبر GitHub:
  • الحساب: الفرق الزمني بين pull_request.review_requested وأول pull_request_review.submitted_at.

[Metric_Card]

3. كثافة التغيير (Change Size Density)

• الحالة المثالية: طلبات سحب صغيرة، مركزة، وسهلة المراجعة (أقل من 200 سطر).
• الاحتكاك: طلب سحب يضم 2000 سطر يغير 5 ملفات غير مترابطة.
• المنطق: طلبات السحب الكبيرة هي عدو الجودة. كلما زاد الحجم، قلت دقة المراجعة وزادت احتمالية ظهور الأخطاء في الإنتاج.
• التنفيذ الفني عبر GitHub:
  • الحقول: pull_request.additions + pull_request.deletions.

[Metric_Card]

4. معدل النجاح من المحاولة الأولى (First-Pass Approval Rate)

• الحالة المثالية: وضوح تام في المتطلبات، الكود يوافق عليه من أول مراجعة.
• الاحتكاك: دورات لا نهائية من “طلب التغييرات” بسبب سوء فهم المتطلبات أو ضعف المعايير.
• المنطق: هذا المقياس لا يقيس ذكاء المطور، بل يقيس “وضوح السياق”. إذا كانت النسبة منخفضة، فالمشكلة في مرحلة التخطيط قبل كتابة الكود.
• التنفيذ الفني عبر GitHub:
  • الفلترة: النسبة المئوية للـ PRs التي حصلت على state: APPROVED دون وجود أي state: CHANGES_REQUESTED مسبقاً.

---

كيفية الربط (How-To Integration)

لجلب هذه البيانات وبناء لوحة معلوماتك الخاصة، نوصي باستخدام GitHub GraphQL API للحصول على دقة عالية وبيانات مجمعة في طلب واحد.

[Code_Block]

# استعلام لجلب بيانات التدفق لآخر 10 طلبات سحب دُمجت
query GetFlowMetrics($owner: String!, $repo: String!) {
  repository(owner: $owner, name: $repo) {
    pullRequests(last: 10, states: MERGED) {
      nodes {
        title
        createdAt
        mergedAt
        additions
        deletions
        reviews(first: 1) {
          nodes {
            submittedAt
          }
        }
      }
    }
  }
}

لأتمتة القياس أسبوعياً، يمكن استخدام GitHub Actions لإرسال هذه البيانات إلى مستودع مركزي أو Dashboard خارجية:

[Code_Block]

name: Metrics Lab Exporter
on:
  pull_request:
    types: [closed]

jobs:
  export_metrics:
    if: github.event.pull_request.merged == true
    runs-on: ubuntu-latest
    steps:
      - name: Calculate Flow
        run: |
          echo "PR Merged in: ${{ github.event.pull_request.merged_at }}"
          # ارسل البيانات إلى قاعدة بيانات القياسات الخاصة بك

---

دليل البصريات (Visual Guidelines)

يجب أن تتبع لوحة بيانات مختبر المقاييس فلسفة “الحد الأدنى من التشتت”:

• السمة اللونية (Monochrome): استخدم تدرجات الرمادي والأسود. اللون يستخدم فقط للإشارة إلى الاحتکار (مثلاً: أحمر خافت جداً لزمن الانتظار الذي يتجاوز 24 ساعة).
• الرسوم البيانية (Bar Charts): استخدمها لمقارنة زمن الدورة أسبوعياً.
• خرائط الحرارة (Heatmaps): لتوضيح أوقات ذروة المراجعات خلال أيام الأسبوع، مما يساعد في تحديد “أوقات التركيز العميق”.
• الخطوط (Typography): خطوط Sans-serif نظيفة (مثل Inter أو Outfit) للعناوين، وخطوط Monospace للقيم الرقمية التقنية.

---

محاذير: ما لا نقيسه ولماذا؟ (Anti-Patterns)

في مختبرنا، نعتبر المقاييس التالية “سامة” ويُمنع تتبعها:

1. عدد أسطر الكود (Lines of Code): لأن الكود “تكلفة” وليس “ربح”. المطور الذي يحذف 100 سطر ويؤدي نفس الوظيفة هو الأكثر إنجازاً.
2. تكرار الالتزام (Commit Frequency): هذا المقياس يشجع على تقسيم العمل بشكل وهمي ولا يعبر عن القيمة.
3. ترتيب المطورين (Individual Ranking): أي ربط للمقاييس بالتقييم الفردي سيؤدي فوراً إلى “تلاعب بالنظام” (Gaming the system) وفقدان ثقة الفريق.

---

خاتمة: نداء للقادة الهندسيين

البيانات التي توفرها GitHub ليست غاية في حد ذاتها، بل هي مرآة تعكس ثقافة العمل في فريقك. ابدأ اليوم بتبني “المقاييس التي تحترم الإنسان”.

هل أنت مستعد لتحويل مؤسستك إلى بيئة قائمة على التدفق؟

---

جميع الحقوق محفوظة © 2026 لمختبر DX Arabic.