معرفی سیاههٔ تغییرات (Change Log)

سیاههٔ تغییرات (changelog یا CHANGELOG) اشاره به یک سیاهه یا تاریخچهٔ تغییراتی دارد که در یک پروژه همانند یک وب‌سایت اینترنتی یا یک پروژه نرم‌افزاری اعمال می‌شوند. یک پروندهٔ سیاههٔ تغییرات شامل یک لیستی است از تغییرات قابل توجه برای هر نسخه از یک پروژه. این تغییرات عموماً به عنوان اصلاحات باگ‌ها، قابلیت‌های جدید و ... در این سیاهه نوشته می‌شوند. برخی از پروژه‌های متن‌باز فایل سیاههٔ تغییرات را در دایرکتوری سطح بالای کدهای منبع پروژه خود قرار می‌دهند. هرچند که قرارداد متعارف نام‌گذاری این فایل ChangeLog است، این فایل گاهی اوقات به صورت CHANGES یا HISTORY هم نام‌گذاری می‌شود (باید توجه داشت که NEWS فایل متفاوتی است که تغییرات بوقوع پیوسته از یک نسخه به نسخه دیگر در آن نوشته می‌شود، نه تغییراتی که از یک کامیت به کامیتی دیگر اتفاق افتاده‌اند). برخی از نگه‌دارنده‌های پروژه‌ها پسوند ‎.txt را هم به انتهای این فایل اضافه می‌کنند. برخی از سیستم‌های نسخه‌بندی قادر به تولید کردن اطلاعاتی هستند که مناسب قرارگرفتن در یک فایل سیاههٔ تغییرات است.

چرا باید از سیاههٔ تغییرات جهت حفظ تغییرات استفاده شود؟

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

چه کسانی به سیاههٔ تغییرات نیاز دارند؟

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

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

راهنمای اصول

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

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

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

برای ردیابی تغییرات آتی یک بخش با عنوان Unreleased در بالا نگه‌دارید، این کار دو هدف دارد:

• مردم می‌توانند ببیند که در نسخه‌های آینده چه تغییراتی را می‌توان انتظار داشت.
• در زمان انتشار، می‌توانید تغییرات بخش Unreleased را به بخش نسخهٔ جدید منتقل کنید.

آیا استانداردی برای سیاههٔ تغییرات وجود دارد؟

حقیقتاً خیر، هرچند سبکی از گنو و همچنین بخشی از فایل خبر گنو به این مورد اشاره دارند، اما این‌ها ناکافی می‌باشند.

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

می‌توانید آن را CHANGELOG.md بنامید. برخی از پروژه‌ها از HISTORY، NEWS و یا RELEASES استفاده می‌کنند. هرچند مهم نیست که نام فایل نهایی این روند چه چیزی باشد، اما طوری باید باشد که کاربر متوجه هدف فایل تغییرات باشد.

یک مثال از قالب صحیح از سیاههٔ تغییرات

# 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.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [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 [@karalamalar](https://github.com/karalamalar).
- French translation from [@zapashcanon](https://github.com/zapashcanon).
- Brazilian Portugese 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.0.0...HEAD
[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