الإصدارات والتصحيحات

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

القاعدة الأساسية: ننشر كل dataset يحتوي على نص قرآني في إصدارات دون تعديله مباشرة، وتحمل كل نسخة منه رقم إصدارها أينما استُخدمت، ونوثّق كل تغيير بين إصدارين محرفًا محرفًا.

توضح صفحة النص أن النص ثابت لا يُعدل، وأن كل تصحيح يُعلن عنه، وتشرح هذه الصفحة كيف نلتزم بذلك بعد نشر البيانات خارج جهازك. وصيغتا manifest وسجل التصحيح أدناه مقترحتان، وتتبع أسماء حقولهما القاموس متى وُجد فيه اسم للحقل.

1. ما الذي نرقّم إصداراته

نرقّم إصدارات dataset بصورة مستقلة عن المستودع أو التطبيق.

1.1 يحتوي كل dataset على نوع واحد من البيانات المبنية على النص، مثل نص طبعة أو جدول عد الآي أو تقسيم أو ملف توقيت أو ترجمة، وله رقم إصدار مستقل.

يفحصه: ملف manifest واحد لكل ملف بيانات، يتحقق منه سكربت الإصدار.

1.2 انشر بجانب كل ملف بيانات ملف dataset.json يعرّفها بذكر الطبعة والرواية ونظام عد الآي والإصدار وبصمة المصدر، حتى تبقى معلومات هويتها مرافقة لها.

{
  "dataset": "text",
  "mushaf_edition": "madinah_hafs_1441",
  "riwayah": "hafs_an_asim",
  "ayah_numbering_system": "kufi",
  "version": "2.0.0",
  "source_hash": "sha256:…",
  "derived_from": null,
  "license": "…",
  "errata": "errata.json",
  "released": "2026-09-06"
}

تأتي قيمتا mushaf_edition وriwayah من السجلات في standards/terminology/registries/، ولا تُكتبان باليد.

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

1.3 اكتب رقم الإصدار في manifest ووسم المستودع بالنص نفسه تمامًا.

يفحصه: يقارن سكربت الإصدار الوسم بحقل version في manifest ويتوقف عند الاختلاف.

2. الترقيم الدلالي للبيانات

حدد رقم الإصدار بحسب التغييرات الفعلية، مهما بدا التصحيح بسيطًا.

2.1 ارفع MAJOR عند تغيير أي محرف منقول أو حد من حدود الآيات أو معرف، حتى عند تصحيح ما يبدو خطأ إملائيًا.

يغير تصحيح محرف واحد كل البصمات المحسوبة من النص، ولذلك يتطلب رفع MAJOR.

يفحصه: يقارن سكربت الإصدار النص بنص الوسم السابق، ويرفض رفع MINOR أو PATCH إذا اختلف أي بايت من النص.

2.2 ارفع MINOR عند إضافة طبقة مشتقة أو بيانات وصفية دون تغيير النص المنقول أو المعرفات.

يفحصه: المقارنة نفسها، وتسمح برفع الرقم إذا بقي النص كما هو.

2.3 ارفع PATCH عندما تقتصر التغييرات على بيانات وصفية لا تمس النص، مثل الوصف أو ملف الرخصة أو ترتيب الملفات على القرص.

يفحصه: المقارنة نفسها.

2.4 يتبع الكود الذي يقرأ البيانات الترقيم الدلالي المعتاد وله رقم إصدار خاص به، ولا يرتبط رقم الكود برقم البيانات.

يفحصه: صفحة المستودعات التي تفصل ترقيم الكود عن ترقيم البيانات.

3. ثبات معنى المعرفات

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

3.1 يحتفظ الإصدار N+1 بجميع معرفات الإصدار N، وإذا غاب أي منها فالتغيير يتطلب رفع MAJOR على الأقل وذكر المعرفات المفقودة في سجل التصحيحات.

يفحصه: مقارنة مجموعتي المعرفات بين الوسمين في سكربت الإصدار.

3.2 أضف نظام عد الآي في جدول أو عمود جديد مفتاحه ayah_numbering_system، مع إبقاء الأرقام الموجودة كما هي.

يفحصه: مقارنة مجموعتي المعرفات.

3.3 إذا تبين خطأ معرف، فأضف معرفًا جديدًا وأبقِ القديم مع الإشارة إلى أن غيره حل محله، دون تعديله مباشرة.

يفحصه: مقارنة مجموعتي المعرفات.

4. سجل التصحيحات

وثّق كل تصحيح قبل دمجه في ملف واحد لكل dataset، وأضف إليه مداخل جديدة دون تعديل المداخل السابقة.

4.1 استخدم errata.json لسجل التصحيحات، أو ERRATA.md إذا كان dataset منشورًا في صورة نص مقروء، وأضف مداخل جديدة دون تعديل المداخل السابقة أو حذفها.

{
  "id": "2026-0001",
  "location": { "surah_number": 2, "ayah_number": 255, "word_position": 12,
                "ayah_numbering_system": "kufi" },
  "offset": { "unit": "codepoint", "start": 38, "end": 39 },
  "before": "U+0651 U+064E",
  "after":  "U+064E U+0651",
  "kind": "transmission_error",
  "confirmed_by": "…",
  "confirmed_on": "2026-08-30",
  "fixed_in": "2.0.0"
}

يفحصه: التحقق من وجود مدخل تصحيح واحد لكل تغيير في نص الإصدار، ومن أن كل مدخل يذكر رقم ذلك الإصدار في fixed_in يقابل تغييرًا واحدًا.

4.2 خزّن في before وafter تسلسل قيم codepoint بدل النص كما يظهر على الشاشة، حتى يمكن التحقق من المدخل دون الاعتماد على خط.

يفحصه: التحقق من وجود تسلسل before في الموضع المحدد بحقلَي location وoffset في الإصدار السابق.

4.3 اختر لـkind إحدى القيم source_error أو transmission_error أو display_error، وأصلح خطأ العرض في محرك العرض دون تغيير النص، وسجله حتى لا يعدّل أحد النص ليطابق ما يظهر على الشاشة.

يفحصه: التحقق من مطابقة مدخل التصحيح للمخطط.

4.4 اذكر في confirmed_by من أكد صحة التصحيح، سواء كان ناشر الطبعة أو مراجعًا محددًا في المستودع، ولا تدمج مدخلًا يخلو من هذا التأكيد.

يفحصه: التحقق من المطابقة للمخطط ومراجعة ثانية لكل تغيير في النص.

4.5 سجّل التصحيح قبل دمج الإصلاح في طلب الدمج نفسه أو في طلب سابق، وارفض عند المراجعة أي تغيير في النص لا يقابله مدخل في سجل التصحيحات.

يفحصه: مطابقة تغييرات النص بمداخل سجل التصحيحات مع كل طلب دمج يغير النص.

5. الإعلان عن التغيير

أعلن كل تحديث للنص.

5.1 أعلن إصدار MAJOR قبل نشره أو عند نشره، مع وصف في سجل التغييرات يقرؤه المستخدم وقائمة مقروءة آليًا بالتصحيحات التي يتضمنها.

2.0.0 — 2026-09-06 — MAJOR — النص: 1 تصحيح (2026-0001، 2:255)؛ المعرفات دون تغيير.

يفحصه: يرفض سكربت الإصدار وسم MAJOR دون مدخل في سجل التغييرات وقائمة تصحيحات.

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

يفحصه: اختبار مسار التحديث مع سجل إشعار ودونه.

5.3 يرفض التطبيق عند التحديث أي dataset تختلف قيمة MAJOR فيه عن الإصدار المثبّت، ما لم يوجد سجل إشعار بهذا الانتقال.

يفحصه: اختبار مسار التحديث نفسه.

5.4 يحتاج إصدار MINOR أو PATCH إلى مدخل في سجل التغييرات فقط.

يفحصه: سكربت الإصدار.

6. ما يمكن للمشاريع التي تستخدم بياناتنا الاعتماد عليه

ما دامت قيمة MAJOR ثابتة، نضمن ثبات بايتات النص والمعرفات وحدود الآيات وبصمة المصدر فقط.

6.1 تذكر الطبقة المشتقة الإصدار الذي بُنيت منه تحديدًا في derived_from، ويفشل البناء إذا ذكرت إصدارًا غير موجود.

يفحصه: البحث في فهرس الإصدارات عند البناء.

6.2 لا تصلح الطبقة المشتقة المبنية على الإصدار N للاستخدام مع الإصدار N+1 إلا بعد إعادة بنائها، أو تسجيل التحقق من عدم تأثرها بالتصحيحات في ملف manifest الخاص بها.

يفحصه: فحص derived_from وفق الإصدار الحالي.

6.3 اعتمد على إصدار موسوم، ولا تعتمد على آخر نسخة من فرع.

يفحصه: رقم الإصدار المحدد للاعتماد عليه في manifest الخاص بالمشروع الذي يستخدم البيانات.

7. الإصدارات التي حل غيرها محلها

أبقِ الإصدار متاحًا، وأشر إلى أن إصدارًا آخر حل محله بدل حذفه.

7.1 أدرج في فهرس الإصدارات جميع الإصدارات المنشورة مع بصمة مصدر كل منها وتاريخه والإصدار الذي حل محله إن وجد.

يفحصه: مقارنة وسوم المستودع بفهرس الإصدارات.

7.2 أبقِ الإصدار الذي حل غيره محله متاحًا للتنزيل، حتى يمكن التحقق من الطبقات المبنية عليه بمقارنتها به، واذكر في الفهرس المدة التي يستمر فيها إرسال إشعارات تصحيحاته.

يفحصه: أداة hook ترفض حذف وسم أو دفع تغيير قسري إليه.

7.3 إذا وجدت خطأ في نص إصدار، فسجّل التصحيح وانشر إصدارًا مصححًا يحل محله دون سحب الإصدار القديم.

سحبه يمنع التحقق من كل بصمة تشير إليه ويخفي ما تغير.

يفحصه: أداة hook نفسها.

8. قبل نشر إصدار موسوم

تخص القواعد السابقة dataset له إصدار منشور، لكن معظم ما لدينا لم يُوسم بعد، ويحتاج القارئ إلى معرفة القواعد التي تنطبق عليه إلى ذلك الحين.

8.1 اعتمد commit إصدارًا لـdataset إلى أن يُوسم، وثبّت الاعتماد على commit محدد وسجّله واقرأ كل الملفات من ذلك المرجع.

السكربت الذي يختار آخر commit في الفرع وقت البناء لا يعتمد على نسخة ثابتة.

يفحصه: يحدد ملف manifest في المشروع الذي يستخدم البيانات قيمة commit، وتقرأ خطوة في البناء البيانات من ذلك commit وحده.

8.2 حدّد ما تثبّت الاعتماد عليه من 3 أشياء مختلفة: شجرة الملفات بقيمة commit، والملف المضغوط ببصمة ملف الإصدار، والنص الذي حُسب تعليق بناءً عليه ببصمة المحتوى المسجلة داخل البيانات.

يفحصه: مراجعة ما يُسجّل في ملف manifest.

8.3 ميّز بين format_version الذي يصف صيغة الملف وschema_version الذي يصف مخططه والوسم الذي يحدد الإصدار وبصمة المحتوى التي تحدد النص، ولا تعتمد على ثبات format_version دليلًا على أن البيانات لم تتغير.

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

8.4 احتفظ ببصمة المصدر ومرجعه في سجلات المشروع الذي يستخدم البيانات، فتثبيت الاعتماد يضمن البايتات وحدها، وقد تتعذر إعادة بناء الحزمة المنشورة من قيم commit الخاصة بها أو يُضاف تصحيح قبل تغيير رقم الإصدار، ولا ترافق البصمة البيانات عند إعادة تصديرها.

يفحصه: مراجعة ما يحفظه المشروع بجانب نسخته من البيانات.

المصدر: quran-ws/docs، عند d1d6be33be9d. ما لم يُوسم «معتمد» فهو مقترح للنقاش، ولا يُبنى عليه بعد.