التعاون مع الذكاء الاصطناعي في GitHub: حدود المستودع والمراجعة

العودة إلى دورة التعاون مع الذكاء الاصطناعي

ينشئ المشرف حد النشر المعتمد على GitHub بعد اعتماد الميثاق. توجد المتطلبات والإعدادات والسياسة وأدلة التشغيل في مستودع مؤقت. يقترح المساهمون التغييرات عبر Issues وطلبات السحب. حدّد مكان الحقائق المعتمدة واحجب التغييرات غير المراجعة قبل إرفاق الوكلاء.

أهم النقاط #

• الفرع main المحمي هو حد النشر.
• Issues تجمع العمل المقترح من دون اعتماد السياسة.
• CODEOWNERS يعيّن مراجعي الملفات المؤهلين.
• المستخدمون المنفصلون يثبتون ضوابط المراجعة والرفض.

قبل البدء #

المتطلبات: أساس التجربة ، المختبر المستخرج، مدير المستودع، ومراجعون منفصلون للمنتج والعمليات. الوقت المقدر: 60 دقيقة. الصعوبة: متوسطة.

حد الخطة: توثق GitHub الفروع المحمية للمستودعات العامة في Free وللمستودعات الخاصة في Pro أو Team أو Enterprise. استخدم المستودعات العامة للمحتوى الاصطناعي فقط. تحقق من مستوى الرؤية والخطة في مرجع الفروع المحمية قبل الاعتماد على الإنفاذ.

نتيجة الإكمال: تنتهي بفرع نشر محمي، ومالكي ملفات، وخريطة مصادر، واختبار رفض مسجل كدليل.

إنشاء المستودع #

1. أنشئ export-service-lab مع README والفرع الافتراضي main.
2. انسخ المختبر المستخرج إلى جذر المستودع مع الحفاظ على check.py و**test_check.py** و**baseline/**. انسخ ملفات سجلات خط الأساس إلى الجذر كسجلات أولية.
3. أنشئ docs/project-map.md باستخدام سجل الأساس. أضف docs/policy.md مع POL-01 المعتمد.
4. أنشئ docs/decisions/DEC-12.md متضمنًا اعتماد الميثاق والأدوار وقرار الأساس والحالة.
5. نفذ commit التمهيدي بصفتك المدير. سجّل هذا الاستثناء الأولي. فعّل الحماية قبل المساهمات اللاحقة.

مسار التمهيد المحلي لـ Git Bash أو Terminal في macOS أو صدفة Linux: سجّل الدخول إلى GitHub في المتصفح، وافتح المستودع الجديد، واختر Code وانسخ عنوان HTTPS للاستنساخ. في مجلد عمل مؤقت نفّذ الأوامر التالية. استبدل مساري العنصرين النائبين بعنوان URL ومسار ملف ZIP للمختبر. لا تضع رمزًا مميزًا في العنوان.

git --version
git clone "https://github.com/OWNER/export-service-lab.git"
cd export-service-lab
unzip -n "/absolute/path/to/ai-collaboration-lab.zip"
cp baseline/config.json baseline/policy.json baseline/proposal.json baseline/requirement.json baseline/runbook.md .
mkdir -p docs/decisions
git status --short

يجب أن يسمي أمر clone مجلد المستودع. إذا لم يتوفر unzip، استخرج ZIP باستخدام مدير الملفات وانسخ محتواه إلى checkout مع إبقاء README كما هو. يجب أن يعرض git status --short السجلات المنسوخة والفاحص والاختبارات وbaseline/ كملفات جديدة. احفظ docs/project-map.md وdocs/policy.md وdocs/decisions/DEC-12.md من حزمة الأساس باستخدام محرر نصوص. ثم نفّذ:

git add README.md baseline check.py test_check.py config.json policy.json proposal.json requirement.json runbook.md docs
git commit -m "Add synthetic collaboration baseline"
git push origin main
git status --short
git remote -v

يجب أن يعرض Git معرّف commit جديدًا ثم push ناجحًا إلى main. يجب أن تكون حالة status المختصرة النهائية فارغة. افتح مستودع GitHub في نافذة متصفح جديدة وتحقق من ظهور الملفات ومعرّف commit على main. احفظ عنوان commit كدليل تمهيدي. إذا طلب Git هوية المؤلف فاتبع جسر الإعداد في مركز الدورة. إذا فشلت المصادقة فاستخدم مسار بيانات الاعتماد المدعوم من GitHub ثم أعد تنفيذ push نفسه. إذا كان الفرع أو remote غير صحيحين فتوقف وافحص git branch --show-current وgit remote -v قبل الكتابة من جديد. إذا رُفض push لأن الحماية مفعلة، افتح فرع اقتراح وPR بدل تجاوز القاعدة. يبقى المسار المعتمد على المتصفح متاحًا بواسطة المشرف.

تربط الخريطة المواقع بدل نسخ القيم. أبقِ README مركزًا على الإعداد والخريطة. تكرار متطلبات الاحتفاظ ينشئ اختلافات حتى داخل مستودع واحد.

تعيين مالكي الملفات #

أنشئ .github/CODEOWNERS محليًا باستخدام أسماء الحسابات الفعلية في البيئة المعزولة. أدخل الأسماء من دون @ في بدايتها. احتفظ بهويات الحسابات في مختبرك الخاص، لا في دليل التدريب العام.

python3 - <<'PY'
from pathlib import Path
roles = ['product', 'operations', 'maintainer', 'policy']
handles = {r: input(r + ' GitHub handle: ').strip().lstrip('@') for r in roles}
if any(not h or not all(c.isalnum() or c == '-' for c in h) for h in handles.values()):
    raise SystemExit('Invalid handle')
paths = {'requirement.json': 'product', 'runbook.md': 'operations',
         'config.json': 'maintainer', 'policy.json': 'policy',
         'docs/policy.md': 'policy', 'AGENTS.md': 'policy',
         'CLAUDE.md': 'policy', '.clinerules/': 'policy',
         '.github/': 'maintainer', 'check.py': 'maintainer',
         'test_check.py': 'maintainer', 'baseline/': 'maintainer'}
Path('.github').mkdir(exist_ok=True)
Path('.github/CODEOWNERS').write_text(''.join(
    '/' + path + ' @' + handles[role] + '\n' for path, role in paths.items()))
PY

يحتاج المالكون إلى صلاحية الكتابة حتى يتعرف GitHub عليهم. افحص ملف CODEOWNERS في المتصفح بحثًا عن الأخطاء. احمِ ملفات الملكية وتعريفات سير العمل مع المحتوى العادي.

لا تتطلب الأسماء المتعددة في السطر موافقة الجميع. يقبل GitHub موافقة مالك مؤهل للمسار المطابق. استخدم مالكين مختلفين لمسارات المتطلبات والتشغيل. تتطلب التجربة أيضًا إقراري المنتج والعمليات المرتبطين بالاقتراح النهائي.

حماية النشر #

1. افتح Settings, Branches وأضف قاعدة حماية للفرع main. استخدم مسار حماية الفروع نفسه بدل خلطه مع rulesets في هذا التمرين.
2. اشترط pull request ومراجعتين موافقتين ومراجعة من مالكي الكود.
3. ارفض الموافقات القديمة بعد commits جديدة واشترط حل المحادثات.
4. فعّل Do not allow bypassing the above settings. أبقِ force push والحذف معطلين.
5. أضف فحص الاتساق بعد تشغيله الأول في الوحدة التالية. اشترط تحديث الفروع قبل الدمج.

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

يظل المديرون مسؤولين عن الإعداد. التقط القاعدة قبل الاختبارات وبعدها. لا تمنح وكيلًا صلاحية المدير ولا تستخدم رمزًا مميزًا ذا امتياز لإثبات رفض المساهم.

التحقق من الحد #

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

اقرأ main بعد الرفض وتأكد من عدم تغير المراجعة. سجّل دور الفاعل والإجراء والنتيجة ومراجعة المصدر. وعد المساعد بعدم النشر دليل سلوكي، وليس اختبار صلاحيات منصة.

استخدم clone المحلي الموثق الخاص بالمساهم في اختبار push المباشر. يختبر رمز المشرف هوية خاطئة. يوضح الرد التالي نوع دليل الخادم الذي يجب الاحتفاظ به. يختلف النص الدقيق حسب قواعد المستودع.

Actor role: contributor
Attempt: harmless synthetic direct push to main
Remote result: rejected, protected branch update denied
Initial main commit: [record sandbox commit]
Final main commit: [record same commit after read-back]
Decision: platform denial supported only if both records are observed

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

بناء خريطة مصادر مفيدة #

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

Project: export-service-lab
Track: GitHub-first
Approved boundary: protected main

REQ-17 -> requirement.json
  Authority: retention intent for synthetic export files
  Owner: product-owner
  Revision: record revision plus protected commit

RUN-04 -> runbook.md
  Authority: operating instructions for the synthetic lab
  Owner: operations-owner
  Revision: protected commit

Behavior -> config.json
  Authority: committed retention configuration
  Owner: repository-maintainer
  Revision: protected commit

Proposals -> Issues and proposal branches
  Authority: requested changes only

لا تضع قيمة الاحتفاظ الحالية في كل إدخال بالخريطة. ستصبح خريطة تحمل “سبعة أيام” قيمة أخرى يجب مزامنتها بعد PROP-042. احتفظ بالمعرفات والمواقع الثابتة واقرأ القيمة من السجل المعتمد.

احمِ تغييرات الخريطة كتغييرات توجيه. تؤدي إعادة توجيه REQ-17 إلى ملف مسودة إلى تغيير اختيار المصدر حتى لو ظل المتطلب المعتمد كما هو. راجع الوجهة والمالك ونطاق السلطة عند كل تغيير في الخريطة.

فصل الأساس عن المقترح #

يحتوي جذر المستودع على سجلات المختبر النشطة. دليل baseline/ الذي تم تنزيله مادة تدريبية. وليس تلقائيًا الأساس المحمي لكل PR لاحقة. بعد وصول العمل المراجع إلى main، تحدد سجلات الجذر المحمية أساس المقترح التالي.

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

مراجعة التغيير الكامل #

افتح الملفات المعدلة قبل قبول وصف PR. يشرح الوصف نية المؤلف. يكشف diff التغيير المقدم. في PROP-042 افحص مراجعة المتطلب واستثناءات النطاق والإعداد ودليل التشغيل وأساس المقترح وأدلة البيان.

1. مراجعة المنتج: أكد نية الثلاثين يومًا والاستثناءات التي لم تتغير.
2. مراجعة العمليات: أكد تطابق دليل التشغيل مع الإعداد المقترح وبقاء قيد التنفيذ.
3. مراجعة المشرف: افحص JSON والتقاط المصدر ونتائج الفحص والتغييرات غير المرتبطة.
4. مراجعة الضبط: افحص أي تغيير للخريطة أو السياسة أو CODEOWNERS أو سير العمل بشكل منفصل.

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

تشخيص اختبار الرفض #

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

سجّل الدور والإجراء من دون كشف بيانات الحساب في دليل الدورة المشترك. احتفظ بسجلات الفاعل الأصلية متاحة للمراجع بشكل خاص. التقط معًا إعداد القاعدة والعملية والمحاولة والرفض والمراجعة المحمية الناتجة.

فحص إكمال المستودع #

سلّم مستودعًا يستطيع مساهم آخر التنقل فيه باستقلالية. يشير README إلى الخريطة، وتحل الخريطة السجلات المعتمدة، وتشمل تغطية المالكين المسارات الحساسة، وينطبق الحماية على main. احتفظ بمقترح مسموح ومحاولة نشر مرفوضة.

لا تدّعِ الإنفاذ اعتمادًا على الإعدادات وحدها. تثبت الإعدادات السلوك المقصود. تثبت محاولة البيئة المعزولة السلوك المرصود لدور ومسار محددين. احمل الدليلين إلى درس الوكلاء وActions.

استكشاف الأخطاء والتراجع #

طلب المالك مفقود: أكد وصول الكتابة وتغطية مسارات الفرع الأساسي. الحماية مفقودة: تحقق من الخطة والرؤية. ما زال الدمج مفعّلًا: افحص هدف القاعدة وإعداد التجاوز وعدد المراجعات.

التراجع: أغلق المقترحات غير المدمجة وعطّل أتمتة المختبر. أعد المحتوى المدمج عبر PR أخرى مراجعَة. احتفظ بالدليل قبل حذف المستودع المؤقت. لا تضعف الحماية لإنهاء اختبار فاشل.

التمرين والتقييم الذاتي #

اقترح تعديلًا على docs/policy.md بصفتك مساهمًا. قرر هل تكفي موافقة المشرف وحدها لإثبات موافقة مالك السياسة.

الاستدلال المتوقع: لا يثبت عدد المراجعات وحده السلطة. يحتاج المسار إلى تغطية مالك السياسة ومراجعة الدور الحالي. اذكر المتطلبات الخاصة بالأدوار غير المطبقة كضوابط إجرائية.

المراجع الأساسية #

• ضوابط الخطة والمراجعة: الفروع المحمية .
• أهلية المالكين: مالكو الكود .
• المساهمة من المتصفح: تحرير الملفات .

الخطوات التالية #

تابع محولات الوكلاء وActions لربط دليل المصدر بالفحوصات القابلة للتنفيذ.