المستودعات والترخيص

بنية المستودع وتغييرات commit والمراجعة والإصدارات، وما يمكن للمشاريع التي تعتمد علينا توقعه، والرخص التي ننشر كل ذلك بموجبها.

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

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

1. الترخيص

ننشر كل موادنا برخصة، أما النص القرآني فلا تشمله رخصة ولا ندّعي ملكيته.

1.1 الكود مرخص برخصة MIT والبيانات والمحتوى برخصة CC BY 4.0، ولا نطلب نسبة المصدر عند الاستخدام داخل منتج ونطلبها عند إعادة النشر.

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

يفحصه: اشتراط حقل license في مخطط manifest، والتحقق من ذكر كل مجلد رئيسي في LICENSE.

2. بنية المستودع

خصص المستودع لمنتج واحد أو dataset واحد.

2.1 يوضع كل dataset تشترك فيه عدة منتجات في مستودع مستقل له إصداراته الخاصة.

يفحصه: مراجعة الالتزام بالقاعدة يدويًا، فلا توجد أداة لفحصها.

2.2 اعتمد المصدر المقروء آليًا مرجعًا والصفحات شرحًا له، واترك كتابة المخرجات المولّدة لعملية البناء دون تعديلها يدويًا.

- run: python3 tools/build.py
- run: git diff --exit-code   # وجود تغييرات يعني أن أحدًا عدّل مخرجات مولّدة

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

2.3 أدرج المخرجات المولّدة في commit فقط عندما يحتاج المستخدم إلى الحصول عليها دون تشغيل البناء، مثل صفحة يقرؤها على GitHub أو مهارة يثبتها وكيل، مع إبقاء كتابتها حصرًا على عملية البناء.

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

2.4 اذكر في README غرض المستودع ثم طريقة تشغيله أو تثبيته ثم الرخصة ثم حالة محتوياته، بهذا الترتيب.

يفحصه: قاعدة للمراجعة.

3. تغييرات commit

يُحدث كل commit تغييرًا واحدًا، ويذكر عنوانه ما تغير بجملة عادية.

3.1 اكتب عنوان commit جملة واضحة تحدد التغيير المطلوب بدل عنوان عام، واشرح في المتن الحالة التي دعت إليه.

نعم:  أضف النص الإنجليزي لكل مدخل وولّد القاموس الإنجليزي
نعم:  احذف حركة الإعراب قبل اشتقاق الاسم
لا:   تحديث القاموس
لا:   fix(terminology): متفرقات

يفحصه: قاعدة للمراجعة.

3.2 خصص لتغيير بيانات النص القرآني commit مستقلًا عن تغييرات الكود وصفحات الشرح والمخرجات المولّدة، لأن مراجع النص يقرأ التغيير محرفًا محرفًا.

يفحصه: أداة hook ترفض أي commit يجمع تغيير ملف بيانات النص القرآني وتغيير أي نوع آخر من الملفات.

3.3 أبقِ سجل التغييرات المنشور كما هو، وأصلح أي خطأ في main بإضافة commit جديد يذكر commit الذي يصححه.

يفحصه: حماية الفرع main وكل وسم.

3.4 حدد مؤلف كل commit، سواء كان شخصًا أو روبوتًا معلوم الاسم، وأرفق بكل commit إقرارًا وفق Developer Certificate of Origin باستخدام git commit -s.

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

يفحصه: روبوت DCO يفحص سطر Signed-off-by في كل commit.

4. طلبات الدمج والمراجعة

يستوفي طلب الدمج أسئلة القالب، ويعتمد المراجع القاعدة نفسها دون الاكتفاء بصياغة الشرح.

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

يفحصه: قالب طلب الدمج الذي يطلب رابط المسألة.

4.2 اعرض كل تغيير يمس النص القرآني على مراجع ثانٍ يقرأ الفرق بقيم codepoint ويقارن الآية المعدلة كاملة بالمصدر المنشور.

standards/            @quran-ws/terminology
data/text/            @quran-ws/text-review

يحدد CODEOWNERS المراجع الثاني للمسارات التي تحتوي على المعيار والنص، فتُطلب مراجعته تلقائيًا، وأسماء المجموعات هنا مؤقتة للتوضيح.

يفحصه: يشمل CODEOWNERS جميع مجلدات بيانات النص، ويرفض روبوت الدمج أي طلب دون الموافقة الثانية.

4.3 تحقق عند مراجعة المخرجات المولّدة من تعديل المصدر وإعادة CI توليدها، بدل مراجعة المخرجات نفسها بالنظر.

يفحصه: مقارنة التغييرات في CI.

5. الإصدارات والوسوم

لكل إصدار وسم ثابت لا يتغير.

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

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

5.2 رقّم إصدارات كل dataset يحتوي على نص قرآني وفق قواعد إصدارات البيانات، وإصدارات الكود وفق الترقيم الدلالي المعتاد.

git tag:        hafs-uthmani-v3.0.0
dataset.json:   { "version": "3.0.0", "riwayah": "hafs_an_asim", … }

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

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

اتبع نموذج update_check.py في المهارة وأضف أداة مماثلة إلى كل ما تنشره.

يفحصه: اختبار يتأكد من وجود version وcommit المستخدم في البناء مع كل ما يُنشر.

6. الاعتماد علينا

يحدد المشروع الذي يعتمد علينا إصدارًا موسومًا للاستخدام بدل main.

6.1 نضمن ثبات بايتات النص والمعرفات وحدود الآيات وبصمة المصدر لكل dataset منشور وأسماء code لكل مدخل حالته adopted ما دامت قيمة MAJOR ثابتة، ولا نضمن ثبات صياغة الشرح أو أسماء display أو أي شيء حالته draft أو proposed.

يفحصه: حقل status في كل صفحة ومدخل.

6.2 سجّل الإصدار الذي يعتمد عليه مشروعك في ملف manifest الخاص به بجانب هوية dataset، حتى يتمكن مستخدمو مشروعك من تتبع تسلسل الاعتماد.

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

6.3 اذكر في README الإصدارات المدعومة التي يمكن تثبيت الاعتماد عليها، وحدد الحالي منها وما حل غيره محله ومدة بقاء الإصدارات السابقة متاحة.

يفحصه: قاعدة للمراجعة.

7. المساهمة من خارج الفريق

نطبق على المساهمات الخارجية قواعد القبول نفسها التي نطبقها على عملنا.

7.1 وثّق كل معلومة علمية، مثل تعريف أو عدد أو نسبة إلى قراءة أو نظام عد الآي، بمصدر مدرج في sources.yml، وأبقِ ما لا مصدر له في حالة draft.

يفحصه: يرفض tools/validate.py الحالة adopted لأي مدخل لا مصدر له.

7.2 تذكر المساهمة التي تضيف نصًا قرآنيًا أو تغيره الطبعة المنشورة التي أُخذ منها، وتمر بالمراجعة الثانية.

يفحصه: قاعدة CODEOWNERS المذكورة أعلاه.

7.3 انشر ميثاق السلوك في CODE_OF_CONDUCT.md، وعلى المسؤول عن المستودع الرد على المسائل بقرار أو سؤال دون تركها بلا رد.

يفحصه: قاعدة للمراجعة.

7.4 سجّل مع كل قول علمي مرتبة أقوى أدلته وحالة توثيقه، واعرضهما كما سُجّلتا دون حساب متوسط يجمعهما في درجة واحدة.

tier:   primary | commentary | secondary | modern-reference | api-check
state:  uncited | secondary_only | primary_cited | primary_cited_and_reviewed | disputed | unresolved

لا يكفي api-check وحده لحسم قول، ولا يُستنتج موقف في مسألة خلافية من مجموع درجات.

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

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