حزم التغيير

حزمة التغيير ملف YAML يصف تغييرًا واحدًا في الواجهة البرمجية، بحيث يتفق فريق الخادم وفريق الويب عليه دون مستند تسليم. يوجد الملف في المستودع نفسه الذي يوجد فيه الكود، ويكتبه Getman ولا يكتبه الإنسان يدويًا.

ما تحتويه حزمة التغيير

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

الملفات في مساحة العمل

getman/
  contracts/openapi.yaml          العقد الحالي للواجهة البرمجية (OpenAPI 3.1)
  changes/GT-SHOP-001.yaml        ملف واحد لكل حزمة تغيير

المرجع GT-SHOP-001 مثال فقط. صيغة المعرّف هي GT-<KEY>-<NNN>. يُشتق المفتاح من اسم المشروع (أحرف وأرقام فقط، بحروف كبيرة، بحد أقصى 12 حرفًا)، أو من الإعداد changeKey. الرقم هو أعلى رقم موجود لهذا المفتاح زائد واحد، وبما لا يقل عن ثلاثة أرقام. لا تُكتب الأسرار في هذه الملفات أبدًا.

الحقول الرئيسية

الحقل	المعنى
id	مرجع التغيير، مثل GT-SHOP-001.
title وsummary وmigration	ما الذي تغيّر، وما الذي يجب على المستهلكين فعله. نص الترحيل هو الجزء الذي يقرؤه فريق الويب أولًا.
state	draft أو published أو withdrawn. تبدأ الحزم الجديدة كمسودات.
author	kind (human أو agent)، وname، وtool اختياريًا. الأسماء للعرض فقط، ولا تمنح أي صلاحيات.
endpoints	العمليات المتأثرة، مثل GET /orders/{id}.
contract.base وcontract.head	المراجعة (هاش SHA-256 للعقد بعد تطبيعه) قبل التغيير وبعده.
contract.changes	إدخالات فرق منظمة، لكل منها نوع وموقع وقيمتان قبل وبعد، ودرجة خطورة.
severity	أعلى درجة خطورة في الفرق: breaking أو potentially-breaking أو non-breaking أو unknown.
evidence	إدخالات من تشغيلات حقيقية. يكتبها Getman وحده.
integrations	إدخال واحد لكل مستهلك، مع status تساوي pending أو in-progress أو reported أو verified أو blocked.

حالات التغيير

تنتقل الحالات بالأزرار الموجودة في رأس التغيير داخل تطبيق سطح المكتب، أو بالأمر getman change state، أو بأداة MCP باسم update_change. تختفي التغييرات المسحوبة من صناديق وارد المستهلكين.

الانتقال	زر سطح المكتب	CLI
من مسودة إلى منشور	Publish	getman change state <ID> published
من منشور إلى مسحوب	Withdraw	getman change state <ID> withdrawn
من مسحوب إلى منشور	Publish again	getman change state <ID> published
من منشور أو مسحوب إلى مسودة	Back to draft	getman change state <ID> draft

ملصقات التحقق

يُحسب الملصق الظاهر بجانب التغيير من أدلته، ولا يُخزَّن أبدًا.

الملصق	متى ينطبق
Not tested	لا توجد أدلة.
Documented	لا توجد أدلة، لكن لكل عملية وصف ومثال.
Schema validated	طابق آخر تشغيل مخططات الاستجابة، ولا توجد اختبارات معرّفة.
Tests passed	نجح آخر تشغيل على العقد الحالي في كل الاختبارات وفحوص المخطط.
Tests failed	يحتوي آخر تشغيل على فشل.
Integration reported	ضبط مستهلك حالته على reported.
Integration verified	ضبط مستهلك حالته على verified، مع تشغيل ناجح خاص به.

يُوسم الدليل المسجّل على مراجعة قديمة للعقد بأنه قديم. يظل الملصق ظاهرًا، مع علامة القِدم.

الأدلة

يسجّل كل إدخال دليل الوقت، والأداة التي شغّلته (سطح المكتب أو CLI أو MCP مع إصدارها)، واسم البيئة ونوعها، ومراجعة العقد التي جرى فحصها، والطلبات التي شُغّلت، ونتائج الاختبارات، وفحوص المخطط، والإجماليات. تُنقّح كل النصوص قبل كتابتها.

الدليل يأتي من تشغيل حقيقي فقط. لإنشائه، استخدم Verify now في تطبيق سطح المكتب، أو getman change verify، أو أداة MCP باسم verify_change. تُسجَّل التشغيلات الفاشلة أيضًا.

قواعد Git

• يستخدم Getman نسخة Git المثبتة لديك، مع بيانات اعتمادك ومفاتيح SSH الخاصة بك. لا يطلب كلمة مرور أبدًا.
• لا يُنفَّذ أي commit أو push أو pull دون إجراء صريح.
• يعمل git pull بالخيار --ff-only. يُبلَّغ عن الفرع المتباعد، ولا يدمجه Getman.
• عندما يتغير ملف محليًا وفي المجلد معًا، يُدرج ضمن التعارضات لتحله بنفسك.
• يُرفض الملف الذي ما زال يحتوي على علامات تعارض، أو على YAML غير صالح، مع ذكر مساره وتلميح للإصلاح.
• قد ينشئ نسختان من المستودع الرقم نفسه. يعرض Getman التكرار كتعارض. إعادة الترقيم يدوية: غيّر id، وأعد تسمية الملف ليطابقه، ثم نفّذ commit.

القيود

• لا يعيد التغيير كتابة المراجع إلى معرّفه القديم. تحقق من حقول related ورسائل commit والملفات الأخرى بعد إعادة الترقيم.
• لا يُقرأ اسم المؤلف من إعدادات Git.
• نص الترحيل والملخص نص عادي في تطبيق سطح المكتب.

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