تاریخچهٔ تغییرات را نگه دارید

خروجی git log را به اسم تاریخچهٔ تغییرات پروژه منتشر نکنید.

Version 1.0.0
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- v1.1 Brazilian Portuguese translation.
- v1.1 German Translation
- v1.1 Spanish translation.
- v1.1 Italian translation.
- v1.1 Polish translation.
- v1.1 Ukrainian translation.

### Changed

- Use frontmatter title & description in each language version template
- Replace broken OpenGraph image with an appropriately-sized Keep a Changelog 
  image that will render properly (although in English for all languages)
- Fix OpenGraph title & description for all languages so the title and 
description when links are shared are language-appropriate

### Removed

- Trademark sign previously shown after the project description in version 
0.3.0

## [1.1.1] - 2023-03-05

### Added

- Arabic translation (#444).
- v1.1 French translation.
- v1.1 Dutch translation (#371).
- v1.1 Russian translation (#410).
- v1.1 Japanese translation (#363).
- v1.1 Norwegian Bokmål translation (#383).
- v1.1 "Inconsistent Changes" Turkish translation (#347).
- Default to most recent versions available for each languages.
- Display count of available translations (26 to date!).
- Centralize all links into `/data/links.json` so they can be updated easily.

### Fixed

- Improve French translation (#377).
- Improve id-ID translation (#416).
- Improve Persian translation (#457).
- Improve Russian translation (#408).
- Improve Swedish title (#419).
- Improve zh-CN translation (#359).
- Improve French translation (#357).
- Improve zh-TW translation (#360, #355).
- Improve Spanish (es-ES) transltion (#362).
- Foldout menu in Dutch translation (#371).
- Missing periods at the end of each change (#451).
- Fix missing logo in 1.1 pages.
- Display notice when translation isn't for most recent version.
- Various broken links, page versions, and indentations.

### Changed

- Upgrade dependencies: Ruby 3.2.1, Middleman, etc.

### Removed

- Unused normalize.css file.
- Identical links assigned in each translation file.
- Duplicate index file for the english version.

## [1.1.0] - 2019-02-15

### Added

- Danish translation (#297).
- Georgian translation from (#337).
- Changelog inconsistency section in Bad Practices.

### Fixed

- Italian translation (#332).
- Indonesian translation (#336).

## [1.0.0] - 2017-06-20

### Added

- New visual identity by [@tylerfortune8](https://github.com/tylerfortune8).
- Version navigation.
- Links to latest released version in previous versions.
- "Why keep a changelog?" section.
- "Who needs a changelog?" section.
- "How do I make a changelog?" section.
- "Frequently Asked Questions" section.
- New "Guiding Principles" sub-section to "How do I make a changelog?".
- Simplified and Traditional Chinese translations from [@tianshuo](https://github.com/tianshuo).
- German translation from [@mpbzh](https://github.com/mpbzh) & [@Art4](https://github.com/Art4).
- Italian translation from [@azkidenz](https://github.com/azkidenz).
- Swedish translation from [@magol](https://github.com/magol).
- Turkish translation from [@emreerkan](https://github.com/emreerkan).
- French translation from [@zapashcanon](https://github.com/zapashcanon).
- Brazilian Portuguese translation from [@Webysther](https://github.com/Webysther).
- Polish translation from [@amielucha](https://github.com/amielucha) & [@m-aciek](https://github.com/m-aciek).
- Russian translation from [@aishek](https://github.com/aishek).
- Czech translation from [@h4vry](https://github.com/h4vry).
- Slovak translation from [@jkostolansky](https://github.com/jkostolansky).
- Korean translation from [@pierceh89](https://github.com/pierceh89).
- Croatian translation from [@porx](https://github.com/porx).
- Persian translation from [@Hameds](https://github.com/Hameds).
- Ukrainian translation from [@osadchyi-s](https://github.com/osadchyi-s).

### Changed

- Start using "changelog" over "change log" since it's the common usage.
- Start versioning based on the current English version at 0.3.0 to help
  translation authors keep things up-to-date.
- Rewrite "What makes unicorns cry?" section.
- Rewrite "Ignoring Deprecations" sub-section to clarify the ideal
  scenario.
- Improve "Commit log diffs" sub-section to further argument against
  them.
- Merge "Why can’t people just use a git log diff?" with "Commit log
  diffs".
- Fix typos in Simplified Chinese and Traditional Chinese translations.
- Fix typos in Brazilian Portuguese translation.
- Fix typos in Turkish translation.
- Fix typos in Czech translation.
- Fix typos in Swedish translation.
- Improve phrasing in French translation.
- Fix phrasing and spelling in German translation.

### Removed

- Section about "changelog" vs "CHANGELOG".

## [0.3.0] - 2015-12-03

### Added

- RU translation from [@aishek](https://github.com/aishek).
- pt-BR translation from [@tallesl](https://github.com/tallesl).
- es-ES translation from [@ZeliosAriex](https://github.com/ZeliosAriex).

## [0.2.0] - 2015-10-06

### Changed

- Remove exclusionary mentions of "open source" since this project can
  benefit both "open" and "closed" source projects equally.

## [0.1.0] - 2015-10-06

### Added

- Answer "Should you ever rewrite a change log?".

### Changed

- Improve argument against commit logs.
- Start following [SemVer](https://semver.org) properly.

## [0.0.8] - 2015-02-17

### Changed

- Update year to match in every README example.
- Reluctantly stop making fun of Brits only, since most of the world
  writes dates in a strange way.

### Fixed

- Fix typos in recent README changes.
- Update outdated unreleased diff link.

## [0.0.7] - 2015-02-16

### Added

- Link, and make it obvious that date format is ISO 8601.

### Changed

- Clarified the section on "Is there a standard change log format?".

### Fixed

- Fix Markdown links to tag comparison URL with footnote-style links.

## [0.0.6] - 2014-12-12

### Added

- README section on "yanked" releases.

## [0.0.5] - 2014-08-09

### Added

- Markdown links to version tags on release headings.
- Unreleased section to gather unreleased changes and encourage note
  keeping prior to releases.

## [0.0.4] - 2014-08-09

### Added

- Better explanation of the difference between the file ("CHANGELOG")
  and its function "the change log".

### Changed

- Refer to a "change log" instead of a "CHANGELOG" throughout the site
  to differentiate between the file and the purpose of the file — the
  logging of changes.

### Removed

- Remove empty sections from CHANGELOG, they occupy too much space and
  create too much noise in the file. People will have to assume that the
  missing sections were intentionally left out because they contained no
  notable changes.

## [0.0.3] - 2014-08-09

### Added

- "Why should I care?" section mentioning The Changelog podcast.

## [0.0.2] - 2014-07-10

### Added

- Explanation of the recommended reverse chronological release ordering.

## [0.0.1] - 2014-05-31

### Added

- This CHANGELOG file to hopefully serve as an evolving example of a
  standardized open source project CHANGELOG.
- CNAME file to enable GitHub Pages custom domain.
- README now contains answers to common questions about CHANGELOGs.
- Good examples and basic guidelines, including proper date formatting.
- Counter-examples: "What makes unicorns cry?".

[unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.1...HEAD
[1.1.1]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.0...v1.1.1
[1.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0
[0.3.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.8...v0.1.0
[0.0.8]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.7...v0.0.8
[0.0.7]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.6...v0.0.7
[0.0.6]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.5...v0.0.6
[0.0.5]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.4...v0.0.5
[0.0.4]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.3...v0.0.4
[0.0.3]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.2...v0.0.3
[0.0.2]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.1...v0.0.2
[0.0.1]: https://github.com/olivierlacan/keep-a-changelog/releases/tag/v0.0.1

تاریخچهٔ تغییرات چیست؟

تاریخچهٔ تغییرات، فایلی شامل تغییرات عمدهٔ هر نسخه از پروژه به‌ترتیبِ زمان انتشار هر نسخه است.

چرا باید لیست تغییرات را نگه‌داری کنیم؟

برای اینکه کاربران بدانند در هر نسخه از پروژه چه اتفاقااتی افتاده است.

لیست تغییرات به درد چه کسانی می‌خورد؟

مصرف‌کننده‌ها، توسعه‌دهنده‌ها، کاربران نهایی و در یک کلام مردم.

مسلماً وقتی نرم‌افزاری بروزرسانی می‌شود، کاربران آن دوست دارند بدانند چرا و چطور این تغییرات اعمال شده است.

چطور یک تاریخچهٔ تغییرات خوب بسازیم؟

راهنمای کلی

  • تاریخچهٔ تغییرات برای انسان است، نه ماشین.
  • برای هر نسخه از پروژه، یک مدخل جدید تعریف کنید.
  • تغییرات مشابه را دسته‌بندی کنید.
  • نسخه‌ها و بخش‌ها قابل لینک‌شدن باشند.
  • آخرین نسخه را در ابتدا قرار دهید.
  • تاریخ انتشار هر نسخه را مشخص کنید.
  • بگویید که آیا از نسخه‌بندی معنایی پیروی می‌کنید یا نه.

انواع تغییرات

  • Added برای قابلیت‌های جدید.
  • Changed برای تغییر در عملکردهای فعلی.
  • Deprecated برای قابلیت‌هایی که حذف می‌شود.
  • Removed برای قابلیت‌های حذف‌شده.
  • Fixed برای خطاهای رفع‌شده.
  • Security برای آسیب‌پذیری‌های امنیتی.

چطور ثبت تغییرات پروژه را آسان‌تر کنیم؟

در بالای فایل تاریخچهٔ تغییرات، بخشی را تحت عنوان Unreleased برای دنبال‌کردن تغییرات پیش‌رو در نظر بگیرید.

این کار دو فایده دارد:

  • اولاً کاربران می‌توانند پیش از انتشار یک نسخهٔ جدید، از تغییراتی که می‌توانند در نسخهٔ بعدی انتظار داشته باشند مطلع شوند.
  • دوماً هنگام انتشار نسخهٔ جدید، می‌توانید به‌راحتی بخش Unreleased را در قالب یک نسخهٔ جدید به بخش انتشاریافته‌ها منتقل کنید و دیگر لازم نباشد بروید ببینید چه تغییراتی ایجاد شده است.

آیا تاریخچهٔ تغییرات می‌تواند بد نوشته شود؟

بله. در شرایط زیر.:

استفاده از خروجی log diff به عنوان تاریخچهٔ تغییرات

استفاده از خروجی log diffها به عنوان تاریخچهٔ تغییرات، ایدهٔ بدی است. این خروجی مملو از اطلاعات درهم‌وبرهم است؛ مثلاً کامیت‌های مربوط به مرج، کامیت‌هایی با عناوین مبهم، تغییرات مربوط به مستندات و غیره.

هدف از یک کامیت، ثبت یک گام انجام‌شده در روند تکامل سورس کد است. برخی از پروژه‌ها، کامیت‌های تمیزی دارند و برخی نه.

هدف از یک مدخل جدید در فایل تاریخچهٔ تغییرات، مستندسازی شفاف تغییرات مهمِ پروژه برای کاربران نهایی است. هر مدخل در تاریخچهٔ تغییرات لزوماً متناظر با یک کامیت در تاریخچهٔ کامیت‌ها نیست. ممکن است چندین کامیت مختلف، مربوط به یک تغییر باشد و بالعکس یک کامیت (غیراستاندارد) دربردارندهٔ چندین تغییر مهم باشد.

نادیده‌گرفتن چیزهای منسوخ‌شده

وقتی کاربران از یک نسخه به نسخهٔ دیگر به‌روزرسانی می‌کنند، باید بدانند که چه موقع نسخهٔ جدید، تغییرات ناسازگار به‌همراه دارد؛ یعنی مثلاً بعد از بروزرسانی یک کتابخانه که پروژهٔ شما به آن وابسته بوده، آیا بخش‌هایی از پروژه از کار می‌افتد یا نه. اگر بله، کدام بخش‌ها. پاسخ به این سؤال کمک می‌کند توسعه‌دهنده‌ها متناسب با نسخهٔ جدید، قسمت‌های منسوخ‌شده را جایگزین کرده و بعد از آن اقدام به بروزرسانی کنند.

تاریخ‌های گیج‌کننده

در هر نقطه‌ای از دنیا شکل نمایش تاریخ متفاوت است؛ بنابراین پیداکردن یک قالب نمایش همه‌فهم برای کل مردم دنیا کار دشواری است. مزیت استفاده از قالب‌هایی مثل 17-07-2017 این است که در آن ترتیب بزرگترین به کوچکترین واحدها یعنی سال، ماه و روز رعایت شده است. این باعث می‌شود که برخلاف برخی از قالب‌ها که در آن جای ماه و روز عوض شده، درک تاریخ دچار ابهام نشود. با درنظرگرفتن این دلایل و این واقعیت که این فرمت، یک استاندارد ایزو است، این قالب را برای مدخل‌های تاریخچهٔ تغییرات در نظر گرفته‌ایم.

سوالات متداول

آیا فرمت استانداردی برای تاریخچهٔ تغییرات وجود دارد؟

حقیتاً نه. یک "راهنمای" راهنمای شیوه ثبت تاریخچهٔ تغییرات GNU و یک فایل دو پاراگرافی بلندِ GNU NEWS وجود دارد که متأسفانه هردویشان نارسا و ناکافی هستند.

این پروژه قصد دارد قراردادی بهتر برای ثبت تاریخچهٔ تغییرات باشد که برگرفته از تجربیات جامعهٔ متن‌باز است.

از نقد سالم، بحث‌وگفتگو و پیشنهادها استقبال می‌کنیم.

نام فایل تاریخچهٔ تغییرات چه چیزی باشد؟

نام این فایل را CHANGELOG.md بگذارید. بعضی پروژه‌ها از HISTORY, NEWS یا RELEASES استفاده می‌کنند.

چرا از ریلیزهای گیت‌هاب استفاده نکنیم؟

ابتکار خوبی است. در هنگام انتشار Releaseها می‌توانید به جای عرضهٔ یک نسخهٔ ساده (مثلاً یک برچسب خالی با نام v1.0.0)، لیست تغییرات آن نسخه را در قالب یک یادداشت، به آن برچسب ضمیمه کنید.

اما نکته این است که تاریخچهٔ تغییراتی که در هر ریلیز گیت‌هاب منتشر می‌کنید فقط در خودِ گیت‌هاب قابل استفاده است و به‌راحتی نمی‌توانید آن را به جای دیگری منتقل کنید. شاید بتوانید بسیار شبیه نسخهٔ پیشنهادی این سند کنید ولی کار زحمت‌داری است.

مشاهدهٔ تغییرات پروژه در لابه‌لای ریلیزهای گیت‌هاب، به اندازهٔ دیدن همهٔ تغییرات در یک فایل، آسان و دلچسب نیست. فایل‌هایی با حرف بزرگ، (README, CONTRIBUTING, غیره.) جذابیت بیشتری برای کاربران دارد. مشکل کوچک بعدی این است که رابط کاربری فعلی اجازه نمی‌دهد بین تاریخچهٔ کامیت‌ها در عرضه‌های مختلف، پیوند برقرار کنید.

آیا نمی‌توان مطابقت تاریخچهٔ تغییرات با موازین این سند را به صورت خودکار انجام داد؟

مشکل است؛ چون افراد از فرمت‌ها و نام‌گذاری‌های متعددی برای این فایل استفاده می‌کنند.

Vandamme یک روبی gem است که توسط تیم Gemnasium ساخته شده است. این ابزار، تاریخچهٔ تغییرات پروژه‌های متن‌باز (البته نه همه) را بررسی می‌کند.

عرضه‌های yanked چطور؟

عرضه‌های Yanked نسخه‌هایی هستند که به خاطر باگ جدی یا مشکل امنیتی باید گرفته شوند. این نسخه‌ها اغلب حتی در تاریخچهٔ تغییرات نیز دیده نمی‌شوند، اما باید اضافه شوند. آن‌ها را به صورت زیر در فایل تاریخچهٔ تغییرات نشان دهید:

## [0.0.5] - 2014-12-13 [YANKED]

برچسب [YANKED] را به این دلیل، به‌شکل متمایز در تاریخچهٔ تغییرات آورده‌ایم که نظرها را به خود جلب کند. بعلاوه وجود کروشه، کار پارزرها را راحت‌تر می‌کند.

آیا لازم است تاریخچهٔ تغییرات را بازنویسی کنیم؟

قطعاً. معمولاً همیشه دلیل خوبی برای بهبود تاریخچهٔ تغییرات وجود دارد. من معمولاً به‌طور منظم، فایل تاریخچهٔ تغییرات را برای پروژه‌های متن‌بازی که این کار را انجام نداده‌اند می‌نویسم و تغییرات را به صورت یک پول‌ریکوئست ارائه می‌دهم.

گاهی نیز ممکن است یادتان رفته باشد که تغییرات ناسازگارِ یک نسخه را ثبت کنید. در چنین شرایطی نیز واضح است که باید تاریخچهٔ تغییرات را بروزرسانی کنید.

چطور می‌توانم مشارکت کنم؟

این سند، کامل و بی‌نقص نیست؛ صرفاً نظرات به‌دقت بررسی‌شده‌ای است که همراه اطلاعات و مثال‌هایی، در اینجا قرار داده‌ام.

این به خاطر آن است که می‌خواهم جامعهٔ ما توسعه‌دهنده‌ها به یک اتفاق‌نظر برسد. من معتقدم بحث‌وگفتگو به‌اندازهٔ نتیجه مهم است.

بنابراین شما نیز دست به کار شوید.

گفتگو

در پادکست Changelog، گفتگویی داشته‌ام دربارهٔ انگیزهٔ پشت این پروژه و اینکه چرا متصدیان نگهداری و مشارکت‌کنندگان پروژه‌ها باید به تاریخچهٔ تغییرات اهمیت بدهند.