كيفية كتابة سجلات تغييرات مفيدة تحفز فريقك

إذا كنت تعمل على منتج رقمي، فسيأتي الوقت عاجلاً أم آجلاً لتسأل نفسك كيفية كتابة سجلات تغييرات مفيدة تجعل عمل الفريق أسهل وبالمناسبة، يجب أن يتمكن عملاؤك من فهم التغييرات بسهولة. تبدأ العديد من الفرق بملاحظات الإصدار المفقودة في مركز المساعدة أو المخفية في سجلات Git، إلى أن يدركوا أن لا أحد يقرأها أو يستخدمها.

والخبر السار هو أنه من خلال اتباع منهجية ما، يمكن تحويل هذه الفوضى إلى نظام يساهم في حل المشكلات. الوضوح والشفافية والقيمة الحقيقية للتطوير والأعمال والعملاء والمستثمرين والدعم.دعونا نرى، خطوة بخطوة، كيفية تصميم سجل تغييرات يعمل بشكل يومي، مع الاستفادة من أفضل الممارسات التقنية (Git، والأتمتة، والقوالب ...) والجانب الإنساني لإدارة التغيير داخل المؤسسة.

ما هو سجل التغييرات ولماذا هو مهم للغاية؟

سجل التغييرات هو، في جوهره، سجل زمني للتغييرات ذات الصلة التي أُجريت على المنتجميزات جديدة، تحسينات، إصلاحات، تغييرات تقنية عميقة، عمليات إيقاف، تجارب... سيكون بمثابة "مذكرات تطور" لبرنامجك، مكتوبة بطريقة تمكن أي شخص من متابعة ما حدث بين إصدار وآخر.

عملياً، يظهر نوعان رئيسيان من سجلات التغييرات عادةً، ويجب التمييز بينهما منذ البداية لأن تختلف النبرة والعمق والجمهور في كل حالة:

• البيانات الصحفيةهذه ملاحظات مصممة للمستخدمين غير التقنيين ولأصحاب الأعمال. تشرح هذه الملاحظات بأسلوب بسيط ما هو جديد، وما تم تحسينه، وما هي المشكلات التي تم حلها، مع التركيز دائماً على الفوائد وحالات الاستخدام.
• سجل التغييرات التقنيةيركز على تفاصيل التنفيذ: تغييرات قاعدة البيانات، وإعادة الهيكلة، وعمليات الترحيل، وإصدارات التبعيات، والبرامج النصية المنفذة... يساعد الفريق على فهم ما حدث دون الخوض في كل عملية تغيير على حدة.

كلا النوعين من السجلات مهمان لأن إنها تخدم أغراضًا مختلفة ولكنها متكاملةداخلياً، توفر هذه الأدوات السياق والتحكم؛ أما خارجياً، فهي تُظهر التقدم، وتبني الثقة، وتساعد في إيصال القيمة.

المزايا الحقيقية للاحتفاظ بسجل تغييرات جيد

إلى جانب مجرد "المظهر الاحترافي"، يوفر سجل التغييرات المُحدّث جيدًا ما يلي: فوائد ملموسة للغاية للفريق والشركة والمستخدمينإنها ليست مجرد وثائق جميلة: إنها أداة عملية.

أولاً، يصبح جزءًا أساسيًا لـ حل المشكلات وتحليل التراجعاتفي حالة حدوث خطأ في الإنتاج، فإن القدرة على مراجعة ما تم إصداره في ذلك اليوم بسرعة (المكونات، والإصدارات، وعمليات الترحيل، والبرامج النصية المنفذة) توفر ساعات من التحقيق وتقلل من متوسط ​​وقت الحل.

ثانيًا، يُعد سجل التغييرات الواضح والعلني وسيلة فعالة لـ مارس الشفافية وعزز الثقة في المنتجيرى العملاء وأصحاب المصلحة أن المنتج يتطور، وأن المشاكل يتم إصلاحها، وأن هناك خارطة طريق حية، بدلاً من تصور "صندوق أسود" يتغير دون تفسير.

علاوة على ذلك، بالنسبة لملفات تعريف الأعمال أو التسويق أو المستثمرين، يعمل سجل التغييرات كعرض للقيمة المقدمة: يُظهر ذلك تطور المنتج بمرور الوقت.يساعد ذلك في تتبع الأولويات ويتيح لك تقييم ما إذا كانت وتيرة التحسينات تتماشى مع أهداف الشركة.

ولا ينبغي أن ننسى الفائدة الداخلية: فبالنسبة للمطورين أو المنتج أو ضمان الجودة أو الدعم، يسمح السجل المنظم جيدًا بما يلي: لتنشيط الذاكرة حول ما حدث في سباق أو في إصدار دون الحاجة إلى تتبع عشرات الفروع وعمليات الدمج في Git. وللدعم، فهو بمثابة برنامج نصي للرد على استفسارات العملاء حول المستجدات أو المشكلات التي تم حلها مؤخرًا.

كما أن لها عنصراً تحفيزياً هاماً: فمشاهدة تاريخ التغيير المنظم تساعد على تخيل العمل الجماعي الذي تم إنجازه على مر الزمنشيء غالباً ما يضيع بين التذاكر والالتزامات، ورؤيته منعكساً يعزز فخر الفريق.

سجل التغييرات الخاص: السجل الداخلي الذي يحتوي على كل شيء

معظم المنتجات تحتاج، كحد أدنى، إلى واحد سجل تغييرات خاص وتقني ومفصل للغايةهذه الوثيقة هي الأساس لعمليات التدقيق والتشخيص والتنسيق بين الفرق. مع أنه يمكنك لاحقًا نشر نسخة مبسطة للعملاء، إلا أن هذه الوثيقة هي "الأصلية" التي يُبنى عليها كل شيء آخر.

في العديد من الأنظمة، يتخذ هذا السجل شكل جدول أو مستند منظم حيث يتم جمع حقول مثل ما يلي لكل إصدار أو نسخة إنتاجية: الوحدة أو المكون المتأثر، نوع التغيير الذي تم إجراؤه، الإصدارات السابقة والجديدة، ملاحظات خاصة، المسؤول التقني، وروابط للاختبارات (على سبيل المثال، في حالات الاختبار أو الأدلة أو خطوط أنابيب التكامل المستمر).

عندما ينطوي التغيير على تأثير على قاعدة البيانات، يكون من المفيد بشكل خاص توثيقه. تفاصيل العمليات التي تم تنفيذها والإشارة إلى النص البرمجي المحدد تم إطلاقها للإنتاج. وبهذه الطريقة، إذا احتاج الفريق بعد أشهر إلى مراجعة ما تم إنجازه بالضبط، فلن يضطر إلى إعادة بناء القصة يدويًا.

يمكن تسجيل سجل التغييرات الخاص هذا لكل عملية نشر (كل "إطلاق إنتاجي") أو لكل إصدار من التطبيق. وفي المنتجات القابلة للتخصيص بدرجة عالية، يمكن أيضًا تنظيمه. حسب حالة الاستخدام أو حسب العميل، مما يشير إلى كيفية تطور كل سيناريو بمرور الوقت.

أفضل الممارسات لسجلات التغييرات الخاصة

ولتجنب تحول هذا السجل الداخلي إلى وثيقة مهملة، من الضروري أن يجب استضافتها في موقع يسهل الوصول إليه وآمن ويسهل على الفريق تعديله.يمكن أن يكون مساحة في ويكي الشركة، أو مستندًا مشتركًا منظمًا جيدًا، أو مخزنًا مباشرة في المستودع (على سبيل المثال، كملف CHANGELOG داخلي).

يُنصح أيضاً بأن يسمح النظام المختار الالتزام بمتطلبات الأمن والتحكم في الوصول ضروري في المشروع، خاصة إذا تم تضمين تفاصيل فنية حساسة أو بيانات البنية التحتية.

يكمن الحل في جعل عملية التحديث مرنة بما يكفي بحيث لا يعتبرها الفريق عبئًا إضافيًا لا يمكن تحمله، لأن إن وجود سجل تغييرات قديم يكاد يكون أسوأ من عدم وجود أي سجل على الإطلاق.فهو يوفر معلومات أمنية زائفة ويجبرك على التحقق من كل شيء من خلال وسائل أخرى.

سجل التغييرات العام: كيفية إيصال الرسالة نفسها دون إرباك المستخدمين

استناداً إلى ذلك السجل الداخلي المفصل، يمكن للمرء أن يبني سجل التغييرات العام، وهو أكثر سهولة في الاستخدام وموجه نحو المستخدم النهائيإن الطريقة التقنية ليست بنفس أهمية ماذا ولماذا: ما هي المشكلة التي تم حلها، وما الذي يحسن التجربة، وما الذي يمكنهم فعله الآن ولم يكونوا قادرين على فعله من قبل.

على الرغم من أن المحتوى الأساسي هو نفسه الموجود في النسخة الداخلية، إلا أن الرسالة تتغير جذريًا: حيث تُحذف تفاصيل التنفيذ وتُترجم التغييرات إلى لغة الأعمال، وحالات الاستخدام، والفوائد الملموسةمن الشائع تجميعها في أقسام مثل "الميزات الجديدة" و "الإصلاحات والتحسينات".

بل يمكنك أن تذهب خطوة أبعد من ذلك عن طريق دمج كتلة صغيرة مع الميزات القادمة أو قيد التطويريُتيح هذا للمستخدمين معرفة ما هو قادم على المدى القريب أو المتوسط. ويساعد في إدارة التوقعات ويُظهر وجود خطة عمل ديناميكية.

كما أنه مكان جيد للإضافة رسائل شكر، إشعارات، أو اعتذارات عندما كانت هناك حوادث ذات صلة، استخدمنا سجل التغييرات كقناة اتصال صادقة مع قاعدة المستخدمين.

تُرفق بعض المنتجات بإدخالات سجل التغييرات العامة مع لقطات الشاشة أو صور GIF المتحركة يعرضون الميزة الجديدة عمليًا، تمامًا مثل الأدوات المألوفة في بيئة التطوير. وهذا يساعد المستخدمين بشكل كبير على فهم التغيير بصريًا دون الحاجة إلى قراءة فقرات مطولة.

نصائح لصياغة السجل العام

القاعدة الذهبية هنا هي اكتب وأنت تفكر في الشخص الذي سيستخدم الأداة، وليس في الشخص الذي قام ببنائها.وهذا يعني تجنب المصطلحات التقنية غير الضرورية، وشرح التأثير ("الآن يمكنك القيام بـ X بشكل أسرع")، وإعطاء الأولوية لما يؤثر فعلاً على حياة المستخدمين اليومية.

من المستحسن الحفاظ على بنية واضحة من إصدار إلى آخر، حتى يتمكن القارئ من تحديد ما هو ذو صلة بسرعة. الأقسام التي تهمك أكثر (على سبيل المثال، أولاً الميزات الجديدة، ثم التحسينات، وأخيراً إصلاحات الأخطاء). يُسهّل هذا التناسق اكتساب عادة قراءة سجل التغييرات.

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

فهم سجلات التغييرات، وGit، والأتمتة بشكل صحيح

إذا كنت تستخدم Git كنظام للتحكم في الإصدارات (وهي الممارسة الأكثر شيوعًا اليوم)، فلديك كنز من المعلومات يمكنك الاستفادة منه لـ إنشاء سجلات التغييرات بطريقة أكثر منهجية وأقل عرضة للنسيانلكن يجب القيام بذلك بحكمة.

الخطوة الأولى هي الحفاظ على الانضباط في عمليات الالتزام: رسائل وصفية ومتسقة، وإذا أمكن، تستند إلى معيار. مثل الالتزامات التقليدية. يسمح هذا بتصنيف التغييرات تلقائيًا إلى أنواع (ميزة، إصلاح، توثيق، إعادة هيكلة...)، والتي تُترجم بعد ذلك إلى أقسام في سجل التغييرات.

وبناءً على ذلك، فإن أدوات مثل سجلات التغييرات التقليدية، أو سجلات تغييرات Git، أو المولدات المدمجة في منصات مثل GitHub أو GitLab لاستخراج التغييرات بين العلامات أو الإصدارات وتفريغها في ملف CHANGELOG منظم حسب الإصدارات.

تتمثل آلية العمل النموذجية فيما يلي: تهيئة المستودع، والعمل على الفروع ذات الالتزامات المكتوبة جيدًا، وتصنيف الإصدارات، ثم قم بإنشاء سجل التغييرات تلقائيًا أو شبه تلقائيًا من السجلعلى سبيل المثال، من خلال دمجه في خط أنابيب التكامل المستمر/التسليم المستمر باستخدام GitHub Actionsثم تتم مراجعته، وصقل اللغة، ونشر النسخة العامة إذا كان ذلك مناسبًا.

لا يحل هذا النوع من الأتمتة محل الحكم البشري، ولكنه يساعد في لمنع حدوث تغييرات دون توثيقها يتطلب تحديث سجل التغييرات جهدًا أقل. مع ذلك، إذا تم التخلي عن المعايير في رسائل الالتزام، فإن فائدة النظام تتراجع بشكل كبير.

الخطوات الأساسية لبناء سجل تغييرات متين

وبغض النظر عن الأدوات المحددة، من المفيد التفكير في تصميم سجل التغييرات كعملية صغيرة متعددة المراحل تتكرر إصدارًا تلو الآخر وتسمح للحفاظ على جودة السجل وفائدته.

تتكون المرحلة الأولى من حدد جميع التحديثات ذات الصلة منذ الإصدار الأخير.لا يتعلق الأمر بتجميع كل تغيير داخلي صغير، بل يتعلق بتجميع الميزات والإصلاحات والتحسينات التي لها تأثير ملحوظ على المنتج.

ثم عليك أن قم بتنظيم هذه التغييرات حسب الإصدار، وضمن كل إصدار، حسب الفئات.من الممارسات الشائعة تجميعها في مجموعات مثل "مضاف / جديد"، "محسن / متغير"، "تم إصلاحه"، "مهجور" أو ما شابه ذلك، بحيث يسهل جدًا تحديد نوع التغيير الذي حدث.

ثم يأتي دور الكتابة: وصف كل تغيير بلغة واضحة ودقيقة. من الناحية المثالية، اشرح ما تم إنجازه ولماذا هو ذو صلةتجنب العبارات الفارغة مثل "العديد من التحسينات الطفيفة" التي لا تفيد أحداً.

بمجرد تحديد الإصدار والفئات والأوصاف، يُنصح باعتماد تنسيق قياسي ومتسق فيما يتعلق بالعناوين والترتيب وأسلوب الجملة واستخدام الروابط وما إلى ذلك، فإن هذا يسهل القراءة والتكامل مع الأدوات الخارجية (المولدات، وبرامج النشر).

وأخيرًا، ينبغي أن يصاحب كل إصدار جديد ما يلي: تحديث سجل التغييرات وإبلاغه للفرق المعنية، سواء من خلال منصة التعليمات البرمجية نفسها (الإصدارات على GitHub/GitLab)، أو موقع المنتج الإلكتروني، أو مركز المساعدة، أو حملات البريد الإلكتروني ووسائل التواصل الاجتماعي.

كيفية إدارة سجل التغييرات والحفاظ عليه بمرور الوقت

الصعوبة الحقيقية لا تكمن في فتح ملف سجل التغييرات، بل في... للحفاظ عليه فعالاً وموثوقاً طوال فترة المشروعلذلك، يجب التعامل معه كجزء آخر من سير العمل وليس كشيء يتم ملؤه على عجل في النهاية "إذا كان هناك وقت".

بدايةً، من المفيد جداً تحديد ذلك منذ البداية. هيكل واضح، متوافق مع الأدوات الخارجية وسهل المتابعةتتمثل إحدى الطرق الكلاسيكية في سرد ​​الإصدارات بترتيب عكسي (الأحدث أولاً)، وضمن كل إصدار، أقسام تحتوي على قوائم مختصرة بالتغييرات.

من المهم أيضاً أن يكون التنسيق المختار قابلاً للقراءة البشرية وسهل التعديل: عادةً ما يكون تنسيق Markdown وHTML العادي خيارين جيدين لأن تتكامل هذه الأنظمة بشكل جيد مع المستودعات وأنظمة إدارة المستندات. وهي سهلة المعالجة بواسطة البرامج النصية.

فيما يتعلق بالمحتوى، من الأفضل التركيز على التغييرات الجوهرية (الميزات الجديدة، وإصلاحات الأخطاء الرئيسية، والقرارات المعمارية، وتغييرات السلوك) وتجنب الإسهاب في التفاصيل التافهة. فسجل التغييرات المزدحم بالتفاصيل غير الضرورية... تضيع المعلومات المهمة بين عشرات الملاحظات التافهة.

ومن الأمور الأساسية الأخرى عدم إلقاء كل المسؤولية على شخص واحد: من الناحية المثالية، يشعر الفريق بأكمله بأنه جزء من الحفاظ على الرقم القياسييمكن لكل شخص المساهمة بمسودات من تذاكره أو قصص المستخدم الخاصة به، والتي تتم مراجعتها وتوحيدها بعد ذلك من قبل شخص لديه رؤية عالمية.

وأخيرًا، من العملي جدًا ربط سجل التغييرات بأدوات إدارة العمل نفسها (المشكلات، والمهام، والحوادث). وفي العديد من البيئات، تُستخدم الوسوم والمراجع المتبادلة لهذا الغرض. قم بربط كل إدخال في سجل التغييرات بالمشكلة أو طلب السحب المقابل.مما يسهل إمكانية التتبع في حال تطلب الأمر إجراء مزيد من التحقيقات.

أدوات وموارد لتحسين سجل التغييرات الخاص بك

بمجرد وضع الأسس، يكون الوقت مناسبًا للاعتماد على الأدوات التي تجعل المهمة أسهل وتسمح أتمتة أجزاء من العملية دون فقدان السيطرة على النتيجة النهائية.

من جهة أخرى، توجد أدوات تقوم بإنشاء ملاحظات الإصدار من الوسوم ورسائل الالتزام، مثل مولدات ملاحظات إصدار Git أو البرامج النصية القائمة على اصطلاحات الرسائل. وعادةً ما تسمح لك بتخصيص تنسيق الإخراج ليتناسب مع قوالبك.

توفر منصات استضافة التعليمات البرمجية نفسها ميزات مفيدة: على سبيل المثال، آليات إصدار GitHub أو GitLab تتيح لك هذه الميزة إنشاء إصدارات موسومة وكتابة سجل التغييرات المرتبط بها هناك مباشرة، والذي يمكن بعد ذلك مزامنته مع الوثائق العامة.

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

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

بغض النظر عن طريقة اختيار المكدس، فإن الأمر المهم هو أن تتكيف الأدوات مع سير عمل فريقك وليس العكس. فالنظام القوي جداً، ولكن يُنظر إليه على أنه غريب أو معقد، سينتهي به الأمر إلى استخدامه بشكل قليل أو سيئ.

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