mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-08-21 17:58:15 +02:00
bee0534514
Previously they had to be duplicated from the page frontmatter but that's not necessary and also makes it possible to have correct OpenGraph title and descriptions.
251 lines
14 KiB
Plaintext
251 lines
14 KiB
Plaintext
---
|
||
title: تاریخچهٔ تغییرات را نگه دارید
|
||
description: خروجی git log را به اسم تاریخچهٔ تغییرات پروژه منتشر نکنید.
|
||
language: fa
|
||
version: 1.0.0
|
||
---
|
||
<link type="text/css" rel="stylesheet" href="https://cdn.rawgit.com/rastikerdar/vazir-font/v19.0.0/dist/font-face.css">
|
||
|
||
<style>
|
||
body,html,h1,h2,h3,h4,h5,h6,a{font-family:Vazir;direction:rtl;text-align:right}
|
||
div.frequently-asked-questions h4:after{float:left}
|
||
pre {direction:ltr;text-align:left}
|
||
</style>
|
||
|
||
.header
|
||
.title
|
||
%h1= current_page.data.title
|
||
%h2= current_page.data.description
|
||
|
||
= link_to data.links.changelog do
|
||
Version
|
||
%strong= current_page.metadata[:page][:version]
|
||
|
||
%pre.changelog{ lang: "en" }= File.read("CHANGELOG.md")
|
||
|
||
.answers
|
||
%h3#what
|
||
%a.anchor{ href: "#what", aria_hidden: "true" }
|
||
تاریخچهٔ تغییرات چیست؟
|
||
|
||
%p
|
||
تاریخچهٔ تغییرات، فایلی شامل تغییرات عمدهٔ هر نسخه از پروژه به‌ترتیبِ زمان انتشار هر نسخه است.
|
||
|
||
%h3#why
|
||
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||
چرا باید لیست تغییرات را نگهداری کنیم؟
|
||
|
||
%p
|
||
برای اینکه کاربران بدانند در هر نسخه از پروژه چه اتفاقااتی افتاده است.
|
||
|
||
%h3#who
|
||
%a.anchor{ href: "#who", aria_hidden: "true" }
|
||
لیست تغییرات به درد چه کسانی می‌خورد؟
|
||
|
||
%p
|
||
مصرف‌کننده‌ها، توسعه‌دهنده‌ها، کاربران نهایی و در یک کلام مردم.
|
||
|
||
%p
|
||
مسلماً وقتی نرم‌افزاری بروزرسانی می‌شود، کاربران آن دوست دارند بدانند چرا و چطور این تغییرات اعمال شده است.
|
||
|
||
.good-practices
|
||
%h3#how
|
||
%a.anchor{ href: "#how", aria_hidden: "true" }
|
||
چطور یک تاریخچهٔ تغییرات خوب بسازیم؟
|
||
|
||
%h4#principles
|
||
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
||
راهنمای کلی
|
||
|
||
%ul
|
||
%li
|
||
تاریخچهٔ تغییرات <em>برای انسان</em> است، نه ماشین.
|
||
%li
|
||
برای هر نسخه از پروژه، یک مدخل جدید تعریف کنید.
|
||
%li
|
||
تغییرات مشابه را دسته‌بندی کنید.
|
||
%li
|
||
نسخه‌ها و بخش‌ها قابل لینک‌شدن باشند.
|
||
%li
|
||
آخرین نسخه را در ابتدا قرار دهید.
|
||
%li
|
||
تاریخ انتشار هر نسخه را مشخص کنید.
|
||
%li
|
||
بگویید که آیا از #{link_to "نسخه‌بندی معنایی", data.links.semver} پیروی می‌کنید یا نه.
|
||
|
||
%a.anchor{ href: "#types", aria_hidden: "true" }
|
||
%h4#types انواع تغییرات
|
||
|
||
%ul
|
||
%li
|
||
%code Added
|
||
برای قابلیت‌های جدید.
|
||
%li
|
||
%code Changed
|
||
برای تغییر در عملکردهای فعلی.
|
||
%li
|
||
%code Deprecated
|
||
برای قابلیت‌هایی که حذف می‌شود.
|
||
%li
|
||
%code Removed
|
||
برای قابلیت‌های حذف‌شده.
|
||
%li
|
||
%code Fixed
|
||
برای خطاهای رفع‌شده.
|
||
%li
|
||
%code Security
|
||
برای آسیب‌پذیری‌های امنیتی.
|
||
|
||
.effort
|
||
|
||
%h3#effort
|
||
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
||
چطور ثبت تغییرات پروژه را آسان‌تر کنیم؟
|
||
|
||
%p
|
||
در بالای فایل تاریخچهٔ تغییرات، بخشی را تحت عنوان <code>Unreleased</code> برای دنبال‌کردن تغییرات پیش‌رو در نظر بگیرید.
|
||
|
||
%p این کار دو فایده دارد:
|
||
|
||
%ul
|
||
%li
|
||
اولاً کاربران می‌توانند پیش از انتشار یک نسخهٔ جدید، از تغییراتی که می‌توانند در نسخهٔ بعدی انتظار داشته باشند مطلع شوند.
|
||
%li
|
||
دوماً هنگام انتشار نسخهٔ جدید، می‌توانید به‌راحتی بخش <code>Unreleased</code> را در قالب یک نسخهٔ جدید به بخش انتشاریافته‌ها منتقل کنید و دیگر لازم نباشد بروید ببینید چه تغییراتی ایجاد شده است.
|
||
|
||
.bad-practices
|
||
%h3#bad-practices
|
||
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||
آیا تاریخچهٔ تغییرات می‌تواند بد نوشته شود؟
|
||
|
||
%p بله. در شرایط زیر.:
|
||
|
||
%h4#log-diffs
|
||
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||
استفاده از خروجی log diff به عنوان تاریخچهٔ تغییرات
|
||
|
||
%p
|
||
استفاده از خروجی log diffها به عنوان تاریخچهٔ تغییرات، ایدهٔ بدی است. این خروجی مملو از اطلاعات درهم‌وبرهم است؛ مثلاً کامیت‌های مربوط به مرج، کامیت‌هایی با عناوین مبهم، تغییرات مربوط به مستندات و غیره.
|
||
|
||
%p
|
||
هدف از یک کامیت، ثبت یک گام انجام‌شده در روند تکامل سورس کد است. برخی از پروژه‌ها، کامیت‌های تمیزی دارند و برخی نه.
|
||
|
||
%p
|
||
هدف از یک مدخل جدید در فایل تاریخچهٔ تغییرات، مستندسازی شفاف تغییرات مهمِ پروژه برای کاربران نهایی است. هر مدخل در تاریخچهٔ تغییرات لزوماً متناظر با یک کامیت در تاریخچهٔ کامیت‌ها نیست. ممکن است چندین کامیت مختلف، مربوط به یک تغییر باشد و بالعکس یک کامیت (غیراستاندارد) دربردارندهٔ چندین تغییر مهم باشد.
|
||
|
||
%h4#ignoring-deprecations
|
||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||
نادیده‌گرفتن چیزهای منسوخ‌شده
|
||
|
||
%p
|
||
وقتی کاربران از یک نسخه به نسخهٔ دیگر به‌روزرسانی می‌کنند، باید بدانند که چه موقع نسخهٔ جدید، تغییرات ناسازگار به‌همراه دارد؛ یعنی مثلاً بعد از بروزرسانی یک کتابخانه که پروژهٔ شما به آن وابسته بوده، آیا بخش‌هایی از پروژه از کار می‌افتد یا نه. اگر بله، کدام بخش‌ها. پاسخ به این سؤال کمک می‌کند توسعه‌دهنده‌ها متناسب با نسخهٔ جدید، قسمت‌های منسوخ‌شده را جایگزین کرده و بعد از آن اقدام به بروزرسانی کنند.
|
||
|
||
%h4#confusing-dates
|
||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||
تاریخ‌های گیج‌کننده
|
||
|
||
%p
|
||
در هر نقطه‌ای از دنیا شکل نمایش تاریخ متفاوت است؛ بنابراین پیداکردن یک قالب نمایش همه‌فهم برای کل مردم دنیا کار دشواری است. مزیت استفاده از قالب‌هایی مثل <code>17-07-2017</code> این است که در آن ترتیب بزرگترین به کوچکترین واحدها یعنی سال، ماه و روز رعایت شده است. این باعث می‌شود که برخلاف برخی از قالب‌ها که در آن جای ماه و روز عوض شده، درک تاریخ دچار ابهام نشود. با درنظرگرفتن این دلایل و این واقعیت که این فرمت، یک #{link_to "استاندارد ایزو", data.links.isodate} است، این قالب را برای مدخل‌های تاریخچهٔ تغییرات در نظر گرفته‌ایم.
|
||
|
||
%aside
|
||
اگر فکر می‌کنید جای موارد بیشتری در این لیست خالی است با
|
||
= link_to "ارسال ایشو", data.links.issue
|
||
یا ارسال پول‌ریکوئست به من کمک کنید.
|
||
|
||
.frequently-asked-questions
|
||
%h3#frequently-asked-questions
|
||
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
||
سوالات متداول
|
||
%h4#standard
|
||
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
||
آیا فرمت استانداردی برای تاریخچهٔ تغییرات وجود دارد؟
|
||
|
||
%p
|
||
حقیتاً نه. یک "راهنمای" #{link_to "راهنمای شیوه ثبت تاریخچهٔ تغییرات GNU", data.links.gnustyle}
|
||
و یک #{link_to "فایل دو پاراگرافی بلندِ GNU NEWS", data.links.gnunews}
|
||
وجود دارد که متأسفانه هردویشان نارسا و ناکافی هستند.
|
||
|
||
%p
|
||
این پروژه قصد دارد
|
||
= link_to "قراردادی بهتر برای ثبت تاریخچهٔ تغییرات باشد", data.links.changelog
|
||
که برگرفته از تجربیات جامعهٔ متن‌باز است.
|
||
|
||
%p
|
||
از نقد سالم، بحث‌وگفتگو و پیشنهادها
|
||
= link_to "استقبال می‌کنیم.", data.links.issue
|
||
|
||
|
||
%h4#filename
|
||
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
||
نام فایل تاریخچهٔ تغییرات چه چیزی باشد؟
|
||
|
||
%p
|
||
نام این فایل را <code>CHANGELOG.md</code> بگذارید. بعضی پروژه‌ها از
|
||
<code>HISTORY</code>, <code>NEWS</code> یا <code>RELEASES</code> استفاده می‌کنند.
|
||
|
||
%h4#github-releases
|
||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||
چرا از ریلیزهای گیت‌هاب استفاده نکنیم؟
|
||
%p
|
||
ابتکار خوبی است. در هنگام انتشار #{link_to "Release", data.links.github_releases}ها می‌توانید به جای عرضهٔ یک نسخهٔ ساده (مثلاً یک برچسب خالی با نام <code>v1.0.0</code>)، لیست تغییرات آن نسخه را در قالب یک یادداشت، به آن برچسب ضمیمه کنید.
|
||
|
||
%p
|
||
اما نکته این است که تاریخچهٔ تغییراتی که در هر ریلیز گیت‌هاب منتشر می‌کنید فقط در خودِ گیت‌هاب قابل استفاده است و به‌راحتی نمی‌توانید آن را به جای دیگری منتقل کنید. شاید بتوانید بسیار شبیه نسخهٔ پیشنهادی این سند کنید ولی کار زحمت‌داری است.
|
||
|
||
%p
|
||
مشاهدهٔ تغییرات پروژه در لابه‌لای ریلیزهای گیت‌هاب، به اندازهٔ دیدن همهٔ تغییرات در یک فایل، آسان و دلچسب نیست. فایل‌هایی با حرف بزرگ،
|
||
(<code>README</code>, <code>CONTRIBUTING</code>, غیره.)
|
||
جذابیت بیشتری برای کاربران دارد. مشکل کوچک بعدی این است که رابط کاربری فعلی اجازه نمی‌دهد بین تاریخچهٔ کامیت‌ها در عرضه‌های مختلف، پیوند برقرار کنید.
|
||
%h4#automatic
|
||
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
||
آیا نمی‌توان مطابقت تاریخچهٔ تغییرات با موازین این سند را به صورت خودکار انجام داد؟
|
||
|
||
%p
|
||
مشکل است؛ چون افراد از فرمت‌ها و نام‌گذاری‌های متعددی برای این فایل استفاده می‌کنند.
|
||
|
||
%p
|
||
#{link_to "Vandamme", data.links.vandamme} یک روبی gem است که توسط تیم
|
||
Gemnasium ساخته شده است. این ابزار، تاریخچهٔ تغییرات پروژه‌های متن‌باز (البته نه همه) را بررسی می‌کند.
|
||
|
||
|
||
%h4#yanked
|
||
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
||
عرضه‌های yanked چطور؟
|
||
|
||
%p
|
||
عرضه‌های Yanked نسخه‌هایی هستند که به خاطر باگ جدی یا مشکل امنیتی باید گرفته شوند. این نسخه‌ها اغلب حتی در تاریخچهٔ تغییرات نیز دیده نمی‌شوند، اما باید اضافه شوند. آن‌ها را به صورت زیر در فایل تاریخچهٔ تغییرات نشان دهید:
|
||
%p <code>## [0.0.5] - 2014-12-13 [YANKED]</code>
|
||
|
||
%p
|
||
برچسب <code>[YANKED]</code> را به این دلیل، به‌شکل متمایز در تاریخچهٔ تغییرات آورده‌ایم که نظرها را به خود جلب کند. بعلاوه وجود کروشه، کار پارزرها را راحت‌تر می‌کند.
|
||
|
||
|
||
%h4#rewrite
|
||
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
||
آیا لازم است تاریخچهٔ تغییرات را بازنویسی کنیم؟
|
||
|
||
%p
|
||
قطعاً. معمولاً همیشه دلیل خوبی برای بهبود تاریخچهٔ تغییرات وجود دارد. من معمولاً به‌طور منظم، فایل تاریخچهٔ تغییرات را برای پروژه‌های متن‌بازی که این کار را انجام نداده‌اند می‌نویسم و تغییرات را به صورت یک پول‌ریکوئست ارائه می‌دهم.
|
||
|
||
%p
|
||
گاهی نیز ممکن است یادتان رفته باشد که تغییرات ناسازگارِ یک نسخه را ثبت کنید. در چنین شرایطی نیز واضح است که باید تاریخچهٔ تغییرات را بروزرسانی کنید.
|
||
|
||
|
||
%h4#contribute
|
||
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
||
چطور می‌توانم مشارکت کنم؟
|
||
|
||
%p
|
||
این سند، <strong>کامل و بی‌نقص</strong> نیست؛ صرفاً نظرات به‌دقت بررسی‌شده‌ای است که همراه اطلاعات و مثال‌هایی، در اینجا قرار داده‌ام.
|
||
|
||
%p
|
||
این به خاطر آن است که می‌خواهم جامعهٔ ما توسعه‌دهنده‌ها به یک اتفاق‌نظر برسد. من معتقدم بحث‌وگفتگو به‌اندازهٔ نتیجه مهم است.
|
||
|
||
%p
|
||
بنابراین شما نیز <strong>#{link_to "دست به کار شوید", data.links.repo}</strong>.
|
||
|
||
.press
|
||
%h3 گفتگو
|
||
%p
|
||
در #{link_to "پادکست Changelog", data.links.thechangelog}، گفتگویی داشته‌ام دربارهٔ انگیزهٔ پشت این پروژه و اینکه چرا متصدیان نگهداری و مشارکت‌کنندگان پروژه‌ها باید به تاریخچهٔ تغییرات اهمیت بدهند.
|