Skip to content
Apothem
المرجع

ترويسة الكِتابة (Authorship Header) — سطر رخصة SPDX لكل ملف

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

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

1. سطر الترويسة الكنسي

يجب أن يبدأ كل ملف منطبق في المنظومة بسطر مُعرِّف رخصة SPDX كنسي واحد، بصيغة تعليق عائلة نوع ملفه. هذا السطر هو علامة الرخصة القابلة للقراءة آليًّا للملف؛ وجوده غير قابل للتفاوض في الملفات غير المُعفاة، ومحتواه محكوم بمصدر حقيقة واحد لا يُرتجَل لكل ملف. يعيش صكُّ حقوق النشر الكامل مرّةً واحدة في ملف 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 (§7) تجاه هذه التثبيتة الدقيقة بايتيًّا. أي انحراف بين سطر ترويسة ملف وهذه التثبيتة (تحت استبدال الصيغة وفق §2) هو إخفاق CI.

2. المتغايرات لكل نوع ملف (دقيقة بايتيًّا)

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

عائلة نوع الملفصيغة التعليقعرض المتغاير
عائلة # — .sh، .bash، .zsh، .py، .rb، .pl، .ps1، .yml، .yaml، .toml، .cff، .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، .c، .cc، .cpp، .h، .hpp، .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 — .css، .scss، .less، .sql (/* */)/* ... *//* SPDX-License-Identifier: MIT */
عائلة ; — .ini، .cfg، بعض .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 القيمة not-applicable لهذه:

  • LICENSE — هو نفسه الصك القانوني؛ يحمل سطر حقوق النشر الموثوق الذي يؤكّد مُتحقِّق license-author-consistency وجوده.
  • أصول *.svg — تعليقات XML هشّة لعلامات التعليق السطري، لذا تُحمَل مصدريّة SVG عبر README الأصل والمخرجات النقطية المُولَّدة.
  • CHANGELOG.md — مستند ملاحظات إصدار مقيّد الصيغة؛ يظهر سطر SPDX كتعليق HTML واحد فوق ترويسة الـ changelog، لا منسوجًا في الصيغة.
  • ملفات JSON (.json) — لا صيغة تعليق لـ JSON. حيث تُطلَب النسبة لإعداد JSON، ضع ملفًّا شقيقًا <file>.NOTICE.md.
  • ملفات القفل — package-lock.json، yarn.lock، pnpm-lock.yaml، Cargo.lock، Pipfile.lock، poetry.lock، go.sum، إلخ (مُدارة آليًّا).
  • الملفات المُولَّدة — أي شيء بعلامة # Generated by ... أو // Generated by ...، أو أي شيء مطابق لـ .gitattributes linguist-generated=true.
  • محتوى طرف ثالث مُورَّد — ملفات تحت vendor/، third_party/، node_modules/. تحمل هذه رخصة/إشعار منبعها الخاص؛ وحقن علامتنا فوق نسبة المنبع انتهاك للرخصة.
  • ملفات .audit/ — زائلات مُتجاهَلة في git؛ خارج نطاق الشجرة المنشورة.
  • ملفات الخطط (<project-root>/.apothem/plans/**، والقديم <project-root>/.plans/**) — زائلات مُتجاهَلة في git؛ المصدريّة هي فرونت-ماتر الخطة (انظر plans-discipline.md §3).
  • العلامات الفارغة — .keep، .gitkeep، إلخ (صفرية البايت دلاليًّا).
  • الملفات الثنائية من أي نوع.

قائمة الاستثناءات نفسها مُرمَّزة كقائمة 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 هو أول محتوى للملف، باستثناء واحد لا غير: سطر الشيبانغ (#!/usr/bin/env bash، #!/usr/bin/env python3، إلخ) الذي يظل دائمًا في السطر 1؛ ويبدأ سطر SPDX في السطر 2.
  • لملفات Markdown / MDX ذات فرونت-ماتر YAML، يجلس تعليق SPDX في القمّة تمامًا، ثم يتبعه فرونت-ماتر YAML، ثم H1 والمتن. يبدأ المُخرَج المعروض بتعليق غير مرئي، ثم تُحلَّل فرونت-ماتر بالأدوات، ثم ينساب المحتوى المرئي.
  • يفصل سطر فارغ واحد فقط سطرَ SPDX عن المحتوى التالي (--- فرونت-ماتر، خَلَف الشيبانغ، H1، إلخ).

6. سياسة رؤية الترويسة

لملفات Markdown تحديدًا، سطر SPDX غير مرئي افتراضيًّا — ملفوف في <!-- ... --> (أو {/* */} لِـ MDX)، مرئي في المصدر فقط. هذه هي السياسة الصحيحة لِـ README وCONTRIBUTING وCLAUDE.md وملفات تعليمات harness المدعوم وSKILL.md الخاص بالمهارة ومتون الأوامر وأنماط المُخرَج وصفحات الوثائق. يُسمَح بعرض مرئي (سطر SPDX كنص عادي أو كتلة مُسوَّرة أعلى المُخرَج) لمستندات المرجع المستقلّة التي تستفيد من مصدريّة قابلة للقراءة فورًا؛ تُضبَط السياسة لكل صنف ملف في src/apothem/schemas/header-visibility.yaml (الافتراضي invisible)، مع علامة تجاوز بنطاق الملف <!-- header-visibility: visible --> مسموح بها مباشرةً بعد السطر.

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

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

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

يُستدعى الحاقن من أهداف Make التي تُهيكِل ملفات جديدة بسطر SPDX مُدرَجًا مسبقًا (make headers-fix وهياكل make new-*) ومن خطّاف pre-commit في نمط --fix.

8. المُتحقِّق — file-header (CI)

يعيش في src/apothem/conformity/file_header_grep.py. لكل ملف في شجرة العمل، يبحث المُتحقِّق عن انطباقه (وفق §3) ويؤكّد، إذا كان منطبقًا، أن سطر SPDX الكنسي حاضر في رأس الملف — أمام كل محتوى آخر، والمحتوى السابق الوحيد المسموح به هو الشيبانغ (§5).

مدعوم بالتثبيتة الدقيقة بايتيًّا في src/apothem/schemas/authorship-header.txt. يبلّغ عن diff لكل ملف ونسبة تغطية مجمَّعة في ملخّص CI. يُخفِق البناء عند أي انحراف.

9. آليات الفرض الذاتي

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

  1. src/apothem/schemas/authorship-header.txt — التثبيتة الكنسية الدقيقة بايتيًّا؛ مصدر حقيقة واحد.
  2. scripts/inject-header.{sh,py} — الحاقن الميكانيكي (§7).
  3. مُتحقِّق CI file-header (§8) — يُخفِق البناء عند أي انحراف.
  4. خطّاف pre-commit — يشغّل المُتحقِّق بـ --fix على الملفات المُجهَّزة، موصولًا بالحاقن.
  5. كتلة السلوك الإلزامي في CLAUDE.md — تُوجِّه المساعد لحقن سطر SPDX الكنسي عند إنشاء أي ملف منطبق.
  6. ملف تعليمات harness المدعوم في مسار .github/ الكنسي — يُوجِّه بيئة تشغيل harness لفعل المثل عند توليد الملف.
  7. خطّافات PreToolUse في src/apothem/hooks/messages/pretooluse-{write,edit}-header-guard.md — تعترض استدعاءات أداة Write/Edit على المسارات المنطبقة كي يُحقَن سطر SPDX عند إنشاء الملف بدلًا من اكتشافه إخفاقَ CI لاحقًا.
  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-header (CI)9. آليات الفرض الذاتيانظر أيضًا