Skip to content
Apothem
المرجع

ترويسة التأليف — سطر رخصة SPDX لكل ملف

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

مرجع معياري معتمد للمساهمين اللاحقين. يعكس هذا المستند أقسام التأليف وترويسة الملف في مواصفة المشروع (المواصفة §0.5 + §4.6)؛ وهو المرجع المستقلّ الذي يُشحَن مع المستودع المنشور. والأساس المعماري مُسجَّل في ADR-0002.

1. سطر الترويسة المرجعي

يجب أن يبدأ كل ملف منطبق في المنظومة بسطر واحد مرجعي لمُعرِّف رخصة SPDX، بصيغة التعليق الخاصة بعائلة نوع ملفه؛ ولا يجوز أن يسبقه إلا سطر shebang أو، في ملفات Markdown، البيانات الأمامية YAML (§5). هذا السطر هو علامة الرخصة المقروءة آليًا للملف؛ ووجوده غير قابل للتفاوض في الملفات غير المُعفاة، ويحكم محتواه مصدر حقيقة واحد، فلا يُرتجَل لكل ملف. ويعيش صكّ حقوق النشر الكامل مرة واحدة في ملف LICENSE في جذر المستودع — ولا يُكرَّر في كل ملف مصدري.

1.1 المحتوى المعلوماتي (ثابت)

المحتوى المرجعي هو سطر واحد بالضبط:

  1. SPDX-License-Identifier: MIT — علامة الرخصة المقروءة آليًا وفق مواصفة REUSE التي تصونها FSFE؛ تُحلِّلها بلا لبس سلسلةُ أدوات SPDX (reuse lint، scancode) وأدوات نواة Linux وماسحات الرخص اللاحقة. لا تحمل إطارًا بصريًا ولا أسطر حقوق نشر أو موقع إلكتروني أو بريد إلكتروني أو GitHub لكل ملف — فمنشأ كل ملف هو سطر SPDX الواحد بحكم التصميم (انظر §4).

1.2 الصيغة المرجعية (عائلة تعليق #)

النص المرجعي — المكتوب هنا بصيغة تعليق # — مصدر حقيقته في src/apothem/schemas/authorship-header.txt:

# SPDX-License-Identifier: MIT

هذا النص هو المصدر المعتمد الوحيد. ويتحقّق المدقّق file-header (§8) من الملفات مقابل هذه التجهيزة المطابقة بالبايت. وأي انحراف بين سطر ترويسة الملف وهذه التجهيزة (مع استبدال صيغة التعليق وفق §2) يُبلَّغ عنه بوصفه ملاحظة. والمدقّق حاجِب: ففي وضع --strict، كما يشغّله CI وخطّاف pre-commit، تُفشل الملاحظة التشغيل (§8).

2. الأشكال الخاصة بكل نوع ملف (مطابقة بالبايت)

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

عائلة نوع الملفصيغة التعليقالشكل المعروض
عائلة # — .sh، .bash، .zsh، .py، .rb، .pl، .ps1، .yml، .yaml، .toml، .cff، .cfg، .gitignore، .gitattributes، .editorconfig، .shellcheckrc، .env.example، Makefile، Dockerfile، Procfile، CODEOWNERS، PKGBUILD، ونقاط دخول الصدفة بلا امتداد مثل scripts/apothemتعليق سطري ## SPDX-License-Identifier: MIT
عائلة // — .js، .jsx، .mjs، .cjs، .ts، .tsx، .go، .rs، .java، .kt، .swift، .cs، .scala، .dart، .jsoncتعليق سطري //// SPDX-License-Identifier: MIT
عائلة التعليق الكتلي — .html، .htm، .md، .markdown، .xml، .vue (منطقة القالب)، .php (منطقة القالب)<!-- ... --><!-- SPDX-License-Identifier: MIT -->
MDX (.mdx){/* ... */} (تعليق تعبير JSX){/* SPDX-License-Identifier: MIT */}
عائلة كتلة C — .c، .cc، .cpp، .h، .hpp، .css، .scss، .less (/* */)/* ... *//* SPDX-License-Identifier: MIT */
عائلة ; — .ini، بعض .lisp/.scmتعليق سطري ;; SPDX-License-Identifier: MIT
عائلة -- — .sql، .lua، .hs، .elm، .adaتعليق سطري ---- SPDX-License-Identifier: MIT
ملف القفل / مُولَّد / JSONلا شيء / غير منطبقمُعفى. انظر §3 قائمة الاستثناءات.

شكل Markdown (العرض المرجعي):

<!-- SPDX-License-Identifier: MIT -->

غلاف تعليق HTML (أو {/* */} في MDX) لا يظهر في العرض، فيبقى السطح المعروض نظيفًا بينما تبقى علامة الرخصة داخل المصدر مقروءة آليًا عبر أنواع الملفات.

3. قائمة الاستثناءات (مُعفاة بحكم الفئة)

الفئات التالية مُعفاة من سطر ترويسة SPDX. ويمرّر المدقّق file-header هذه الملفات دون فحصها. تطابق الفئات أدناه قائمة الأنماط الواردة في header-exceptions.txt:

  • ملفات الرخصة والإصدار — LICENSE، وLICENSE.md، وLICENSE.txt، وNOTICE، وVERSION. يحمل LICENSE سطر حقوق النشر المعتمَد، ويؤكّد المدقّق license-author-consistency وجوده.
  • التثبيتة الكانونية — schemas/authorship-header.txt. فحقن الترويسة في التثبيتة سيُنتج ترويسةً لترويسة.
  • أصول *.svg — تعليقات XML هشّة بالنسبة إلى علامات التعليق السطري، لذا يُحمَل منشأ SVG في README الأصل وفي المخرجات النقطية المُولَّدة.
  • ملفات JSON (.json) — لا صيغة تعليق في JSON. وحيث يُشترط الإسناد لإعداد JSON، ضع ملفًا شقيقًا <file>.NOTICE.md.
  • ملفات القفل — كل ملف *.lock، وpackage-lock.json، وyarn.lock، وpnpm-lock.yaml، وgo.sum. هذه الملفات تُدار آليًّا.
  • الملفات المُولَّدة والمُصغَّرة — أي ملف تحت دليل generated/، والحزم المُصغَّرة (*.min.js، *.min.css).
  • محتوى الطرف الثالث المُضمَّن — ملفات تحت _vendor/، وvendor/، وthird_party/، وnode_modules/. تحمل هذه الملفات رخصة المنبع وإشعاره الخاصّين. وحقن علامتنا فوق إسناد المنبع يُعدّ انتهاكًا للرخصة.
  • حالة التدقيق والتخطيط وإطار العمل — كل ما تحت .audit/ و.apothem/، وهو يحوي الخطط والذاكرة وبيانات التعلّم والسياقات. وكذلك projects/ وmemory/ في جذر شجرة العمل، والتي يملكها إطار العمل. هذه الشجرات مُتجاهَلة بواسطة gitignore أو يملكها المُشغِّل، وهي خارج نطاق الشجرة المنشورة. وتُتتبَّع أصول ملفات الخطط عبر بياناتها الأمامية (راجع plans-discipline.md §3).
  • تثبيتات بيانات الاختبار — ملفات .yaml و.yml و.txt و.json تحت tests/fixtures/. وملفات شيفرة الاختبار في تلك الشجرة ما زالت تحمل الترويسة.
  • مُدخلات اختبار الدخان للحاقن — الملفات تحت tests/conformity-scenarios/fixtures/F-13-injector-smoke/. وتبقى بلا ترويسة لأن اختبار الحاقن يتحقّق من أن الحاقن يضيف الترويسة إليها.
  • ملفات التغليف والعلامات الفارغة — .SRCINFO، الذي يقرؤه مُحلِّل التغليف بصرامة، والعلامات صفرية البايت .keep و.gitkeep وpy.typed.
  • الملفات الثنائية — لواحق الصور والخطوط والأرشيفات والوسائط والكائنات المُترجَمة المدرجة في التثبيتة. واللاحقة التي لا يطابقها جدول المتغيّرات لدى المدقّق تُعفى افتراضيًّا.

قائمة الاستثناءات نفسها مُرمَّزة بوصفها قائمة regex/glob في src/apothem/schemas/header-exceptions.txt وهي مُدخَل فحص الانطباق في المدقّق. وتتطلّب التعديلات استيضاحًا مُهيكَلًا وADR جديدًا.

4. التفاعل مع الرخصة

يُعلِن سطر SPDX رخصة المشروع بصورة مقروءة آليًا؛ ويُعلِنها ملف LICENSE بصورة معتمدة:

  • SPDX-License-Identifier: MIT — علامة الرخصة المقروءة آليًا وفق مواصفة REUSE ومعيار SPDX. تُحلِّل ماسحات الرخص الآلية هذا السطر مباشرةً؛ وصيغة تعبير SPDX متوافقة مع reuse lint وscancode-toolkit وFOSSology وأدوات رخص نواة Linux.
  • LICENSE في جذر المستودع — الصكّ القانوني المعتمد الحامل لشروط MIT الكاملة ولصاحب حقوق النشر. وهو الموضع الوحيد لبيان حقوق النشر؛ وتُحيل إليه ترويسات الملفات ضمنًا عبر مُعرِّف SPDX المشترك بدلًا من إعادة ذكر حقوق النشر في كل ملف.

الصيغة أحادية السطر. منشأ كل ملف هو سطر SPDX الواحد؛ ويعيش صكّ حقوق النشر مرة واحدة في LICENSE الجذر. صناديق اللافتة المؤطَّرة متعددة الأسطر (أسطر حقوق النشر والموقع الإلكتروني والبريد الإلكتروني والاتصال ملفوفة في إطار مُسطَّر) يرفضها المدقّق: فهي تُكرِّر بيانات الاتصال وحقوق النشر الوصفية في كل ملف دون أن تضيف شيئًا لا توفّره علامة الرخصة المقروءة آليًا أصلًا لأدوات REUSE/SPDX/SBOM. وتحمل التجهيزة المطابقة بالبايت في src/apothem/schemas/authorship-header.txt الصيغة أحادية السطر؛ ويعمل المدقّق على هذه التجهيزة.

الإحالات المتبادلة. ملف LICENSE (MIT) — الصكّ القانوني هو الحاكم عند التعارض. ويوثّق ADR-0006 مسوّغ المصادقة على تضييق اللافتة.

5. موضع الإدراج

  • سطر SPDX هو أول محتوى في الملف، مع استثناءين. سطر shebang (#!/usr/bin/env bash، #!/usr/bin/env python3، وغيرهما) يظل دائمًا السطر 1، ويبدأ سطر SPDX في السطر 2. وفي ملفات Markdown / MDX ذات البيانات الأمامية YAML تأتي البيانات الأمامية أولًا (البند التالي).
  • في ملفات Markdown / MDX ذات البيانات الأمامية YAML، تبقى البيانات الأمامية عند البايت 0 كي تتمكّن الأدوات من تحليلها، ويلي تعليقُ SPDX الفاصلَ --- الختامي، ثم المتن، الذي يبدأ بعنوان H1 في الملفات التي تحمل واحدًا. ويضع scripts/inject-header.py التعليق على هذا النحو.
  • يفصل سطر فارغ واحد سطرَ SPDX عن المحتوى التالي (H1، والمتن، وغيرهما).

6. سياسة ظهور الترويسة

في ملفات Markdown وMDX، يُكتب سطر SPDX دائمًا داخل غلاف التعليق الخاص به (<!-- ... --> أو {/* */}). وهو مرئي في المصدر فقط، ولا يظهر في الصفحة المعروضة. وليس للحاقن عرض مرئي، ولا تجاوز لكل ملف على حدة. ولا تقرأ أي أداة في المستودع التجهيزةَ src/apothem/schemas/header-visibility.yaml.

7. الحاقن — scripts/inject-header.{sh,py}

واجهة سطر أوامر حتمية:

  • تأخذ مسارًا واحدًا أو أكثر من مسارات الملفات (أو أنماط glob).
  • تحدّد الانطباق عبر قائمة الاستثناءات (§3).
  • تكشف حالة الترويسة الموجودة (مرجعية / مشوَّهة / غائبة)، وتنزع أي كتلة لافتة غير مرجعية تجدها، حتى تكون عمليات إعادة التشغيل عديمة الأثر.
  • تُنتِج شكل SPDX الصحيح لكل نوع ملف (§2).
  • تُدرِج في الموضع الصحيح (§5)، مع احترام سطور shebang والبيانات الأمامية.
  • تُضيف السطر الفارغ الناقص إلى سطر SPDX الواقع عند موضع الإدراج دونه، بدلًا من إدراج نسخة ثانية فوقه.
  • تعمل بثلاثة أنماط: fix-in-place (تكتب)، وemit-patch (تطبع diff موحَّدًا)، وcheck (تخرج بقيمة غير صفرية عند أي انحراف؛ ولا تُشغّلها أي مهمة CI على الشجرة المتتبَّعة).
  • عديمة الأثر عند التكرار: تشغيلها مرتين لا يُحدث أي تغيير.

يُستدعى الحاقن من الهدف make headers-fix، الذي يُشغِّل scripts/inject-header.py --mode fix-in-place.

8. المدقّق — file-header

يوجد في src/apothem/conformity/file_header_grep.py. وبالنسبة إلى كل ملف في شجرة العمل، يستعلم المدقّق عن انطباقه (وفق §3)، فإن كان منطبقًا تحقّق من وجود سطر SPDX المرجعي في موضع الإدراج. وبالنسبة إلى معظم الفئات يكون هذا الموضع أعلى الملف، بعد سطر shebang اختياري. أما ملفات Markdown وMDX فتُتخطّى فيها كتلة البيانات الأمامية YAML أولًا، فقد يأتي السطر المرجعي بعد السياج الختامي، كما يشترط §5. وتُحَلّ ملفات MDX إلى الصيغة {/* */} (§2) وتُفحَص وفقها. ويضع المدقّق والحاقن الكتلة المرجعية في الفهرس نفسه.

يستند هذا إلى التجهيزة المطابقة بالبايت في src/apothem/schemas/authorship-header.txt. يُبلِّغ تشغيل مجموعة الملفات عن عدد الملاحظات وعن عيّنة من الملفات المُعلَّمة لهذا المطابِق. ولا يطبع فرقًا لكل ملف ولا نسبة تغطية مئوية. والمطابِق حاجِب: ففي وضع --strict، الذي يستخدمه CI وخطّاف pre-commit، تُفشل الملاحظة التشغيل. ومن دون --strict، تُبلِّغ البوابة عن الملاحظة وتخرج بالرمز 0.

9. آليات الإنفاذ الذاتي

يجب أن ينجو هذا الانضباط من كل جلسة مستقبلية ومن كل مساهم مستقبلي. أسطح الإنفاذ الإلزامية:

  1. src/apothem/schemas/authorship-header.txt — التجهيزة المرجعية المطابقة بالبايت؛ مصدر حقيقة واحد.
  2. scripts/inject-header.{sh,py} — الحاقن الميكانيكي (§7).
  3. مدقّق file-header (§8) — يُبلِّغ عن الانحراف بوصفه ملاحظة حاجبة تُفشل تشغيل --strict.
  4. خطّاف pre-commit — يُشغِّل الخطّاف conformity-corpus-perwrite كل مطابِق يعمل عند كل كتابة، بما فيه مدقّق file-header (§8)، على الشجرة المتتبَّعة مع --strict. ومطابِق file-header حاجِب، فتمنع ملاحظته الإيداع. والخطّاف يفحص فقط؛ فليس له وضع إصلاح، ولا يُشغِّل الحاقن أبدًا (§7)، إذ يعمل الحاقن عبر make headers-fix.
  5. كتلة السلوك الإلزامي في CLAUDE.md — توجّه المساعِد إلى حقن سطر SPDX المرجعي كلما أنشأ ملفًا منطبقًا.
  6. ملف تعليمات GitHub Copilot في .github/copilot-instructions.md — يوجّه Copilot إلى فعل الأمر نفسه عند توليد الملفات.
  7. خطّافات PreToolUse في src/apothem/hooks/messages/pretooluse-{write,edit}-header-guard.md — تعترض استدعاءات أداتَي Write/Edit على المسارات المنطبقة، فيُحقَن سطر SPDX عند إنشاء الملف، بدلًا من أن يُكتشَف غيابه لاحقًا بوصفه ملاحظة من المدقّق. ويستخدم مُدقِّق الحارس، src/apothem/hooks/lib/header_check.py، المكتبة القياسية وحدها، ويقرأ التجهيزة وقائمة الاستثناءات من الدليل schemas/ المجاور لـhooks/، لذا يعمل أيضًا تحت إضافة Claude Code، حيث لا تكون الحزمة apothem قابلة للاستيراد. ويطبّق جداول أشكال الحاقن وقواعد مواضع الإدراج على الملفات داخل المشروع، وفقط في مشروع git يحمل تجهيزة الترويسة (src/apothem/schemas/authorship-header.txt)، لأن سطر SPDX اصطلاح هذا المستودع وليس افتراضيًا لكل مشروع تفتحه الإضافة.
  8. خانة اختيار في قالب PR — إقرار موجَّه إلى المساهِم بأن كل ملف جديد يحمل سطر SPDX المرجعي.
  9. هذا المستند (site/content/docs/reference/authorship-header.mdx) — الشرح المعياري المرجعي.

انظر أيضًا

اصطلاحات أُطُر العمل متعدّدة الأسطح

المرجع المعياري المعتمد لإعداد أُطُر العمل متعدّدة الأسطح واتّساقها عبر بيئات تشغيل الدردشة، والإكمال داخل بيئة التطوير، ومراجعة طلبات السحب.

بيان تثبيت الاعتماديات

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

On this page

1. سطر الترويسة المرجعي1.1 المحتوى المعلوماتي (ثابت)1.2 الصيغة المرجعية (عائلة تعليق #)2. الأشكال الخاصة بكل نوع ملف (مطابقة بالبايت)3. قائمة الاستثناءات (مُعفاة بحكم الفئة)4. التفاعل مع الرخصة5. موضع الإدراج6. سياسة ظهور الترويسة7. الحاقن — scripts/inject-header.{sh,py}8. المدقّق — file-header9. آليات الإنفاذ الذاتيانظر أيضًا