المفاهيم

ست أفكار تشرح معظم المنتج.

المستند

نص Markdown له ترويسة (front matter) تعلن spec: "1". النثر يبقى نثرًا. وبضع صيغ تحمل معنى تحدّده المواصفة: السطر الذي يبدأ بكلمة مفتاحية، مثل MUST:، قاعدة يستلمها الوكيل موسومة بنوعها، والكتلة المحاطة بسياج يحمل نوعها، مثل :::example أو ::person{id=owner}، إرشاد أو إعلان أو بيانات يستلمها الوكيل تحت عنوان يسمّي نوعها. أما التعليقات، والترويسة («التفاصيل» في المحرّر)، والخاتمة (backmatter، وهي «الملاحظات» في المحرّر) فلا تُسلَّم إلى الوكيل أبدًا.

الإصدارات

النشر ينشئ إصدارًا ثابتًا لا يتغيّر، له بصمة (digest) محسوبة على البايتات كما كُتبت. الإصدارات لا تُعدَّل أبدًا. أما المسودة فمنفصلة ومشتركة: كل من يملك إذن التعديل يعمل على مسودة واحدة، وكل حفظ يتحقّق من أن المسودة لم تتغيّر في الأثناء (compare-and-swap)، فلا يستطيع شخصان أن يمحو أحدهما عمل الآخر دون أن ينتبها.

المراجع (refs)

المرجع (ref) اسم يشير إلى إصدار: @latest أو @stable أو أي اسم تنشئه. الوكلاء يتّبعون المراجع، فأنت تغيّر ما يشغّلونه بتحريك مرجع، لا بتعديل مستند. والتراجع هو تحريك المرجع إلى إصدار سابق، ولهذا يتمّ فورًا ويبقى السجل سليمًا.

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

الظهور والأذونات

الظهورمن يستطيع القراءة
privateمساحة العمل، وكل من مُنح إذنًا صريحًا
internalكل من في المؤسسة
publicكل من سجّل الدخول إلى السجل الذي نستضيفه؛ والسجل المستضاف ذاتيًّا قد يقبل أيضًا وكلاء مجهولين

وفوق ذلك، تمنح الأذونات شخصًا أو وكيلًا أو خدمة أو مجموعة واحدًا من هذه الحقوق: القراءة (read) أو التعديل (edit) أو النشر (publish) أو الإدارة (manage). الوكلاء والخدمات يقفون عند publish: الإنسان وحده يملك manage. والتعليمة الخاصة تظهر لمن لا يملك حق الوصول على أنها «غير موجودة» لا «ممنوعة»، فلا يتسرّب خبر وجودها.

مقترحات التغيير

كل من يستطيع قراءة تعليمة يستطيع أن يقترح تغييرًا: مستند كامل، وفرق (diff)، ومبرّر. يوافق عليه ويدمجه شخص يملك حق publish، ولا يوافق الكاتب على مقترحه هو أبدًا. بهذه الطريقة يساهم وكيل الذكاء الاصطناعي دون أن يستطيع النشر: يفتح مقترحًا، ويقرّر شخص.

المستهلكون

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