مسارات الـ Deprecation

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

مسار الـ deprecation

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

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

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

type ButtonProps = {
  /** @deprecated Use `variant`. Removed in 5.0.0. */
  kind?: 'primary' | 'secondary' | 'danger';
  variant?: 'primary' | 'secondary' | 'danger';
  // …rest of the props
};

const warned = new Set<string>();
function warnOnce(key: string, message: string) {
  if (process.env.NODE_ENV === 'production' || warned.has(key)) return;
  warned.add(key);
  console.warn(`[Northwind UI] ${message}`);
}

export function Button({ kind, variant, ...rest }: ButtonProps) {
  if (kind) warnOnce('button-kind', 'Button `kind` is deprecated; use `variant`. Removed in 5.0.0.');
  const resolvedVariant = variant ?? kind ?? 'secondary';
  // …render as before, using resolvedVariant
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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