From ee5c255e0378556053c06a3aaf2514adae7d2dd4 Mon Sep 17 00:00:00 2001 From: Hamed Date: Mon, 29 Oct 2018 22:27:37 +0330 Subject: [PATCH] add persian translation --- config.rb | 3 + source/fa-IR/0.3.0/index.html.haml | 182 ++++++++++++++++++ source/fa-IR/1.0.0/index.html.haml | 285 +++++++++++++++++++++++++++++ 3 files changed, 470 insertions(+) create mode 100644 source/fa-IR/0.3.0/index.html.haml create mode 100644 source/fa-IR/1.0.0/index.html.haml diff --git a/config.rb b/config.rb index f10523e..472ad7f 100644 --- a/config.rb +++ b/config.rb @@ -95,6 +95,9 @@ $languages = { }, "ko" => { name: "한국어" + }, + "fa-IR" => { + name: "فارسی" } } diff --git a/source/fa-IR/0.3.0/index.html.haml b/source/fa-IR/0.3.0/index.html.haml new file mode 100644 index 0000000..0f6ef0d --- /dev/null +++ b/source/fa-IR/0.3.0/index.html.haml @@ -0,0 +1,182 @@ +--- +description: Keep a Changelog +title: Keep a Changelog +language: en +version: 0.3.0 +--- + +:markdown + # Keep a CHANGELOG + + ## Don’t let your friends dump git logs into CHANGELOGs™ + + Version **#{current_page.metadata[:page][:version]}** + + ### What’s a change log? + A change log is a file which contains a curated, chronologically ordered + list of notable changes for each version of a project. + + 
#{File.read("CHANGELOG.md")}
+ + ### What’s the point of a change log? + To make it easier for users and contributors to see precisely what + notable changes have been made between each release (or version) of the project. + + ### Why should I care? + Because software tools are for people. If you don’t care, why are + you contributing to open source? Surely, there must be a kernel (ha!) + of care somewhere in that lovely little brain of yours. + + I [talked with Adam Stacoviak and Jerod Santo on The Changelog][thechangelog] + (fitting, right?) podcast about why maintainers and + contributors should care, and the motivations behind this project. + If you can spare the time (1:06), it’s a good listen. + + ### What makes a good change log? + I’m glad you asked. + + A good change log sticks to these principles: + + - It’s made for humans, not machines, so legibility is crucial. + - Easy to link to any section (hence Markdown over plain text). + - One sub-section per version. + - List releases in reverse-chronological order (newest on top). + - Write all dates in `YYYY-MM-DD` format. (Example: `2012-06-02` for `June 2nd, 2012`.) It’s international, [sensible](https://xkcd.com/1179/), and language-independent. + - Explicitly mention whether the project follows [Semantic Versioning][semver]. + - Each version should: + - List its release date in the above format. + - Group changes to describe their impact on the project, as follows: + - `Added` for new features. + - `Changed` for changes in existing functionality. + - `Deprecated` for once-stable features removed in upcoming releases. + - `Removed` for deprecated features removed in this release. + - `Fixed` for any bug fixes. + - `Security` to invite users to upgrade in case of vulnerabilities. + + ### How can I minimize the effort required? + Always have an `"Unreleased"` section at the top for keeping track of any + changes. + + This serves two purposes: + + - People can see what changes they might expect in upcoming releases + - At release time, you just have to change `"Unreleased"` to the version number + and add a new `"Unreleased"` header at the top. + + ### What makes unicorns cry? + Alright…let’s get into it. + + - **Dumping a diff of commit logs.** Just don’t do that, you’re helping nobody. + - **Not emphasizing deprecations.** When people upgrade from one version to + another, it should be painfully clear when something will break. + - **Dates in region-specific formats.** In the U.S., people put the month first + ("06-02-2012" for June 2nd, 2012, which makes *no* sense), while many people + in the rest of the world write a robotic-looking "2 June 2012", yet pronounce + it differently. "2012-06-02" works logically from largest to smallest, doesn't + overlap in ambiguous ways with other date formats, and is an + [ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Thus, it + is the recommended date format for change logs. + + There’s more. Help me collect those unicorn tears by + [opening an issue][issues] + or a pull request. + + ### Is there a standard change log format? + Sadly, no. Calm down. I know you're furiously rushing to find that link + to the GNU change log style guide, or the two-paragraph GNU NEWS file + "guideline". The GNU style guide is a nice start but it is sadly naive. + There's nothing wrong with being naive but when people need + guidance it's rarely very helpful. Especially when there are many + situations and edge cases to deal with. + + This project [contains what I hope will become a better CHANGELOG file convention][CHANGELOG]. + I don't think the status quo is good enough, and I think that as a community we + can come up with better conventions if we try to extract good practices from + real software projects. Please take a look around and remember that + [discussions and suggestions for improvements are welcome][issues]! + + ### What should the change log file be named? + Well, if you can’t tell from the example above, `CHANGELOG.md` is the + best convention so far. + + Some projects also use `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, + `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc. + + It’s a mess. All these names only makes it harder for people to find it. + + ### Why can’t people just use a `git log` diff? + Because log diffs are full of noise — by nature. They could not make a suitable + change log even in a hypothetical project run by perfect humans who never make + typos, never forget to commit new files, never miss any part of a refactoring. + The purpose of a commit is to document one atomic step in the process by which + the code evolves from one state to another. The purpose of a change log is to + document the noteworthy differences between these states. + + As is the difference between good comments and the code itself, + so is the difference between a change log and the commit log: + one describes the *why*, the other the how. + + ### Can change logs be automatically parsed? + It’s difficult, because people follow wildly different formats and file names. + + [Vandamme][vandamme] is a Ruby gem + created by the [Gemnasium][gemnasium] team and which parses + many (but not all) open source project change logs. + + ### Why do you alternate between spelling it "CHANGELOG" and "change log"? + "CHANGELOG" is the name of the file itself. It's a bit shouty but it's a + historical convention followed by many open source projects. Other + examples of similar files include [`README`][README], [`LICENSE`][LICENSE], + and [`CONTRIBUTING`][CONTRIBUTING]. + + The uppercase naming (which in old operating systems made these files stick + to the top) is used to draw attention to them. Since they're important + metadata about the project, they could be useful to anyone intending to use + or contribute to it, much like [open source project badges][shields]. + + When I refer to a "change log", I'm talking about the function of this + file: to log changes. + + ### What about yanked releases? + Yanked releases are versions that had to be pulled because of a serious + bug or security issue. Often these versions don't even appear in change + logs. They should. This is how you should display them: + + `## 0.0.5 - 2014-12-13 [YANKED]` + + The `[YANKED]` tag is loud for a reason. It's important for people to + notice it. Since it's surrounded by brackets it's also easier to parse + programmatically. + + ### Should you ever rewrite a change log? + Sure. There are always good reasons to improve a change log. I regularly open + pull requests to add missing releases to open source projects with unmaintained + change logs. + + It's also possible you may discover that you forgot to address a breaking change + in the notes for a version. It's obviously important for you to update your + change log in this case. + + ### How can I contribute? + This document is not the **truth**; it’s my carefully considered + opinion, along with information and examples I gathered. + Although I provide an actual [CHANGELOG][] on [the GitHub repo][gh], + I have purposefully not created a proper *release* or clear list of rules + to follow (as [SemVer.org][semver] does, for instance). + + This is because I want our community to reach a consensus. I believe the + discussion is as important as the end result. + + So please [**pitch in**][gh]. + + [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md + [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md + [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE + [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.md + [gemnasium]: https://gemnasium.com/ + [gh]: https://github.com/olivierlacan/keep-a-changelog + [issues]: https://github.com/olivierlacan/keep-a-changelog/issues + [semver]: https://semver.org/ + [shields]: https://shields.io/ + [thechangelog]: https://changelog.com/podcast/127 + [vandamme]: https://github.com/tech-angels/vandamme/ diff --git a/source/fa-IR/1.0.0/index.html.haml b/source/fa-IR/1.0.0/index.html.haml new file mode 100644 index 0000000..352c774 --- /dev/null +++ b/source/fa-IR/1.0.0/index.html.haml @@ -0,0 +1,285 @@ +--- +description: لاگ تغییرات را نگه دارید +title: لاگ تغییرات را نگه دارید +language: fa-IR +version: 1.0.0 +--- + +- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md" +- gemnasium = "https://gemnasium.com/" +- gh = "https://github.com/olivierlacan/keep-a-changelog" +- issues = "https://github.com/olivierlacan/keep-a-changelog/issues" +- semver = "https://semver.org/" +- shields = "https://shields.io/" +- thechangelog = "https://changelog.com/podcast/127" +- vandamme = "https://github.com/tech-angels/vandamme/" +- iso = "http://www.iso.org/iso/home/standards/iso8601.htm" +- ghr = "https://help.github.com/articles/creating-releases/" +- gnustyle = "https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs" +- gnunews = "https://www.gnu.org/prep/standards/html_node/NEWS-File.html#NEWS-File" + + + + + +.header + .title + %h1 لاگ تغییرات را نگه دارید + %h2 اجازه ندهید دوستانتان، لاگ git را در لاگ تغییرات خالی کنند + + = link_to changelog do + Version + %strong= current_page.metadata[:page][:version] + + %pre.changelog= 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 + مردم. خواه مصرف کننده یا توسعه‌دهنده، کاربران نهایی نرم‌افزار انسان‌هایی هستند که به آنچه در نرم‌افزار هست اهمیت می‌دهند. وقتی نرم‌افزار تغییر می‌کنند،‌مردم می‌خواهند بدانند چرا و چگونه. + +.good-practices + %h3#how + %a.anchor{ href: "#how", aria_hidden: "true" } + چطور یک لاگ تغییرات خوب بسازم؟ + + %h4#principles + %a.anchor{ href: "#principles", aria_hidden: "true" } + اصول راهنما + + %ul + %li + لاگ تغییرات برای انسان‌هاهستند، نه ماشین‌ها. + %li + برای هر کدام از نسخه‌ها باید یک مدخل وجود داشته باشد + %li + انواع مشابه تغییرات باید دسته‌بندی شوند. + %li + نسخه‌ها و بخش‌ها باید پیوند پذیر باشند. + %li + آخرین نسخه اول می‌آید. + %li + تاریخ عرضه هر کدام از نسخه‌ها، نمایش داده می‌شود. + %li + به اینکه #{link_to "نسخه‌بندی معنایی", 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 + بخش Unreleased را برای دنبال کردن تغییرات پیش رو به بالا اضافه کنید + + %p این کار دو هدف را دنبال می‌کند: + + %ul + %li + افراد بتوانند ببینند چه تغییراتی را می‌توانند در عرضه‌های بعدی انتظار داشته باشند. + %li + در زمان عرضه، می‌توانید بخش Unreleased را به بخش release منتقل کنید. + +.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" } + تفاوت (diff) لاگ کامیت‌ها + + %p + استفاده از لاگ تفاوت کامیت‌های به عنوان لازم تغییرات ایده بدی است: چون پر از پازایت هستند. پارازیت‌هایی مثل کامیت‌های ادغام، کامیت‌هایی با عناوین مبهم، تغییر مستندات و ... + + %p + هدف کامیت مستند کردن یک گام در سیر تکاملی سورس کد است. بعضی پروژه‌ها، کامیت‌ها را تمیز می‌کنند و بعضی این کار را نمی‌کنند. + + %p + هدف یک مدخل لاگ تغییرات مستند کردن تفاوت‌های مهم، معمولاً از میان چندین کامیت، برای انتقال شفاف این تغییرات به کاربران نهایی است. + + %h4#ignoring-deprecations + %a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" } + نادیده گرفتن منسوخ شده‌ها + Ignoring Deprecations + + %p + وقتی مردم از یک نسخه به نسخه دیگری به روز رسانی می‌کنند، باید کاملاً شفاف باشد که چه موقع چیزی می‌شکند. + باید ممکن باشد که به نسخه‌ای که منسوخ شده‌ها (deprecations) را فهرست کند، آنچه منسوخ شده را حذف کند و سپس به نسخه‌ای به روز رسانی کرد که منسوخ شده‌ها را برداشته است. + + %p + حتی اگر کار دیگری نمی‌کنید، منسوخ شده‌ها، امکانات حذف شده یا هر نوع تغییرات منجر به شکست را در لاگ تغییرات فهرست کنید + + + %h4#confusing-dates + %a.anchor{ href: "#confusing-dates", aria_hidden: "true" } + تاریخ‌های گیج کننده + + %p + فرمت‌های تاریخ محلی در سراسر جهان متفاوت است و معمولاً مشکل است که یک فرمت انسان پسند تاریخ پیدا کنیم که همه درکش کنند. + مزیت استفاده از فرمت‌هایی مثل + 2017-07-17 + این است که شما ترتیب بزرگترین به کوچگترین واحدها را رعایت می کنید: سال، ماه و روز. + این فرمت همچنین بر خلاف بعضی فرمت‌های محلی که که جای اعداد ماه و روز را عوضی می‌کنند، با فرمت‌های دو پهلوی تاریخ همپوشانی ندارد، + این دلایل، و این واقعیت که این فرمت یک + #{link_to "استاندارد ایزو", iso} است، دلیل پیشنهاد شدن این فرمت برای مدخل‌های لاگ تغییرات است. + + %aside + موارد بیشتری وجود دارد. با + = link_to "ارسال issue", issues + یا ارسال Pull request به من کمک کنید این ضد الگوها را جمع‌آوری کنم + +.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", gnustyle}, + یا #{link_to "فایل دو پاراگرافی GNU NEWS", gnunews} + وجود دارد. این نارسا و ناکافی هستند. + + %p + این پروژه قصد دارد + = link_to "یک قرارداد بهتر برای لاگ تغییرات باشد", changelog + که از مشاهده و جمع آوری شیوه‌های خوب جامعه متن باز آمده است + + %p + از نقد سالم، بحث و گفتگو و پیشنهادات برای بهبود + = link_to "استقبال می‌کنیم.", issues + + + %h4#filename + %a.anchor{ href: "#filename", aria_hidden: "true" } + فایل لاگ تغییرات باید چه نامیده شود؟ + + %p + نامش را CHANGELOG.md بگذارید. بعضی پروژه‌ها از + HISTORY, NEWS یا RELEASES استفاده می‌کنند. + + %p + در حالی گه ساده است فکر کنیم که اسم فایل لاگ تغییرات اهمیتی ندارد، چرا پیدا کردن تغییرات مهم را برای کاربران نهایی سخت کنیم؟ + + %h4#github-releases + %a.anchor{ href: "#github-releases", aria_hidden: "true" } + Release های گیت‌هاب چطور؟ + + %p + ابتکار فوق‌العاده‌ای است. #{link_to "Release", ghr} ها می‌توانند برای تبدیل برچسب‌های ساده گیت + (مثلاً برچسبی به نام v1.0.0) + به یادداشت عرضه (Release Note) غنی استفاده شوند. یا با اضافه کردن دستی یادداشت عرضه یا با گرفتن پیام‌های حاشیه‌نویسی شده برچسب گیت و تبدیلشان به یادداشت. + + %p + Release های گیت‌هاب لاگ‌های تغییرات غیرقابل حمل که فقط در گیت‌هاب به کاربران نمایش داده می‌شوند را ایجاد می‌کنند. + شبیه کردن‌شان به فرمت پیشنهادی این سند ممکن است اما تلاش بیشتری می‌طلبد. + + %p + نسخه فعلی release های گیت‌هاب نسبت به فایل‌های با حرف بزرگ دیگر + (README, CONTRIBUTING, غیره.) + کمتر توسط کاربران پیدا می‌شوند + مشکل کوچک دیگر این است که رابط کاربری فعلی امکان ایجاد پیوند به لاگ کامیت‌ها را بین هر عرضه نمی‌دهد. + + %h4#automatic + %a.anchor{ href: "#automatic", aria_hidden: "true" } + آیا لاگ تغییرات را می‌توان به صورت اتوماتیک، پارس کرد؟ + + %p + مشکل است، چون افراد فرمت‌ها و فایل‌ها خیلی متفاوتی را استفاده می‌کنند. + + %p + #{link_to "Vandamme", vandamme} یک روبی gem ساخته شده توسط تیم + #{link_to "Gemnasium", gemnasium} است که اغلب (اما نه همه) لاگ تغییرات پروژه‌های متن باز را پارس می‌کند. + + + %h4#yanked + %a.anchor{ href: "#yanked", aria_hidden: "true" } + عرضه‌های yanked چطور؟ + + %p + عرضه‌های Yanked نسخه‌هایی هستند که به خاطر باگ جدی یا مشکل امنیتی باید گرفته شوند. + معمولاً این عرضه‌ها در لاگ تغییرات دیده نمی‌شوند، اما باید اضافه شوند. این روشی است که باید آن‌ها را نمایش دهید: + %p ## 0.0.5 - 2014-12-13 [YANKED] + + %p + برچسب [YANKED] به دلیلی پر سر و صداست. + مهم است که مردم به آن توجه کنند. چون با کروشه محصور شده پارس کردن نرم‌افزاری آن‌ها هم ساده‌تر است. + + + %h4#rewrite + %a.anchor{ href: "#rewrite", aria_hidden: "true" } + آیا هرگز باید یک لاگ تغییرات را بازنویسی کنید؟ + + %p + حتماً. همیشه دلیل خوبی برای بهبود لاگ تغییرات وجود دارد. من معمولاً برای اضافه کردن عرضه‌های فراموش شده به پروژه‌های متن باز که لاگ تغییرات را نگهداری نمی‌کنند Pull Request ایجاد می‌کنم. + + %p + ممکن است متوجه شوید گه فراموش کردید تغییرات منجر به شکست را در یادداشت‌‌های یک نسخه بنویسید. به طور مشخص در چنین شرایطی مهم است که لاگ تغییرات را به روز رسانی کنید. + + + %h4#contribute + %a.anchor{ href: "#contribute", aria_hidden: "true" } + چطور می‌توانم مشارکت کنیم؟ + + %p + این سند حقیقت نیست; این نظر به دقت در نظر گرفته شده من به همراه اطلاعات و مثال‌هایی است که من گردآوری کردم + + %p + این سند برای آن است که جامعه نرم‌افزاری به اجماع برسند. معتقدم بحث و گفتگو به اندازه نتیجه نهایی مهم است + + %p + بنابراین لطفاً #{link_to "دست به کار شوید", gh}. + +.press + %h3 گفتگو + %p + به #{link_to "پادکست Changelog", thechangelog} رفتم تا درباره اینکه چرا متصدیان نگهداری و مشارکت‌کنندگان پروژه‌ها باید به لاگ تغییرات اهمیت بدهند و همچنین انگیزه‌های پشت این پروژه صحبت کنم.