mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-28 00:04:10 +02:00
Add Persian translation for v1.1.0 and minor edits and improvements (#538)
* Some minor edit * Remove a section that was related to v1.1.0 * add Persian translation for version 1.1.0 * renaming based on ISO 639-1
This commit is contained in:
Ayub Kokabi
GitHub
parent
0f00ac59d5
commit
d7f9d60e56
@ -118,7 +118,7 @@ $languages = {
|
|||||||
"ko" => {
|
"ko" => {
|
||||||
name: "한국어"
|
name: "한국어"
|
||||||
},
|
},
|
||||||
"fa-IR" => {
|
"fa" => {
|
||||||
name: "فارسی"
|
name: "فارسی"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
250
source/fa/1.0.0/index.html.haml
Normal file
250
source/fa/1.0.0/index.html.haml
Normal file
@ -0,0 +1,250 @@
|
|||||||
|
---
|
||||||
|
description: تاریخچهٔ تغییرات را نگه دارید
|
||||||
|
title: تاریخچهٔ تغییرات را نگه دارید
|
||||||
|
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 تاریخچهٔ تغییرات را نگه دارید
|
||||||
|
%h2 خروجی git log را به اسم تاریخچهٔ تغییرات پروژه منتشر نکنید.
|
||||||
|
|
||||||
|
= 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}، گفتگویی داشته‌ام دربارهٔ انگیزهٔ پشت این پروژه و اینکه چرا متصدیان نگهداری و مشارکت‌کنندگان پروژه‌ها باید به تاریخچهٔ تغییرات اهمیت بدهند.
|
||||||
@ -1,8 +1,8 @@
|
|||||||
---
|
---
|
||||||
description: تاریخچهٔ تغییرات را نگه دارید
|
description: تاریخچهٔ تغییرات را نگه دارید
|
||||||
title: تاریخچهٔ تغییرات را نگه دارید
|
title: تاریخچهٔ تغییرات را نگه دارید
|
||||||
language: fa-IR
|
language: fa
|
||||||
version: 1.0.0
|
version: 1.1.0
|
||||||
---
|
---
|
||||||
<link type="text/css" rel="stylesheet" href="https://cdn.rawgit.com/rastikerdar/vazir-font/v19.0.0/dist/font-face.css">
|
<link type="text/css" rel="stylesheet" href="https://cdn.rawgit.com/rastikerdar/vazir-font/v19.0.0/dist/font-face.css">
|
||||||
|
|
||||||
@ -15,7 +15,7 @@ pre {direction:ltr;text-align:left}
|
|||||||
.header
|
.header
|
||||||
.title
|
.title
|
||||||
%h1 تاریخچهٔ تغییرات را نگه دارید
|
%h1 تاریخچهٔ تغییرات را نگه دارید
|
||||||
%h2 نگذارید دوستانتان، خروجی git log را به اسم تاریخچهٔ تغییرات پروژه منتشر کنند.
|
%h2 خروجی git log را به اسم تاریخچهٔ تغییرات پروژه منتشر نکنید.
|
||||||
|
|
||||||
= link_to data.links.changelog do
|
= link_to data.links.changelog do
|
||||||
Version
|
Version
|
||||||
@ -29,26 +29,29 @@ pre {direction:ltr;text-align:left}
|
|||||||
تاریخچهٔ تغییرات چیست؟
|
تاریخچهٔ تغییرات چیست؟
|
||||||
|
|
||||||
%p
|
%p
|
||||||
تاریخچهٔ تغییرات، فایلی شامل تغییرات قابل‌توجهِ هر نسخه از پروژه به‌ترتیبِ زمان انتشار هر نسخه است.
|
تاریخچهٔ تغییرات، فایلی شامل تغییرات عمدهٔ هر نسخه از پروژه به‌ترتیبِ زمان انتشار هر نسخه است.
|
||||||
|
|
||||||
%h3#why
|
%h3#why
|
||||||
%a.anchor{ href: "#why", aria_hidden: "true" }
|
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||||||
چرا باید لیست تغییرات را نگهداری کنیم؟
|
چرا باید لیست تغییرات را نگهداری کنیم؟
|
||||||
|
|
||||||
%p
|
%p
|
||||||
برای اینکه مردم بفهمند در هر نسخه از پروژه چه تغییرات عمده‌ای وجود داشته است.
|
برای اینکه کاربران بدانند در هر نسخه از پروژه چه اتفاقااتی افتاده است.
|
||||||
|
|
||||||
%h3#who
|
%h3#who
|
||||||
%a.anchor{ href: "#who", aria_hidden: "true" }
|
%a.anchor{ href: "#who", aria_hidden: "true" }
|
||||||
لیست تغییرات به درد چه کسانی می‌خورد؟
|
لیست تغییرات به درد چه کسانی می‌خورد؟
|
||||||
|
|
||||||
%p
|
%p
|
||||||
مصرف‌کننده‌ها، توسعه‌دهنده‌ها، کاربران نهایی و در یک کلام مردم. مسلماً وقتی نرم‌افزاری بروزرسانی می‌شود، کاربران آن دوست دارند بدانند چرا و چطور این تغییرات اعمال شده است.
|
مصرف‌کننده‌ها، توسعه‌دهنده‌ها، کاربران نهایی و در یک کلام مردم.
|
||||||
|
|
||||||
|
%p
|
||||||
|
مسلماً وقتی نرم‌افزاری بروزرسانی می‌شود، کاربران آن دوست دارند بدانند چرا و چطور این تغییرات اعمال شده است.
|
||||||
|
|
||||||
.good-practices
|
.good-practices
|
||||||
%h3#how
|
%h3#how
|
||||||
%a.anchor{ href: "#how", aria_hidden: "true" }
|
%a.anchor{ href: "#how", aria_hidden: "true" }
|
||||||
چطور یک تاریخچهٔ تغییرات خوب بسازم؟
|
چطور یک تاریخچهٔ تغییرات خوب بسازیم؟
|
||||||
|
|
||||||
%h4#principles
|
%h4#principles
|
||||||
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
||||||
@ -56,13 +59,13 @@ pre {direction:ltr;text-align:left}
|
|||||||
|
|
||||||
%ul
|
%ul
|
||||||
%li
|
%li
|
||||||
تاریخچهٔ تغییرات <em>برای انسان</em>است، نه ماشین.
|
تاریخچهٔ تغییرات <em>برای انسان</em> است، نه ماشین.
|
||||||
%li
|
%li
|
||||||
برای هر نسخه از پروژه، مدخلی تعریف کنید.
|
برای هر نسخه از پروژه، یک مدخل جدید تعریف کنید.
|
||||||
%li
|
%li
|
||||||
تغییرات مشابه را دسته‌بندی کنید.
|
تغییرات مشابه را دسته‌بندی کنید.
|
||||||
%li
|
%li
|
||||||
نسخه‌ها و بخش‌های مختلف باید قابل لینک‌شدن باشند.
|
نسخه‌ها و بخش‌ها قابل لینک‌شدن باشند.
|
||||||
%li
|
%li
|
||||||
آخرین نسخه را در ابتدا قرار دهید.
|
آخرین نسخه را در ابتدا قرار دهید.
|
||||||
%li
|
%li
|
||||||
@ -82,7 +85,7 @@ pre {direction:ltr;text-align:left}
|
|||||||
برای تغییر در عملکردهای فعلی.
|
برای تغییر در عملکردهای فعلی.
|
||||||
%li
|
%li
|
||||||
%code Deprecated
|
%code Deprecated
|
||||||
برای قابلیت‌هایی که به‌زودی حذف می‌شود.
|
برای قابلیت‌هایی که حذف می‌شود.
|
||||||
%li
|
%li
|
||||||
%code Removed
|
%code Removed
|
||||||
برای قابلیت‌های حذف‌شده.
|
برای قابلیت‌های حذف‌شده.
|
||||||
@ -102,19 +105,21 @@ pre {direction:ltr;text-align:left}
|
|||||||
%p
|
%p
|
||||||
در بالای فایل تاریخچهٔ تغییرات، بخشی را تحت عنوان <code>Unreleased</code> برای دنبال‌کردن تغییرات پیش‌رو در نظر بگیرید.
|
در بالای فایل تاریخچهٔ تغییرات، بخشی را تحت عنوان <code>Unreleased</code> برای دنبال‌کردن تغییرات پیش‌رو در نظر بگیرید.
|
||||||
|
|
||||||
%p این کار دو هدف را دنبال می‌کند:
|
%p این کار دو فایده دارد:
|
||||||
|
|
||||||
%ul
|
%ul
|
||||||
%li
|
%li
|
||||||
افراد بتوانند پیش از انتشار یک نسخهٔ جدید، از تغییراتی که می‌توانند در نسخهٔ بعدی انتظار داشته باشند مطلع شوند.
|
اولاً کاربران می‌توانند پیش از انتشار یک نسخهٔ جدید، از تغییراتی که می‌توانند در نسخهٔ بعدی انتظار داشته باشند مطلع شوند.
|
||||||
%li
|
%li
|
||||||
هنگام انتشار بتوانید بخش <code>Unreleased</code> را به‌راحتی در قالب یک نسخهٔ جدید به بخش انتشاریافته‌ها منتقل کنید و دیگر لازم نباشد بروید ببینید چه تغییراتی ایجاد شده است.
|
دوماً هنگام انتشار نسخهٔ جدید، می‌توانید به‌راحتی بخش <code>Unreleased</code> را در قالب یک نسخهٔ جدید به بخش انتشاریافته‌ها منتقل کنید و دیگر لازم نباشد بروید ببینید چه تغییراتی ایجاد شده است.
|
||||||
|
|
||||||
.bad-practices
|
.bad-practices
|
||||||
%h3#bad-practices
|
%h3#bad-practices
|
||||||
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||||||
آیا تاریخچهٔ تغییرات می‌تواند بد نوشته شود؟
|
آیا تاریخچهٔ تغییرات می‌تواند بد نوشته شود؟
|
||||||
|
|
||||||
%p بله. در شرایط زیر.:
|
%p بله. در شرایط زیر.:
|
||||||
|
|
||||||
%h4#log-diffs
|
%h4#log-diffs
|
||||||
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||||||
استفاده از خروجی log diff به عنوان تاریخچهٔ تغییرات
|
استفاده از خروجی log diff به عنوان تاریخچهٔ تغییرات
|
||||||
@ -131,29 +136,28 @@ pre {direction:ltr;text-align:left}
|
|||||||
%h4#ignoring-deprecations
|
%h4#ignoring-deprecations
|
||||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||||
نادیده‌گرفتن چیزهای منسوخ‌شده
|
نادیده‌گرفتن چیزهای منسوخ‌شده
|
||||||
Ignoring Deprecations
|
|
||||||
%p
|
%p
|
||||||
وقتی مردم از یک نسخه به نسخهٔ دیگر به‌روزرسانی می‌کنند باید بدانند که چه موقع نسخهٔ جدید تغییرات ناسازگار به‌همراه دارد. یعنی مثلاً بعد از بروزرسانی یک کتابخانه که پروژهٔ شما به آن وابسته بوده، آیا بخش‌هایی از پروژه از کار می‌افتد یا نه. اگر بله، کدام بخش‌ها. پاسخ این سؤال کمک می‌کند تا توسعه‌دهنده‌ها، متناسب با نسخهٔ جدید، قسمت‌های منسوخ‌شده را جایگزین کرده و بعد از آن اقدام به بروزرسانی کنند.
|
وقتی کاربران از یک نسخه به نسخهٔ دیگر به‌روزرسانی می‌کنند، باید بدانند که چه موقع نسخهٔ جدید، تغییرات ناسازگار به‌همراه دارد؛ یعنی مثلاً بعد از بروزرسانی یک کتابخانه که پروژهٔ شما به آن وابسته بوده، آیا بخش‌هایی از پروژه از کار می‌افتد یا نه. اگر بله، کدام بخش‌ها. پاسخ به این سؤال کمک می‌کند توسعه‌دهنده‌ها متناسب با نسخهٔ جدید، قسمت‌های منسوخ‌شده را جایگزین کرده و بعد از آن اقدام به بروزرسانی کنند.
|
||||||
|
|
||||||
%h4#confusing-dates
|
%h4#confusing-dates
|
||||||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||||
تاریخ‌های گیج‌کننده
|
تاریخ‌های گیج‌کننده
|
||||||
|
|
||||||
%p
|
%p
|
||||||
در هر نقطه‌ای از دنیا شکل نمایش تاریخ متفاوت است؛ بنابراین پیداکردن یک قالب نمایش همه‌فهم برای کل مردم دنیا کار دشواری است. مزیت استفاده از قالب‌هایی مثل <code>2017-07-17</code> این است که در آن ترتیب بزرگترین به کوچکترین واحدها یعنی سال، ماه و روز رعایت شده است. این باعث می‌شود که برخلاف برخی از قالب‌ها که در آن جای ماه و روز عوض شده، درک تاریخ دچار ابهام نشود. با درنظرگرفتن این دلایل واین واقعیت که این فرمت یک #{link_to "استاندارد ایزو", data.links.isodate} است، این قالب را برای مدخل‌های تاریخچهٔ تغییرات در نظر گرفته‌ایم.
|
در هر نقطه‌ای از دنیا شکل نمایش تاریخ متفاوت است؛ بنابراین پیداکردن یک قالب نمایش همه‌فهم برای کل مردم دنیا کار دشواری است. مزیت استفاده از قالب‌هایی مثل <code>17-07-2017</code> این است که در آن ترتیب بزرگترین به کوچکترین واحدها یعنی سال، ماه و روز رعایت شده است. این باعث می‌شود که برخلاف برخی از قالب‌ها که در آن جای ماه و روز عوض شده، درک تاریخ دچار ابهام نشود. با درنظرگرفتن این دلایل و این واقعیت که این فرمت، یک #{link_to "استاندارد ایزو", data.links.isodate} است، این قالب را برای مدخل‌های تاریخچهٔ تغییرات در نظر گرفته‌ایم.
|
||||||
|
|
||||||
|
|
||||||
%h4#inconsistent-changes
|
%h4#inconsistent-changes
|
||||||
%a.anchor{ href: "#inconsistent-changes", aria_hidden: "true" }
|
%a.anchor{ href: "#inconsistent-changes", aria_hidden: "true" }
|
||||||
ناهمگونی ثبت تغییرات
|
ناهمگونی ثبت تغییرات
|
||||||
Inconsistent Changes
|
|
||||||
%p
|
%p
|
||||||
تاریخچهٔ تغییراتی که فقط شامل برخی از تغییرات است می‌تواند به اندازهٔ نبود تاریخچهٔ تغییرات خطرناک باشد. با اینکه لزومی به ثبت همهٔ تغییرات مثلاً حذف یک فاصلهٔ خالی نیست، باید هر تغییر مهمی را در تاریخچهٔ تغییرات ثبت کرد. نایکدستی در ثبت تغییرات ممکن است اعتماد کاربران را به تاریخچهٔ تغییرات به عنوان یگانه مرجع مشاهدهٔ تغییرات سلب کند. یک تاریخچهٔ تغییرات خوب باید به‌طور منظم بروزرسانی شود.
|
تاریخچهٔ تغییراتی که فقط شامل برخی از تغییرات است می‌تواند به اندازهٔ نبود تاریخچهٔ تغییرات خطرناک باشد. با اینکه لزومی به ثبت همهٔ تغییرات مثلاً حذف یک فاصلهٔ خالی نیست، باید هر تغییر مهمی را در تاریخچهٔ تغییرات ثبت کرد. نایکدستی در ثبت تغییرات ممکن است اعتماد کاربران را به تاریخچهٔ تغییرات به عنوان یگانه مرجع مشاهدهٔ تغییرات سلب کند. یک تاریخچهٔ تغییرات خوب باید به‌طور منظم بروزرسانی شود.
|
||||||
|
|
||||||
%aside
|
%aside
|
||||||
اگر فکر می‌کنید جای موارد بیشتری در این لیست خالی است با
|
اگر فکر می‌کنید جای موارد بیشتری در این لیست خالی است با
|
||||||
= link_to "ارسال issue", data.links.issue
|
= link_to "ارسال ایشو", data.links.issue
|
||||||
یا ارسال Pull request به من کمک کنید.
|
یا ارسال پول‌ریکوئست به من کمک کنید.
|
||||||
|
|
||||||
.frequently-asked-questions
|
.frequently-asked-questions
|
||||||
%h3#frequently-asked-questions
|
%h3#frequently-asked-questions
|
||||||
@ -164,8 +168,8 @@ pre {direction:ltr;text-align:left}
|
|||||||
آیا فرمت استانداردی برای تاریخچهٔ تغییرات وجود دارد؟
|
آیا فرمت استانداردی برای تاریخچهٔ تغییرات وجود دارد؟
|
||||||
|
|
||||||
%p
|
%p
|
||||||
حقیتاً نه. یک "راهنمای" #{link_to "راهنمای شیوه ثبت تاریخچهٔ تغییرات GNU", data.links.gnustyle},
|
حقیتاً نه. یک "راهنمای" #{link_to "راهنمای شیوه ثبت تاریخچهٔ تغییرات GNU", data.links.gnustyle}
|
||||||
و یک #{link_to "فایل دو پاراگرافیِ بلند GNU NEWS", data.links.gnunews}
|
و یک #{link_to "فایل دو پاراگرافی بلندِ GNU NEWS", data.links.gnunews}
|
||||||
وجود دارد که متأسفانه هردویشان نارسا و ناکافی هستند.
|
وجود دارد که متأسفانه هردویشان نارسا و ناکافی هستند.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
@ -186,9 +190,6 @@ pre {direction:ltr;text-align:left}
|
|||||||
نام این فایل را <code>CHANGELOG.md</code> بگذارید. بعضی پروژه‌ها از
|
نام این فایل را <code>CHANGELOG.md</code> بگذارید. بعضی پروژه‌ها از
|
||||||
<code>HISTORY</code>, <code>NEWS</code> یا <code>RELEASES</code> استفاده می‌کنند.
|
<code>HISTORY</code>, <code>NEWS</code> یا <code>RELEASES</code> استفاده می‌کنند.
|
||||||
|
|
||||||
%p
|
|
||||||
در حالی که ساده است فکر کنیم که اسم فایل تاریخچهٔ تغییرات اهمیتی ندارد، چرا یافتن تغییرات مهم را برای کاربران نهایی سخت کنیم؟
|
|
||||||
|
|
||||||
%h4#github-releases
|
%h4#github-releases
|
||||||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||||||
چرا از ریلیزهای گیت‌هاب استفاده نکنیم؟
|
چرا از ریلیزهای گیت‌هاب استفاده نکنیم؟
|
||||||
@ -196,7 +197,7 @@ pre {direction:ltr;text-align:left}
|
|||||||
ابتکار خوبی است. در هنگام انتشار #{link_to "Release", data.links.github_releases}ها می‌توانید به جای عرضهٔ یک نسخهٔ ساده (مثلاً یک برچسب خالی با نام <code>v1.0.0</code>)، لیست تغییرات آن نسخه را در قالب یک یادداشت، به آن برچسب ضمیمه کنید.
|
ابتکار خوبی است. در هنگام انتشار #{link_to "Release", data.links.github_releases}ها می‌توانید به جای عرضهٔ یک نسخهٔ ساده (مثلاً یک برچسب خالی با نام <code>v1.0.0</code>)، لیست تغییرات آن نسخه را در قالب یک یادداشت، به آن برچسب ضمیمه کنید.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
اما نکته این است که تاریخچهٔ تغییراتی که در هر ریلیز گیت‌هاب منتشر می‌کنید فقط در خودِ گیت‌هاب قابل استفاده است و به‌راحتی نمی‌توانید آن را به جای دیگری منتقل کنید. شاید بتوانید بسیار شبیهش کنید به نسخهٔ پیشنهادی این سند ولی کار زحمت‌داری است.
|
اما نکته این است که تاریخچهٔ تغییراتی که در هر ریلیز گیت‌هاب منتشر می‌کنید فقط در خودِ گیت‌هاب قابل استفاده است و به‌راحتی نمی‌توانید آن را به جای دیگری منتقل کنید. شاید بتوانید بسیار شبیه نسخهٔ پیشنهادی این سند کنید ولی کار زحمت‌داری است.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
مشاهدهٔ تغییرات پروژه در لابه‌لای ریلیزهای گیت‌هاب، به اندازهٔ دیدن همهٔ تغییرات در یک فایل، آسان و دلچسب نیست. فایل‌هایی با حرف بزرگ،
|
مشاهدهٔ تغییرات پروژه در لابه‌لای ریلیزهای گیت‌هاب، به اندازهٔ دیدن همهٔ تغییرات در یک فایل، آسان و دلچسب نیست. فایل‌هایی با حرف بزرگ،
|
||||||
@ -234,15 +235,15 @@ pre {direction:ltr;text-align:left}
|
|||||||
قطعاً. معمولاً همیشه دلیل خوبی برای بهبود تاریخچهٔ تغییرات وجود دارد. من معمولاً به‌طور منظم، فایل تاریخچهٔ تغییرات را برای پروژه‌های متن‌بازی که این کار را انجام نداده‌اند می‌نویسم و تغییرات را به صورت یک پول‌ریکوئست ارائه می‌دهم.
|
قطعاً. معمولاً همیشه دلیل خوبی برای بهبود تاریخچهٔ تغییرات وجود دارد. من معمولاً به‌طور منظم، فایل تاریخچهٔ تغییرات را برای پروژه‌های متن‌بازی که این کار را انجام نداده‌اند می‌نویسم و تغییرات را به صورت یک پول‌ریکوئست ارائه می‌دهم.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
گاهی نیز ممکن است یادتان رفته باشد که تغییرات ناسازگار یک نسخه را ثبت کنید. در چنین شرایطی نیز واضح است که باید تاریخچهٔ تغییرات را بروزرسانی کنید.
|
گاهی نیز ممکن است یادتان رفته باشد که تغییرات ناسازگارِ یک نسخه را ثبت کنید. در چنین شرایطی نیز واضح است که باید تاریخچهٔ تغییرات را بروزرسانی کنید.
|
||||||
|
|
||||||
|
|
||||||
%h4#contribute
|
%h4#contribute
|
||||||
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
||||||
چطور می‌توانم مشارکت کنیم؟
|
چطور می‌توانم مشارکت کنم؟
|
||||||
|
|
||||||
%p
|
%p
|
||||||
این سند <strong>کامل و بی‌نقص</strong> نیست; صرفاً نظرات به‌دقت بررسی‌شده‌ای است که با اطلاعات و مثال‌هایی در اینجا قرار داده‌ام.
|
این سند، <strong>کامل و بی‌نقص</strong> نیست؛ صرفاً نظرات به‌دقت بررسی‌شده‌ای است که همراه اطلاعات و مثال‌هایی، در اینجا قرار داده‌ام.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
این به خاطر آن است که می‌خواهم جامعهٔ ما توسعه‌دهنده‌ها به یک اتفاق‌نظر برسد. من معتقدم بحث‌وگفتگو به‌اندازهٔ نتیجه مهم است.
|
این به خاطر آن است که می‌خواهم جامعهٔ ما توسعه‌دهنده‌ها به یک اتفاق‌نظر برسد. من معتقدم بحث‌وگفتگو به‌اندازهٔ نتیجه مهم است.
|
||||||
Loading…
x
Reference in New Issue
Block a user