{"id":"l-ds-4-3","courseId":"design-systems","lang":"ar","kind":"lesson","summary":"احذف الـ tokens والـ props والمكوّنات دون كسر عمل الفرق، بإطلاق البديل أولًا، وإعلان الـ deprecation بوضوح في كل قناة، وأتمتة الانتقال بالـ codemods، والحذف في إصدار major فقط.","html":"

الحذف أصعب جزء في إدارة نظام التصميم. إضافة مكوّن تُسعد فريقًا واحدًا؛ أما حذف مكوّن فيجعل أربعين فريقًا يقومون بعمل لم يخطّطوا له. حذف أول إصدار major في Northwind أحد عشر prop وستة tokens دفعة واحدة، مع دليل انتقال نُشر في اليوم نفسه. وبعد تسعة أشهر كان فريقان ما زالا على الإصدار الـ major القديم، ينسخان الإصلاحات بصمت. عمليات الحذف نفسها كانت صحيحة. ما كان ينقص هو الطريق إليها.

\n

مسار الـ deprecation

\n
\n خط زمني من الإصدار 4.3 إلى 5.0 وما بعده: يُطلق 4.3 البديل ويعلن deprecation الـ API القديم؛ ومن 4.4 إلى 4.9 يجري الانتقال بالـ codemods وتتبّع الاستخدام؛ ويحذف 5.0 الـ API القديم؛ ويستمرّ 4.x في تلقّي الإصلاحات ستة أشهر.\n \n \n \n \n 4.3.0\n من 4.4 إلى 4.9\n 5.0.0\n \n البديل\n + deprecation\n \n Codemods،\n تتبّع الاستخدام\n \n الحذف\n \n إصلاحات لـ 4.x\n
الـ deprecation تمتدّ عبر إصدارات: بديل، فتحذير، فانتقال، فحذف
\n

كل عملية حذف في Northwind تتبع اليوم الخطوات نفسها، موزّعة على عدّة إصدارات.

\n

1. أطلق البديل أولًا. لا يمكنك أن تطلب من الفرق الانتقال إلى شيء غير موجود. أُطلق الـ prop المسمّى variant في Button ضمن الإصدار 4.3.0 كإضافة عادية، أي إصدار minor.

\n

2. أعلن الـ deprecation في كل القنوات دفعة واحدة. في الإصدار نفسه يُعلَّم kind كـ deprecated في كل مكان قد يصادفه فيه الناس:

\n
Button.tsx
type ButtonProps = {\n  /** @deprecated Use `variant`. Removed in 5.0.0. */\n  kind?: 'primary' | 'secondary' | 'danger';\n  variant?: 'primary' | 'secondary' | 'danger';\n  // …rest of the props\n};\n\nconst warned = new Set<string>();\nfunction warnOnce(key: string, message: string) {\n  if (process.env.NODE_ENV === 'production' || warned.has(key)) return;\n  warned.add(key);\n  console.warn(`[Northwind UI] ${message}`);\n}\n\nexport function Button({ kind, variant, ...rest }: ButtonProps) {\n  if (kind) warnOnce('button-kind', 'Button `kind` is deprecated; use `variant`. Removed in 5.0.0.');\n  const resolvedVariant = variant ?? kind ?? 'secondary';\n  // …render as before, using resolvedVariant\n}
\n

وسم JSDoc المسمّى @deprecated يجعل المحرّرات تشطب الـ prop أثناء الكتابة. والتحذير يظهر مرة واحدة في كل جلسة، وفي نسخ التطوير وحدها؛ إذ تستبدل الـ bundlers قيمة process.env.NODE_ENV بثابت، فيسقط الفحص والرسالة من كود الإنتاج. وتحصل صفحة التوثيق على شارة «Deprecated»، وتُعاد تسمية خاصية المكوّن في Figma حتى يلاحظ المصمّمون أيضًا.

\n

والـ tokens تُعامَل بالطريقة نفسها. يبقى الاسم القديم اسمًا مستعارًا للجديد، فلا ينكسر شيء، ويقول ملف الـ tokens ذلك صراحة:

\n
JSON
{\n  \"color\": {\n    \"text\": {\n      \"light\": {\n        \"$type\": \"color\",\n        \"$value\": \"{color.text.subtle}\",\n        \"$deprecated\": \"Use color.text.subtle. Removed in 5.0.0.\"\n      }\n    }\n  }\n}
\n

3. أتمت الانتقال. الـ codemod سكربت يعيد كتابة الكود المصدري. ولـ prop أُعيدت تسميته، يكفي transform من بضعة أسطر في jscodeshift:

\n
codemods/button-kind.js
export default function transformer(file, api) {\n  const j = api.jscodeshift;\n  return j(file.source)\n    .find(j.JSXOpeningElement, { name: { name: 'Button' } })\n    .find(j.JSXAttribute, { name: { name: 'kind' } })\n    .forEach((path) => {\n      path.node.name.name = 'variant';\n    })\n    .toSource();\n}
\n

تشغّله الفرق بالأمر npx jscodeshift --parser=tsx --extensions=tsx,ts -t codemods/button-kind.js src/ (فبدون هذين الخيارين لا يقرأ jscodeshift إلا ملفات .js بمحلّل Babel)، ثم تراجع الفروقات. ولأكبر خمسة مستخدمين، يفتح فريق النواة في Northwind pull requests الانتقال بنفسه. إعادة تسمية كانت ستكلّف كل فريق من الأربعين ظهيرة كاملة تصبح أربعين مراجعة سريعة.

\n

للـ codemods حدود، ويجب أن يسمّيها دليل الانتقال. الـ transform أعلاه يعيد تسمية kind="danger" وkind={isUrgent ? 'danger' : 'primary'} بشكل صحيح، لأن كليهما سمة مكتوبة على <Button>. لكنه لا يرى kind المختبئ داخل props تُمرَّر بالـ spread، مثل <Button {...actionProps} /> حيث بُني actionProps في ملف آخر، ولا Button أُعيد تصديره باسم آخر. لهذا يبقى تحذير وقت التشغيل مهمًّا حتى بعد تشغيل الـ codemod: فهو يلتقط الحالات التي لا تصل إليها إعادة الكتابة الثابتة. ودليل Northwind لكل عملية حذف له الأجزاء الأربعة نفسها: كود قبل وبعد، وأمر الـ codemod، والحالات المعروفة التي يفوّتها الـ codemod، ورابط إلى موعد الساعات المكتبية حيث يساعد فريق النواة في الباقي.

\n

4. قِس، ثم احذف. البحث في الكود عبر المستودعات يخبرك بعدد الاستخدامات المتبقّية؛ ويشرح القسم 5 كيف تجمع Northwind ذلك تلقائيًا. وحين يقارب الاستخدام الصفر، يدخل الحذف في الإصدار الـ major التالي، مجمّعًا مع عمليات الحذف المخطّطة الأخرى، فتواجه الفرق ترقية واحدة بدل عدّة ترقيات.

\n

5. ادعم الإصدار الـ major السابق. بعد إطلاق 5.0.0 يظلّ 4.x يتلقّى إصلاحات الأخطاء والأمان ستة أشهر. الفرق التي لا تستطيع الترقية فورًا لا تُترك عالقة، ولا تنسخ النظام.

\n\n

أعلنه كما تعلن تغييرًا في منتج

\n

الـ deprecation خبر لأربعين فريقًا، فعامله كإعلان منتج لا كسطر في الـ changelog. تنشر Northwind كل deprecation في قناة نظام التصميم بثلاث جمل: ما الذي يتغيّر، ولماذا يستحقّ الجهد، ومتى يحدث الحذف. ويرتبط المنشور بدليل الانتقال ويبقى مثبّتًا حتى يُطلَق الـ major. ويتلقّى مديرو الهندسة ملخّصًا شهريًا بعمليات الحذف القادمة التي تمسّ فرقهم، لأنهم هم مَن يجدولون العمل.

\n

كم من الوقت يكفي؟

\n

تُبقي Northwind الـ API المُهمَل لإصدارين minor على الأقل أو ثلاثة أشهر، أيّهما أطول، قبل الـ major الذي يحذفه، وتنشر جدول الإصدارات الـ major قبل ربع سنة. أرقامك قد تختلف؛ المهمّ أن تكون مكتوبة ويمكن توقّعها، حتى تخطّط الفرق لعمليات الانتقال ضمن خرائط طريقها بدل أن تكتشفها في عملية بناء فاشلة.

\n

في التمرين ترتّب مسار deprecation كاملًا. وبعدها تبني خط الإصدار الذي يلتقط التغييرات الكاسرة غير المقصودة قبل أن تُطلَق.

\n","toc":[{"id":"sec-1","text":"مسار الـ deprecation","level":2},{"id":"sec-2","text":"أعلنه كما تعلن تغييرًا في منتج","level":2},{"id":"sec-3","text":"كم من الوقت يكفي؟","level":2}],"takeaways":["لا تعلن deprecation لشيء قبل أن يُطلَق بديله؛ فالـ deprecation بلا بديل مجرّد شكوى.","علّم الـ deprecation في كل مكان ينظر إليه الناس - الأنواع، والـ tokens، وتحذيرات الـ console في بيئة التطوير وحدها، والتوثيق، وFigma - وسمِّ دائمًا البديل وإصدار الحذف.","الـ codemods تحوّل الانتقال من مهمّة لأربعين فريقًا إلى مراجعة لأربعين فريقًا.","لا تحذف العناصر المُهمَلة إلا في إصدار major، بعد أن تقيس أن الاستخدام قارب الصفر، واستمرّ في إصلاح الإصدار الـ major السابق لمدّة معلنة."],"further":[{"title":"jscodeshift (official repository)","url":"https://github.com/facebook/jscodeshift"},{"title":"Design token $deprecated property (DTCG specification source)","url":"https://github.com/design-tokens/community-group/blob/main/technical-reports/format/design-token.md"},{"title":"console: warn() static method (MDN)","url":"https://developer.mozilla.org/en-US/docs/Web/API/console/warn_static"}],"quiz":[{"q":"

يريد فريق النواة إعلان deprecation لـ ShipmentCard لأن Card المركّب أفضل. لكن الـ slot الخاص بـ Footer في Card لم يُطلَق بعد. ما الذي يجب أن يحدث أولًا؟

","options":[{"text":"إطلاق قطع Card، بما فيها الـ slot الخاص بـ Footer، حتى يكون لكل استخدام لـ ShipmentCard بديل يعمل.","why":"صحيح. لا تستطيع الفرق الانتقال إلا إلى شيء موجود ويغطّي حالة استخدامها."},{"text":"إعلان deprecation لـ ShipmentCard الآن حتى تتوقّف الفرق عن إضافة استخدامات جديدة.","why":"الفرق التي تحتاج بطاقة اليوم لا تملك بديلًا، فستتجاهل التحذير أو تبني بطاقتها الخاصة."},{"text":"حذف ShipmentCard في الـ major التالي وترك الفرق تتكيّف.","why":"حذفه بلا بديل يكسر 60 شاشة ولا يترك للفرق شيئًا تنتقل إليه."},{"text":"كتابة دليل الانتقال أولًا، ثم بناء Card لاحقًا.","why":"الدليل الذي يشير إلى مكوّن لم يُطلَق لا يمكن اتّباعه."}],"answer":0},{"q":"

أين يجب أن يظهر تحذير «Button kind is deprecated» وقت التشغيل؟

","options":[{"text":"في الإنتاج كتنبيه منبثق، حتى يلاحظه مديرو المنتجات.","why":"المستخدمون النهائيون سيرون رسالة عن كود لا يستطيعون تغييره."},{"text":"في لا مكان؛ الـ changelog يكفي.","why":"أغلب المهندسين لا يقرؤون كل changelog؛ أما التحذير في الـ console الخاص بهم أثناء التطوير فيصلهم حيث يعملون."},{"text":"في كل render، وفي كل بيئة.","why":"التسجيل في كل render يُغرق الـ console ويخفي الأخطاء الحقيقية؛ ومستخدمو الإنتاج لا يحتاجونه أيضًا."},{"text":"في الـ console أثناء التطوير، مرة واحدة في كل جلسة، مع ذكر البديل وإصدار الحذف.","why":"صحيح. يصل إلى المطوّرين وهم يعملون على الكود، دون ضجيج في الإنتاج."}],"answer":3},{"q":"

يُظهر البحث في الكود لدى Northwind 4 استخدامات متبقّية للـ prop المُهمَل kind عبر 40 مستودعًا، كلها في أداة إدارة قديمة لفريق واحد. إصدار 5.0 الأسبوع القادم. ما أفضل خطوة؟

","options":[{"text":"تأجيل 5.0 حتى تخلو المستودعات الأربعون من كل API مُهمَل.","why":"احتجاز إصدار major رهينةً لأداة قديمة واحدة يؤخّر تحسينات كل الفرق الأخرى."},{"text":"إطلاق 5.0، وفتح pull request لذلك الفريق يشغّل الـ codemod، مع إخبارهم أنهم يستطيعون البقاء على 4.x، الذي ما زال يتلقّى الإصلاحات، حتى يُدمج.","why":"صحيح. العمل المتبقّي صغير، وأنت تساعد مباشرة، وفترة الدعم تحميهم في الأثناء."},{"text":"إطلاق 5.0 دون إخبار الفريق.","why":"سينكسر التحديث التالي لاعتمادياتهم دون إنذار، وهذا يكلّف النظام ثقته."}],"answer":1}],"exercise":{"kind":"order","items":["replacement","deprecate","codemod","measure","remove","support"],"title":"خطّط لإعادة تسمية الـ token من أولها إلى آخرها","prompt":"

تستبدل Northwind الـ token المسمّى --nw-color-text-light بـ --nw-color-text-subtle. هناك نحو 300 استخدام عبر 40 مستودعًا، والإصدار الحالي 4.6.0. رتّب خطوات مسار الـ deprecation.

\n","hints":["لا يستطيع الناس الانتقال إلا إلى شيء موجود بالفعل.","الحذف تغيير كاسر، فينتظر إصدارًا major وبيانات الاستخدام.","خطوة واحدة تحدث بعد إطلاق الحذف."],"explanation":"

يُطلَق الـ token الجديد أولًا (إصدار minor)، فيكون هناك شيء ينتقل إليه الناس. وفي الإصدار نفسه يصبح الاسم القديم اسمًا مستعارًا معلَّمًا بـ $deprecated، ويسمّي التوثيق والـ changelog البديل وإصدار الحذف. وتنجز الـ codemods وpull requests الانتقال معظم العمل، ويُظهر تتبّع الاستخدام متى قاربت الاستخدامات المتبقّية الصفر، وعندها فقط يحذف الـ major التالي الاسم المستعار. واستمرار إصلاح 4.x لفترة معلنة بعد ذلك يحمي الفرق التي تحتاج وقتًا أطول.

\n","checkLabels":{},"itemText":{"replacement":"إطلاق --nw-color-text-subtle في 4.7.0","deprecate":"إبقاء --nw-color-text-light اسمًا مستعارًا معلَّمًا بـ $deprecated، وإعلان إصدار الحذف في التوثيق والـ changelog","codemod":"نشر codemod وفتح pull requests الانتقال لأكبر المستخدمين","measure":"تتبّع الاستخدامات المتبقّية عبر المستودعات حتى تقارب الصفر","remove":"حذف الـ token القديم في 5.0.0، مجمّعًا مع عمليات الحذف المخطّطة الأخرى","support":"الاستمرار في إطلاق إصلاحات الأخطاء على 4.x لستة أشهر"}},"words":646,"readMinutes":4}