حين أطلقت Northwind الإصدار 3.4.0 من حزمة الواجهة، فشل البناء لدى أحد عشر فريقًا في الصباح التالي. ملاحظات الإصدار كانت تقول «تحسينات طفيفة». أحد تلك التحسينات أعاد تسمية الـ token المسمّى --nw-color-text-light، لأن الفريق قرّر (محقًّا) أن الاسم مضلِّل. كان تغييرًا جيدًا أُطلق برقم خاطئ، وكلّفنا من الثقة أكثر من أي خلل في تلك السنة. الترقيم هو الطريقة التي يقطع بها نظام التصميم وعوده لمستخدميه، والوعود المكسورة باهظة الثمن.
الترقيم الدلالي للإصدارات (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 مبكرًا.
الـ semver لا يعني شيئًا حتى تكتب ما هو «الـ API العام». في Northwind UI هو:
\ndata-variant وdata-size والـ component tokens؛أي شيء خارج هذه القائمة، مثل أسماء الـ classes الداخلية، أو تداخل الـ DOM داخل المكوّن، أو الدوال المساعدة الخاصة، يمكن أن يتغيّر في أي إصدار. اكتب القائمة في التوثيق، وأخبر الفرق بوضوح أن الاعتماد على التفاصيل الداخلية غير الموثّقة على مسؤوليتها.
\nبعد تحديد الـ API، تصبح معظم القرارات آلية:
\n| التغيير | \nالرفع | \n
|---|---|
| إصلاح Dialog الذي لا يعيد التركيز عند الإغلاق | \nPatch | \n
إضافة prop باسم loading إلى Button | \nMinor | \n
| إضافة مكوّن Tabs جديد أو token جديد | \nMinor | \n
| تحسين قيمة token ضمن الدور نفسه | \nMinor، مع ملاحظة وفروقات بصرية | \n
| إعادة تسمية token أو prop أو مكوّن، أو حذفه | \nMajor | \n
| تغيير قيمة افتراضية، مثل الـ variant الافتراضي لـ Button | \nMajor | \n
صفّان يستحقّان تعليقًا. تغيير القيمة الافتراضية major لأن الكود الذي اعتمد عليها صار يُعرض بشكل مختلف دون تغيير سطر واحد. وتحسينات القيم minor لأن عقد الـ token هو دوره، لا لونه بالضبط؛ فإن صار «النص الهادئ» أغمق قليلًا لينجح في التباين، فكل شاشة استخدمته ما زالت تحصل على نص هادئ. عامل هذه كتحديثات تصميم: أبرزها في الـ changelog بصور قبل وبعد، لأن الفرق التي لديها اختبارات لقطات شاشة سترى صورها المرجعية تتغيّر.
\n\nتذكّر الرفع الصحيح وقت الإصدار لا يصمد مع كثرة المساهمين. تستخدم Northwind أداة Changesets: كل pull request يغيّر حزمة يضيف ملفًا صغيرًا يذكر نوع الرفع وملخّصًا مكتوبًا للمستخدمين.
\n---\n\"@northwind/ui\": minor\n---\n\nButton: 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 };\n\nfunction nextVersion(current, changes) {\n const [major, minor, patch] = current.split('.').map(Number);\n const bump = changes.reduce((top, c) => (order[c.bump] > order[top] ? c.bump : top), 'patch');\n if (bump === 'major') return `${major + 1}.0.0`;\n if (bump === 'minor') return `${major}.${minor + 1}.0`;\n return `${major}.${minor}.${patch + 1}`;\n}\n\nconst pending = [\n { bump: 'patch', summary: 'Dialog returns focus to its trigger on close.' },\n { bump: 'minor', summary: 'Button: add a `loading` prop.' },\n];\nconsole.log(nextVersion('4.7.2', pending));\nconsole.log(nextVersion('4.7.2', [...pending, { bump: 'major', summary: 'Remove Button `kind`.' }]));الـ changelog الجيد يجمّع الإدخالات حسب الأثر (كاسر، مُضاف، مُصلَح)، ويُكتب للأشخاص الذين يرفعون الإصدار، ويعطي كل إدخال كاسر خطوات الانتقال الخاصة به. عبارة «Refactored Button internals» لا تقول لفريق المنتج شيئًا؛ أما «حُذف kind من Button، استخدم variant، وهناك codemod متاح» فتقول له بالضبط ما يفعل.
في التمرين تعطي أرقام إصدارات لدفعة من التغييرات. وبعدها تخطّط لكيفية حذف الأشياء دون أن تكسر عمل أربعين فريقًا في صباح واحد.
\n","toc":[{"id":"sec-1","text":"الـ semver في فقرة واحدة","level":2},{"id":"sec-2","text":"حدّد الـ API العام أولًا","level":2},{"id":"sec-3","text":"تصنيف التغييرات الحقيقية","level":2},{"id":"sec-4","text":"الـ Changesets والـ changelogs","level":2}],"takeaways":["لا يعمل الـ semver إلا حين تكتب ما هو الـ API العام لديك؛ وفي نظام التصميم يشمل ذلك props المكوّنات، والأسماء المصدَّرة، وأسماء الـ tokens، ونقاط ربط CSS الموثّقة.","حذف أي شيء عام أو إعادة تسميته، أو تغيير قيمة افتراضية، تغيير major، حتى حين يبدو صغيرًا.","إضافة props أو مكوّنات أو tokens تغيير minor؛ وإصلاح السلوك ليطابق التوثيق patch.","الـ changelog يُكتب للمستخدمين، ويُجمَّع حسب الأثر، وكل إدخال كاسر يتضمّن خطوات الانتقال."],"further":[{"title":"About semantic versioning (npm Docs)","url":"https://docs.npmjs.com/about-semantic-versioning"},{"title":"Semantic Versioning specification (source)","url":"https://github.com/semver/semver/blob/master/semver.md"},{"title":"Changesets (official repository)","url":"https://github.com/changesets/changesets"}],"quiz":[{"q":"الحزمة @northwind/ui في الإصدار 4.7.2. إصدار جديد يحذف الـ prop المُهمَل kind من Button (حلّ محلّه variant في 4.3.0). ما الإصدار التالي؟
kind ينكسر حين يختفي."},{"text":"4.8.0، لأن prop واحدًا فقط تغيّر.","why":"عدد التغييرات لا يهمّ؛ أي حذف من الـ API العام تغيير كاسر."},{"text":"5.0.0، لأن حذف prop عام يكسر الكود الذي ما زال يستخدمه.","why":"صحيح. الحذف مكانه إصدار major، ويُفضّل تجميعه مع عمليات الحذف المخطّطة الأخرى."}],"answer":2},{"q":"تجعل Northwind اللون --nw-color-text-subtle أغمق قليلًا حتى ينجح في التباين في الوضع الداكن. الاسم والدور يبقيان كما هما. كيف يجب أن يُطلَق؟
أيّ إدخال في الـ changelog هو الأكثر فائدة لفريق منتج؟
","options":[{"text":"“Refactored Button internals and cleaned up styles.”","why":"يصف عمل القائمين على النظام، لا ما يتغيّر عند المستخدم ولا هل عليه أن يفعل شيئًا."},{"text":"“Bumped dependencies.”","why":"دقيق لكنه فارغ؛ لا يقول هل تغيّر شيء مرئي أو سلوكي."},{"text":"“Various fixes and improvements.”","why":"يجبر كل فريق على قراءة الفروقات ليعرف هل هو متأثّر."},{"text":"“Breaking: Buttonkind prop removed. Replace kind="primary" with variant="primary", or run the codemod nw-codemods button-kind.”","why":"صحيح. يقول ما الذي تغيّر، ومَن المتأثّر، وكيف ينتقل بالضبط."}],"answer":3}],"exercise":{"kind":"fill","language":"text","template":"@northwind/ui is at 4.7.2. Each line is a separate release from 4.7.2.\n\nFix: Dialog now returns focus to its trigger on close -> {{0}}\nAdd a `loading` prop to Button -> {{1}}\nRemove the old token name --nw-color-text-light -> {{2}}\nChange Button's default variant from \"primary\" to \"secondary\" -> {{3}}\nA Dialog focus fix plus a new Tabs component -> {{4}}\nDarken --nw-color-text-subtle slightly (same name and role) -> {{5}}","blanks":[{"answers":["4.7.3"]},{"answers":["4.8.0"]},{"answers":["5.0.0"]},{"answers":["5.0.0"]},{"answers":["4.8.0"]},{"answers":["4.8.0"]}],"title":"رقّم الإصدارات","prompt":"طبّق سياسة الترقيم في Northwind من الدرس. كل سطر إصدار مستقل يبدأ من 4.7.2. اكتب رقم الإصدار التالي كاملًا لكلٍّ منها، مثل 4.7.3.
إصلاح التركيز يعيد سلوكًا موثّقًا، فهو patch (4.7.3). والـ prop الجديد إضافة متوافقة مع ما سبق (4.8.0). وحذف اسم token يكسر كل من ما زال يستخدمه، وتغيير القيمة الافتراضية يغيّر العرض دون أي تغيير في الكود، فكلاهما major (5.0.0). والإصدار الذي يجمع إصلاحًا ومكوّنًا جديدًا يأخذ الرفع الأعلى، أي minor (4.8.0). وتحسين القيمة الذي يحافظ على اسم الـ token ودوره تحديث تصميم من نوع minor (4.8.0)، يُطلَق مع ملاحظة في الـ changelog وفروقات بصرية.
\n","checkLabels":{}},"words":639,"readMinutes":4}