كيف تكتبون سجل تغييرات (وملاحظات إصدار) يقرؤه العملاء
أطلقتم عشرات الأشياء الشهر الماضي. وسجل تغييراتكم يقول “إصلاح أخطاء وتحسينات في الأداء.”
والعملاء الذين كانوا ينتظرون أحد تلك الإصلاحات لا يعرفون أنه وصل. والعميل المحتمل الذي يقارنكم بمنافس يرى منتجًا يبدو كأنه لم يتحرك منذ الربيع.
وهذه هي طريقة كتابة سجل تغييرات يقرؤه الناس فعلًا. اكتبوا للعميل، لا لمن دمج الشيفرة. أرّخوا كل مدخل. جمّعوا التغييرات تحت New وImproved وFixed. ابدؤوا كل مدخل بما يستطيع أحدهم فعله الآن، وأضيفوا سطرًا واحدًا عن أهميته، وقولوا أين يجدونه. واستبعدوا كل ما لا يستطيع العميل رؤيته، وكل ما لم يصبح فعليًا بعد. ثم انشروا بإيقاع ثابت، حتى لو كانت بعض الأسابيع قصيرة.
هذا هو معظم الأمر. وبقية المقال قالب، ومجموعة أمثلة سيئة مقابل جيدة، وروتين للانتقال من طلبات السحب المدمجة إلى ملاحظات منشورة دون أن يلتهم يوم الجمعة لديكم.
سجل التغييرات مقابل ملاحظات الإصدار: ما الفرق؟
يستخدم الناس الكلمتين بالتبادل، لكن هناك فعلًا جمهورين.
سجل تغييرات المطورين عادةً ملف CHANGELOG.md في المستودع. وهو لمن يدمجون واجهة البرمجة (API) أو مجموعة التطوير (SDK) أو مكتبتكم. وهم يهتمون بأرقام الإصدارات والتغييرات الكاسرة وما يُلغى استخدامه. وKeep a Changelog هو المرجع القياسي هنا، وأعرافه معقولة: الأحدث أولًا، وقسم واحد لكل إصدار، وتجميع التغييرات تحت Added وChanged وDeprecated وRemoved وFixed وSecurity، وقسم “Unreleased” في الأعلى للعمل المدموج وغير المُصدَر.
ملاحظات الإصدار (أو “تحديثات المنتج”، أو صفحة سجل تغييرات عامة) للعملاء الذين يستخدمون المنتج. وهم لا يهتمون بأنكم رفعتم إصدار تبعية. إنهم يريدون معرفة ما يستطيعون فعله الآن ولم يكونوا يستطيعونه الأسبوع الماضي.
وإذا كنتم تديرون منتج برمجيات كخدمة (SaaS)، فأنتم على الأرجح تحتاجون إلى الثاني أكثر من الأول. وكثير من الفرق تحتاج إلى الاثنين، وهذا لا بأس به: قائمة واحدة بالعمل المدموج يمكن أن تغذي نصين. فقط لا تنشروا نسخة المطورين وتسمّوها ملاحظات إصدار.
قالب ملاحظات إصدار يمكنكم نسخه
يصلح هذا لتحديث منتج أسبوعي أو كل أسبوعين، على صفحة سجل تغييرات أو في أداة داخل التطبيق أو في رسالة بريد.
## 6 October 2026
### New
**[What you can now do, in plain words]**
[One or two sentences: what it does and who it's for.]
Find it in **[Page > Section]**. [Link to help article]
### Improved
**[The thing that got better]**
[What's different from before, in terms the customer notices:
faster, fewer clicks, works on mobile, handles bigger files.]
### Fixed
- [Symptom the customer saw], now fixed.
- [Symptom the customer saw], now fixed.
### Heads up (only if needed)
**[Anything changing or going away]**
[What's happening, when, and what they need to do.]
بضع قواعد تجعله ينجح:
- العناوين تصف النتيجة لا اسم الميزة. “صدّروا التقارير الكبيرة دون انتهاء مهلة” أفضل من “تصدير CSV غير متزامن”.
- الإصلاحات تصف العَرَض. يتذكر العملاء “كانت المجاميع متأخرة بيوم”، لا “معالجة المنطقة الزمنية في مهمة التجميع”.
- أحيلوا إلى مقالة المساعدة لكل ما هو جديد. سجل التغييرات يقول إن شيئًا موجود، والمقالة تقول كيف يُستخدم. وإذا لم تكتبوا واحدة، فإن دليلنا عن كتابة مقالات مركز المساعدة فيه قالب لذلك أيضًا.
- ابدؤوا بالتغيير الذي سيهتم به معظم الناس، حتى لو لم يكن الأصعب بناءً.
إدخالات سجل تغييرات سيئة مقابل جيدة
أكثر الإخفاقات شيوعًا هو لصق رسائل الإيداع (commit). وهذا شكل ذلك:
v2.14.0
- feat(export): csv async job
- fix: tz bug in reports
- refactor billing svc
- bump deps
- misc improvements
كل ما فيها صحيح. ولا شيء منه مفيد للعميل. مدخلان ضجيج داخلي، وواحد بلا معنى (“misc improvements”)، والتغييران الحقيقيان مكتوبان لمن راجع طلب السحب.
وهذا هو الإصدار نفسه بعد إعادة كتابته:
6 October
NEW: Big CSV exports run in the background
Exports over 10,000 rows no longer time out. Start the export
and we'll email you a link when the file is ready.
Find it in Reports > Export.
FIXED: Report dates now match your timezone
Daily totals were splitting at midnight UTC instead of your
local midnight, so some days looked short. They're correct now,
including for past reports.
مدخلان بدل خمسة. كل منهما يقول ما تغيّر، ولماذا ينبغي أن يهتم القارئ، وأين ينظر. وقد اختفى إعادة الهيكلة ورفع التبعيات لأن أي عميل لن يلاحظهما.
وبضعة أزواج أخرى، لأن النمط يحتاج وقتًا ليصبح عادة:
| سيئ | جيد |
|---|---|
| أُضيف SSO | سجّلوا الدخول عبر Okta أو Google Workspace. يستطيع المسؤولون تفعيله في الإعدادات ← الأمان. |
| تحسين الأداء | تُحمَّل لوحة التحكم أسرع بكثير في الحسابات الكبيرة. المشاريع التي تضم آلاف العناصر لم تعد تتعثر عند التحميل الأول. |
| إصلاح خطأ في الإشعارات | لن تتلقوا رسائل بريد مكررة بعد الآن حين يذكركم أحدهم مرتين في تعليق واحد. |
| إيقاف نقاط نهاية v1 | ستتوقف واجهة v1 عن العمل في 1 مارس. انتقلوا إلى v2 قبل ذلك. وهذا ما سيتغير. |
لاحظوا أن “أسرع بكثير” عبارة مبهمة. فإذا كان لديكم رقم حقيقي قستموه، فاستخدموه. وإذا لم يكن، فصفوا التجربة بدل اختلاق نسبة مئوية.
كيف تكتبون سجل تغييرات من طلبات السحب المدمجة
معظم الفرق لا تعاني من الكتابة. إنها تعاني من تذكّر ما أُطلق. وهذا روتين يصمد.
1. اجمعوا. اسردوا كل ما دُمج منذ المدخل الأخير. باستخدام GitHub CLI:
gh pr list --state merged \
--search "merged:>=2026-10-27" \
--json number,title,labels,mergedAt,url \
--limit 100
2. صفّوا. اسألوا عن كل طلب سحب سؤالين. هل يستطيع العميل أن يرى هذا أو يشعر به؟ وهل هو فعلي بالنسبة إليه؟ إعادة الهيكلة الداخلية وتغييرات CI وإصلاحات الاختبارات تُستبعد. وكذلك كل ما خلف علم ميزة (feature flag) لم يُفعَّل. إعلان عمل لا يستطيع العملاء الوصول إليه بعد أسوأ من عدم الإعلان، لأنكم ستتلقون تذاكر “أين هو؟“.
3. جمّعوا. صنّفوا ما تبقى في New وImproved وFixed. وكثيرًا ما تتراكم عدة طلبات سحب صغيرة لتصبح مدخلًا واحدًا (“التحرير الجماعي” قد يكون أربعة طلبات سحب).
4. أعيدوا الكتابة. حوّلوا كل مجموعة إلى مدخل باستخدام القالب. الفائدة أولًا، وكلمات بسيطة، وأين يجدونه.
5. انشروا وأحيلوا. انشروه، واربطوا كل ميزة جديدة بمقالة المساعدة الخاصة بها، وشاركوه حيث سيراه عملاؤكم.
والحيلة التي تجعل الخطوة 4 أسهل بكثير هي طلب الجملة الموجهة للعميل عند تقديم طلب السحب، بينما ما زال كاتبه يتذكر ما بناه. أضيفوا قسمًا إلى .github/pull_request_template.md:
## Customer-facing change
<!-- One sentence a customer would understand, or "None". -->
<!-- e.g. "You can now export reports over 10,000 rows." -->
- [ ] Behind a feature flag (don't announce until it's on)
- [ ] Help articles checked
وخانة الاختيار الأخيرة مهمة. فكل تغيير مُطلَق يمس الواجهة قد يترك مقالة مساعدة قديمة، وسجل التغييرات لحظة جيدة لاكتشاف ذلك. ونتناول هذا الجانب في كيف تحافظون على تحديث التوثيق.
كم مرة ينبغي أن تنشروا تحديثات المنتج؟
وافقوا إيقاع الإطلاق لديكم، في حدود المعقول. فإذا كنتم تُطلقون باستمرار، فإن ملخصًا أسبوعيًا أو كل أسبوعين يُقرأ أفضل من مدخل لكل نشر. وإذا كنتم تُطلقون شهريًا، فانشروا شهريًا.
والأهم من التكرار هو الاتساق. فسجل تغييرات فيه ثلاثة مدخلات في يناير ولا شيء بعدها يقول للزوار شيئًا ربما لم تقصدوه. والأسبوع القصير لا بأس به. و”إصلاحان هذا الأسبوع، وإصدار أكبر الأسبوع القادم” أفضل من الصمت.
والإطلاقات الكبيرة تستحق أكثر من سطر في سجل التغييرات: إعلان مستقل، ورسالة بريد، وربما فيديو قصير. فسجل التغييرات هو السجل الجاري، لا خطة التسويق كلها.
أين تضعون سجل تغييراتكم
- صفحة عامة على
/changelogأو/updates. مناسبة للعملاء المحتملين وللبحث. - داخل التطبيق، كرابط أو أداة “ما الجديد”. وهنا يراه المستخدمون الحاليون فعلًا.
- البريد الإلكتروني، كملخص شهري لمن اشتركوا.
- المستودع، كملف
CHANGELOG.md، إذا كان المطورون يدمجون خدمتكم.
وأدوات مخصصة مثل Beamer وHeadway وLaunchNotes وسجل تغييرات Canny تتعامل جيدًا مع جانبي الأداة المدمجة والبريد. وكثير من الفرق يكتفي بصفحة على موقع وثائقه. فالأداة أقل أهمية من العادة.
أين يناسب Ellie Docs
إفصاح: هذه مشكلة بنينا لها شيئًا. يراقب Ellie Docs طلبات السحب المدمجة لديكم ويصوغ منها مدخلات سجل تغييرات، مكتوبة للعملاء لا للمراجعين. ويحجب المدخلات الخاصة بالعمل غير المُصدَر أو خلف علم ميزة، حتى لا تعلنوا عن أشياء لا يستطيع الناس استخدامها. وأنتم من تحررون كل مدخل أو تسقطونه أو تنشرونه. لا شيء يخرج من تلقاء نفسه.

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

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