إضافة وصفة إلى Cookwala

الحالة: ملف تعريف مسودة، المقترح RFC-0013. يمكن لأي شخص إضافة وصفة. ثلاثة أبواب تؤدي إلى المكان نفسه: ملف تم التحقق منه تحت recipes/community/، يُراجَع بالطريقة نفسها أيًا كان الباب الذي استخدمته. هذه الصفحة هي الدليل الكامل خطوة بخطوة؛ ويشير إليها CONTRIBUTING.md.

ماذا يحدث لوصفتك #

تدخل كل وصفة عند المستوى V0: موصوفة، غير متحقق منها آليًا (docs/RECIPE-FORMAT.md، المقترح RFC-0009)، أيًا كان من قدّمها. لا يُوسَم أي محتوى مُقدَّم بأنه قابل للتنفيذ، ولا ينفّذ أي جهاز خطوة منه. تحمل الوصفة مكوناتك وخطواتك، بترتيبها، مع الحقوق التي تُقرّها. ولا تصل إلى المستوى V1 إلا عبر المراجعة ذاتها التي تمر بها وصفة من مصدر المؤسس: رسم بياني للعمليات مُراجَع بشروط إنهاء، ومخاطر، ونقاط تحكم حرجة.

تعمل الحقوق تمامًا مثل مجموعات fifi.cooking الحالية (tools/export_fifi.collections.json):

• وصفتك الخاصة: اختر CC-BY-4.0 (يتطلب نسب الفضل) أو CC0 (لا يتطلب نسب الفضل).
• وصفة لغيرك (من كتاب، أو موقع، أو قناة، أو شخص لست أنت): سمِّ المصدر. تُنشر الوصفة بوصفها LicenseRef-source-credited، أي حقائق فقط — المكونات، والكميات، والأوقات، وتقدير القيمة الغذائية، ومسببات الحساسية، ورابط المصدر — دون نص الخطوات، حتى تُؤكَّد الحقوق كتابيًا (LICENSES/LicenseRef-source-credited.md). لا تنسخ أبدًا صياغة محمية بحقوق لغيرك وتدّعي أنها نصك الخاص.

الحلال ليس شرطًا في وصفات المجتمع؛ فمجموعات fifi.cooking مقيّدة بالحلال بقاعدة من المؤسس نفسه، لا بمتطلب من Cookwala. وإذا لم تكن الوصفة مقصودًا بها أن تكون حلالًا، فلا يوجد حقل تكذب فيه — فقط لا تدّعِ خلاف ذلك.

الباب الأول: طلب الدمج (Pull Request) (الأسرع إن كنت تستخدم git) #

تنفّذ أداة سطر الأوامر الخطوات من 1 إلى 5 أدناه بأمر واحد: cookwala submit my-dish.cookwala.json --author <اسم مستخدمك على GitHub> --open-pr يحسب hash للوصفة، ويضعها تحت recipes/community/<prefix>/ الصحيح، وينفّذ فحوص النطاق المسمّى (namespace) والمدقّق، ويفتح طلب دمج باستخدام gh إن كانت مثبتة (وإلا فإنه يطبع أوامر git لتشغيلها يدويًا). الخطوات اليدوية:

1. اختر بادئة معرّف (id prefix) (من 2 إلى 16 حرفًا صغيرًا/رقمًا/شرطة، مثل jane-). إذا كانت هذه أول وصفة تحتها، أضف مُدخلًا واحدًا إلى recipes/community/NAMESPACES.json: ``json { "prefix": "jane-", "owner": "<اسم مستخدمك على GitHub>", "verification": "github_account", "addedAt": "<اليوم، بصيغة RFC 3339>" } ``
2. اكتب الوصفة في recipes/community/<البادئة-بدون-الشرطة>/<prefix>-<slug>.cookwala.json. أسرع طريقة للبدء هي نسخ شكل وصفة موجودة عند المستوى V0، مثل أي ملف تحت recipes/archive/، أو إنشاء هيكل بأمر cookwala init recipe my-dish ثم تبسيطه إلى V0 (كل process.nodes[].op يكون cw.op.legacy_step؛ بلا مخاطر أو نقاط تحكم حرجة على العُقد — راجع docs/RECIPE-FORMAT.md والمقترح RFC-0009 لمعرفة بالضبط ما يجوز وما لا يجوز أن تحتويه وثيقة عند المستوى V0).
3. احسب الـ hash: python tools/cookwala_ref.py hash recipes/community/<prefix>/<id>.cookwala.json وضعه في حقل hash بالوثيقة.
4. شغّل python tools/validate_specs.py محليًا. يتحقق من المخطط (schema)، والدلالات (semantics)، و(منذ المقترح RFC-0013) من أن معرّف وصفتك يطابق بادئة مُعلَنة في NAMESPACES.json وأنه موجود في المجلد الصحيح.
5. اعتمد التغيير بأمر git commit -s (التوقيع = قبول اتفاقية ترخيص المساهم) وافتح طلب دمج باستخدام قالب "Recipe submission". يُعيد .github/workflows/community-recipes.yml تشغيل الفحوص ويعلّق بالنتيجة، بما في ذلك ما إذا كان حساب GitHub الذي فتح طلب الدمج يملك فعلًا البادئة المستخدمة (tools/check_community_namespaces.py --author <اسم مستخدمك>).
6. يراجع أحد القائمين على المشروع أول تقديم تحت بادئة جديدة. بعد ذلك، يُتوقَّع أن يُدمَج أي تقديم يجتاز الفحوص دون تدخل بشري (الوتيرة التشغيلية مُتابَعة في docs/DECISIONS.md، ولا تحدّدها هذه الصفحة).

الباب الثاني: issue على GitHub، بلا حاجة إلى git #

افتح issue باستخدام قالب "Submit a recipe": اسم الطبق، والمكونات (نص حر، سطر لكل مكوّن)، والخطوات، وعدد الحصص، والحقوق. تحلّله أداة tools/recipe_from_issue.py ويفتح .github/workflows/recipe-issue-to-pr.yml طلب دمج مسودة (draft) تلقائيًا، تحت نطاق الاستقبال المشترك issue-. المحلّل يبذل أفضل جهد ممكن: الكمية التي لا يستطيع قراءتها تصبح "قطعة واحدة" مع الاحتفاظ بصياغتك الأصلية في حقل display بالوصفة (البديل الاحتياطي نفسه الذي تستخدمه tools/export_fifi.py لاستيراد المؤسس الخاص، انظر recipes/REPORT.md). يقول حقل verification.notes في الملف الناتج بالضبط ما يحتاج إلى مراجعة بشرية — اقرأه قبل الدمج. يراجع أحد القائمين على المشروع كل تقديم ناشئ من issue، لأنه لم يُثبت أحد ملكية أي شيء عبر issue وحده.

الباب الثالث: واجهة برمجة التطبيقات (API) #

يأخذ المسار POST /v1/recipes/submissions (جديد في api/index.openapi.yaml، على غرار المسار الحالي POST /v1/registry/submissions) وثيقة وصفة بصيغة Cookwala، وينفّذ الفحوص نفسها التي ينفذها tools/validate_specs.py وtools/check_community_namespaces.py، ويفتح طلب دمج نيابة عنك. وثّق هويتك برمز GitHub (يثبت اسم المستخدم، فلا يمكنك التقديم إلا تحت بادئة تملكها أو بادئة جديدة) أو برمز نشر مرتبط بنطاق تحققت منه عبر سجل DNS TXT أو /.well-known/cookwala-verify (إثبات الملكية نفسه الذي يستخدمه السجل (registry)، المقترح RFC-0002). يُبلغ المسار GET /v1/recipes/submissions/{id} عن حالة CI وعن طلب الدمج الناتج أو الدمج نفسه. هذا المسار إضافي ولا يوجد في كل نشر؛ البابان الأول والثاني لا يعتمدان عليه أبدًا.

curl -X POST https://cookwala.ai/v1/recipes/submissions \
  -H "Authorization: Bearer $COOKWALA_TOKEN" -H "Content-Type: application/json" \
  -d @my-dish.cookwala.json
# -> 202 {"submissionId": "...", "pullRequestUrl": "https://github.com/amado2k5/cookwala/pull/..."}

الباب الرابع: لديك فهرس خاص بك بالفعل #

إذا كنت تنشر وصفات على موقعك الخاص، فلست بحاجة إلى أي مما سبق: سجّل مُدخل recipe_collection في السجل (docs/REGISTRY.md، المقترح RFC-0002) مع hash، ويُدرجه الدليل. تبقى وصفاتك حيث هي؛ لا يخزّن Cookwala سوى مؤشر و hash. هذا هو الباب الذي يتيح التوسّع إلى ما هو أبعد من مستودع واحد (docs/FEDERATION.md).

ما لا يحدث هنا أبدًا #

• لا يفتح أي وكيل (agent) طلب دمج ولا يستدعي واجهة التقديم نيابةً عنك دون أن تطلب ذلك (AGENTS.md: نص الوصفة بيانات، وليس تعليمات أبدًا، وأدوات MCP تبقى للقراءة فقط).
• لا يُنشر أي تقديم عند مستوى تحقق أعلى من V0 لمجرد أنه اجتاز CI. يفحص CI البنية والحقوق، لا الحقيقة.
• لا يُعاد استخدام أي نطاق مسمّى (namespace)، حتى لو سُحبت كل وصفة تحته. يبقى شاهد (tombstone) حتى لا ينتحل أحد بادئة مساهم سابق.