الـ Semver والـ Changelog لنظام التصميم

حين أطلقت Northwind الإصدار 3.4.0 من حزمة الواجهة، فشل البناء لدى أحد عشر فريقًا في الصباح التالي. ملاحظات الإصدار كانت تقول «تحسينات طفيفة». أحد تلك التحسينات أعاد تسمية الـ token المسمّى --nw-color-text-light، لأن الفريق قرّر (محقًّا) أن الاسم مضلِّل. كان تغييرًا جيدًا أُطلق برقم خاطئ، وكلّفنا من الثقة أكثر من أي خلل في تلك السنة. الترقيم هو الطريقة التي يقطع بها نظام التصميم وعوده لمستخدميه، والوعود المكسورة باهظة الثمن.

الـ semver في فقرة واحدة

الترقيم الدلالي للإصدارات (semantic versioning أو semver) يعطي كل إصدار رقمًا بالشكل MAJOR.MINOR.PATCH. الـ patch ‏(4.7.2 ← 4.7.3) يصلح أخطاء دون تغيير الـ API العام. والـ minor ‏(4.7.2 ← 4.8.0) يضيف وظائف بطريقة متوافقة مع ما سبق. والـ major ‏(4.7.2 ← 5.0.0) يحتوي تغييرات قد تكسر الاستخدام الحالي. ومديرو الحزم يعتمدون على هذا: الاعتمادية المكتوبة بالشكل ^4.7.2 تقبل أي 4.x.x من 4.7.2 فصاعدًا، لكنها لا تقبل 5.0.0 أبدًا. وقبل 1.0.0 يمكن أن يتغيّر أي شيء في أي وقت، لذا يجب أن يصل النظام الذي تعتمد عليه الفرق إلى 1.0 مبكرًا.

حدّد الـ API العام أولًا

الـ semver لا يعني شيئًا حتى تكتب ما هو «الـ API العام». في Northwind UI هو:

• كل مكوّن مُصدَّر والـ props الخاصة به، بما فيها قيمها الافتراضية؛
• كل اسم token في حزمة الـ tokens، والدور الذي يصفه كلٌّ منها؛
• نقاط ربط CSS الموثّقة: data-variant وdata-size والـ component tokens؛
• السلوك الموثّق، مثل «يعيد Dialog التركيز إلى العنصر الذي فتحه».

أي شيء خارج هذه القائمة، مثل أسماء الـ classes الداخلية، أو تداخل الـ DOM داخل المكوّن، أو الدوال المساعدة الخاصة، يمكن أن يتغيّر في أي إصدار. اكتب القائمة في التوثيق، وأخبر الفرق بوضوح أن الاعتماد على التفاصيل الداخلية غير الموثّقة على مسؤوليتها.

تصنيف التغييرات الحقيقية

بعد تحديد الـ API، تصبح معظم القرارات آلية:

صفّان يستحقّان تعليقًا. تغيير القيمة الافتراضية major لأن الكود الذي اعتمد عليها صار يُعرض بشكل مختلف دون تغيير سطر واحد. وتحسينات القيم minor لأن عقد الـ token هو دوره، لا لونه بالضبط؛ فإن صار «النص الهادئ» أغمق قليلًا لينجح في التباين، فكل شاشة استخدمته ما زالت تحصل على نص هادئ. عامل هذه كتحديثات تصميم: أبرزها في الـ changelog بصور قبل وبعد، لأن الفرق التي لديها اختبارات لقطات شاشة سترى صورها المرجعية تتغيّر.

الـ Changesets والـ changelogs

تذكّر الرفع الصحيح وقت الإصدار لا يصمد مع كثرة المساهمين. تستخدم Northwind أداة Changesets: كل pull request يغيّر حزمة يضيف ملفًا صغيرًا يذكر نوع الرفع وملخّصًا مكتوبًا للمستخدمين.

---
"@northwind/ui": minor
---

Button: add a `loading` prop. While loading, the button keeps its width, sets `aria-busy`, and ignores clicks.

حين يُجهَّز إصدار، تأخذ الأداة أعلى رفع بين الـ changesets المعلّقة، وتحدّث الإصدار، وتحوّل الملخّصات إلى CHANGELOG.md. وهذا المنطق نفسه في صورة مصغّرة:

const order = { patch: 0, minor: 1, major: 2 };

function nextVersion(current, changes) {
  const [major, minor, patch] = current.split('.').map(Number);
  const bump = changes.reduce((top, c) => (order[c.bump] > order[top] ? c.bump : top), 'patch');
  if (bump === 'major') return `${major + 1}.0.0`;
  if (bump === 'minor') return `${major}.${minor + 1}.0`;
  return `${major}.${minor}.${patch + 1}`;
}

const pending = [
  { bump: 'patch', summary: 'Dialog returns focus to its trigger on close.' },
  { bump: 'minor', summary: 'Button: add a `loading` prop.' },
];
console.log(nextVersion('4.7.2', pending));
console.log(nextVersion('4.7.2', [...pending, { bump: 'major', summary: 'Remove Button `kind`.' }]));

الـ changelog الجيد يجمّع الإدخالات حسب الأثر (كاسر، مُضاف، مُصلَح)، ويُكتب للأشخاص الذين يرفعون الإصدار، ويعطي كل إدخال كاسر خطوات الانتقال الخاصة به. عبارة «Refactored Button internals» لا تقول لفريق المنتج شيئًا؛ أما «حُذف kind من Button، استخدم variant، وهناك codemod متاح» فتقول له بالضبط ما يفعل.

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