البداية
المفاهيم
في هذه الصفحة
الأعلام وأنواعها
ينتمي العلم إلى مشروع، وله:
- مفتاح (مثل
checkout-v2) ونوع:booleanأوstringأوnumberأوjson(أي قيمة JSON). المفتاح والنوع لا يتغيّران؛ - غرض: إصدار أو تجربة أو تشغيلي أو صلاحية؛
- عمر: مؤقت، أو دائم لمفاتيح الإيقاف الطارئ والإعدادات طويلة الأمد (يرفض أمر cleanup في أداة سطر الأوامر الأعلام الدائمة)؛
- الكشف للعميل: لا تُسلَّم إلى مفاتيح المتصفح (العميل) إلا الأعلام المكشوفة للعميل.
لا تُحذف الأعلام، بل تُؤرشف (ويمكن استعادتها). العلم المؤرشف ليس في الحزمة، فتعيد حِزم SDK قيمة الاحتياط التي مرّرها المستدعي.
لكل علم في كل بيئة إعداد: enabled، وقائمة مرتّبة من القواعد rules، وقيمة افتراضية default (مفعّل ولم تطابق قاعدة)، وقيمة إيقاف off (معطّل).
كيف يُقيَّم العلم
المحرك نفسه يعمل في حِزم SDK وعلى الحافة وفي أداة سطر الأوامر ولوحة التحكم، فيعطي الإعداد نفسه ومفتاح العلم نفسه والسياق نفسه النتيجة نفسها دائمًا. القواعد بيانات؛ ولا تُنفَّذ أي شيفرة للمستخدم أثناء التقييم.
- لم يُحمَّل إعداد، أو العلم غير موجود فيه ← قيمة الاحتياط لدى المستدعي، والسبب
flag_not_found. - العلم معطّل ← قيمة
offالخاصة به، والسببoff. - القواعد بالترتيب؛ أول قاعدة تتطابق شروطها تحسم النتيجة (السبب
rule_match). والقاعدة تقدّم قيمة ثابتة أو طرحًا تدريجيًا (نسبة مئوية تحصل علىvalueوالباقي علىotherwise). - لم تطابق أي قاعدة ← قيمة
defaultللعلم، والسببdefault. - أي أمر غير متوقع ← قيمة الاحتياط لدى المستدعي، والسبب
error. والتقييم لا يرمي استثناءً أبدًا.
تتطابق القاعدة عندما تتطابق all (كل) أو any (أي) من شروطها (والقاعدة بلا شروط تطابق كل سياق). ويقارن كل شرط خاصية واحدة من السياق:
| المعامل | يتطابق عندما |
|---|---|
eq | تتساوى القيمتان (الكائنات والمصفوفات تُقارن كـ JSON). الخاصية الغائبة لا تتطابق أبدًا. |
neq | الخاصية موجودة وغير مساوية. |
in / not_in | مساوية لأحد عناصر قائمة / موجودة ولا تساوي أيًّا منها. يجب أن تكون القيمة قائمة. |
contains / starts_with / ends_with | مقارنات نصية؛ ويجب أن يكون الطرفان نصّين. |
gt / gte / lt / lte | مقارنات رقمية. النصوص الرقمية تُحوَّل؛ وأي شيء آخر لا يتطابق أبدًا. |
exists / not_exists | الخاصية موجودة وليست null / غائبة أو null. |
segment / not_segment | السياق (ليس) ضمن الشريحة المسمّاة. |
البيئات
للمشروع عدة بيئات (المشاريع الجديدة: Development وStaging وProduction). ولكل بيئة مسودتها الخاصة لكل علم، ونسخها المنشورة الخاصة، ومفاتيحها الخاصة: يقرأ المفتاح بيئة واحدة بالضبط. ويضبط المديرون لكل بيئة:
- الحماية، واشتراط الموافقة مع عدد الموافقين المطلوبين من 1 إلى 5، واشتراط السيناريوهات. بيئات Production الجديدة محمية، وفي Team وScale تشترط أيضًا الموافقة والسيناريوهات (الموافقات الإلزامية وفحوص السيناريوهات غير متاحة في Explore)؛
- الحد اليومي للأحداث المأخوذة كعيّنات والمخزّنة (انظر الحدود).
ميزة ترقية الإعدادات (Promote configuration) في الإعدادات ← البيئات تنسخ إعدادات أعلام مختارة من مسودة بيئة إلى مسودة بيئة أخرى. وهي لا تنشر.
المسودة والنسخة المنشورة
تعديل العلم يغيّر مسودة البيئة. ولا يصل شيء إلى حِزم SDK حتى تنشر: يأخذ النشر لقطة من مسودة البيئة كاملة (كل الأعلام والشرائح) في نسخة مرقّمة ثابتة لها بصمة (checksum). ولا تستلم حِزم SDK إلا النسخ المنشورة.
- كل نشر يسمّي النسخة التي يتوقع أن يحلّ محلها. فإن تقدّمت البيئة في الأثناء يُرفض النشر (
DESTINATION_CHANGED) بدل الكتابة فوق نسخة شخص آخر. - لا يمكن نشر مسودة مطابقة للإعداد المنشور (
NO_CHANGES)؛ وتُرفض القيم التي لا تطابق نوع العلم (INVALID_VALUE). - للتراجع، استعد محتوى نسخة سابقة إلى المسودة وانشره كنسخة جديدة. لا يُعاد كتابة السجل أبدًا.
التغييرات والموافقات
التغيير يجمع الأعلام التي تنوي تعديلها في بيئة واحدة مع عنوان وسبب ومرجع اختياري في الشيفرة. ويمرّ بالحالات draft ← testing ← awaiting_approval ← approved ← published (أو closed).
- في البيئة التي تشترط الموافقة، لا يمكن النشر إلا عبر تغيير (وإلا
CHANGE_REQUIRED) بعدد الموافقات الصالحة المطلوب على الأقل (APPROVAL_REQUIRED). - يجب أن يكون الموافقون مديرين أو مالكين، ولا يستطيع كاتب التغيير الموافقة عليه (
SELF_APPROVAL). - ترتبط الموافقة ببصمة مسودة البيئة لحظة إعطائها. وأي تعديل لاحق على تلك المسودة يجعلها متقادمة؛ فلا تعود تُحتسب ويحتاج التغيير إلى موافقة جديدة. والرفض يعيد التغيير إلى
draft. - لا تستطيع مفاتيح API تجاوز المراجعة: مفتاح المدير لا يستطيع نشر بيئة تشترط الموافقة.
السيناريوهات
السيناريو فحص محفوظ: علم وسياق والقيمة التي تتوقعها، مثل «المستخدم المسجَّل في الولايات المتحدة يحصل على true». تعمل السيناريوهات على المسودة أو على النسخة المنشورة لبيئة، في لوحة التحكم أو في CI.
- النجاح يعني أن القيمة الفعلية تساوي المتوقعة مساواةً عميقة (ترتيب مفاتيح الكائن لا يهم، وترتيب المصفوفة يهم، ولا تحويل للأنواع). والسيناريو الذي يغيب علمه (
flag_not_found) أو يفشل تقييمه لا ينجح أبدًا، حتى لو كان يتوقعnull. - السيناريوهات الموسومة تضمين في مجموعة CI (Include in CI suite) تعمل في CI. وفي البيئة التي تشترط السيناريوهات، يجب أن ينجح كل سيناريو ضمن النطاق على المسودة الدقيقة التي تُنشر (البصمة نفسها)؛ وتعديل المسودة يتطلب تشغيلًا جديدًا. والنطاق هو سيناريوهات أعلام التغيير، أو كل سيناريوهات CI عند النشر دون تغيير.
الشرائح
الشريحة مجموعة شروط مسمّاة قابلة لإعادة الاستخدام (all أو any) تُعرَّف مرة واحدة لكل مشروع، مثل beta-testers أو internal-staff. وتشير إليها القواعد بالمعاملين segment / not_segment. ويمكن للشريحة أن تشير إلى شرائح أخرى حتى أربعة مستويات؛ والإشارة إلى شريحة مجهولة لا تتطابق أبدًا (ولا يتطابق not_segment لشريحة مجهولة أيضًا). والشرائح جزء من المسودة وتُنشر معها.
توزيع الطرح التدريجي
الطرح بالنسب المئوية حتمي: لا عشوائية ولا تخصيصات مخزّنة. الهوية نفسها تقع دائمًا في الشريحة الرقمية نفسها للبذرة نفسها، في كل SDK وعلى كل جهاز.
bucket = (murmur3_x86_32(utf8(nfc(seed + ":" + identity)), 0) mod 10000) / 100 // 0.00 … 99.99
inside = bucket < percentage- الدالة: MurmurHash3 x86 بطول 32 بت، ببذرة تجزئة 0، على بايتات UTF-8 للنص بعد تطبيع NFC. تُستخدم للتوزيع فقط، لا للأمان أبدًا.
- الهوية: خاصية السياق التي يحدّدها
bucketByفي القاعدة، وافتراضيًاkey. والسياق الذي يفتقدها (غائبة أوnullأو فارغة) يُعامل على أنه خارج التوزيع ويحصل علىotherwise. - البذرة: قيمة
seedفي القاعدة، وافتراضيًا مفتاح العلم، فتكون توزيعات الأعلام المختلفة مستقلة. أعطِ علمين البذرة نفسها لتخصيص المستخدمين أنفسهم لكليهما. - للنسب منزلتان عشريتان (0–100). رفع النسبة يُبقي كل من كان داخلها؛ وخفضها يُخرج الشرائح الأعلى أولًا.
تتضمن نتيجة التقييم bucket وinRollout؛ ويشرح الأثر (trace) القرار.
الحزم الموقّعة
توقّع NanoFlags كل نسخة منشورة بخوارزمية Ed25519 قبل توزيعها. وتستلم مفاتيح المتصفح عرض العميل موقّعًا بشكل منفصل لا يحتوي إلا الأعلام المكشوفة للعميل. وتقدّم الحافة البايتات الموقّعة دون تعديل، فيستطيع الـ SDK (أو شيفرتك أنت) التحقق من أن الحزمة هي بالضبط ما نُشر لتلك البيئة وتلك النسخة. وبعد النشر مباشرة قد تقدّم الحافة لفترة وجيزة حزمة غير موقّعة (X-NanoFlags-Signed: false) إلى أن يلحق التوقيع.
التفاصيل: صيغة التوقيع والتحقق منه، وخيار verify في الـ SDK.
المُلاحَظ والمجهول
تُبقي NanoFlags أربعة أنواع من الحالة متمايزة بوضوح، ولا تصف أي إصدار بأنه «آمن» أبدًا:
| الحالة | المعنى | المصدر |
|---|---|---|
| المسودة | ما تعدّله الآن. لا يُسلَّم إلى حِزم SDK. | مسودة البيئة |
| المنشورة | النسخة التي تقدّمها الحافة للبيئة. | مؤشّر النسخة المنشورة للبيئة |
| المُبلَّغ عنها / المُلاحَظة | عملية تستخدم مفتاحًا لهذه البيئة قالت إنها حمّلت النسخة N، أو استُلم تقييم مأخوذ كعيّنة. | بلاغات الخدمات من حِزم SDK والأحداث المأخوذة كعيّنات |
| المجهولة | لا يوجد بلاغ. قد يكون القياس معطّلًا أو محجوبًا أو مستبعدًا من العيّنة أو مفقودًا. | غياب الإشارات: لا يثبت شيئًا |