diff --git a/ar/1.0.0/index.html b/ar/1.0.0/index.html index e4b1a03..6588ef6 100644 --- a/ar/1.0.0/index.html +++ b/ar/1.0.0/index.html @@ -3,7 +3,7 @@ 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} p.yanked {direction:ltr;text-align:right} -

احتفظ بسجل التغيير

لا تدع أصدقائك يخلطون سجلات git مع سجلات التغيير

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

## [Unreleased]

## [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

ما هو سجل التغيير؟

سجل التغيير هو ملف يحتوي على قائمة مرتبة ترتيبًا زمنيًا بالتغييرات البارزة لكل إصدار من المشروع.

لماذا الاحتفاظ بسجل التغيير؟

لتسهيل الأمر على المستخدمين والمساهمين أن يروا بدقة التغييرات البارزة التي تم إجراؤها بين كل إصدار (أو نسخة) من المشروع.

من يحتاج إلى سجل التغيير؟

الناس على العموم. سواء أكان المستهلكون أم المطورون ، فإن المستخدمين النهائيين للبرامج هم بشر يهتمون بما يوجود في البرنامج ، وعندما يتغير فإنهم يرغبون في معرفة السبب والكيف.

كيف أصنع سجل تغيير جيد؟

مبادئ إرشادية

أنواع التغييرات

كيف يمكنني تقليل الجهد المطلوب لصيانة سجل التغيير؟

احتفظ بقسم لم يتم طرحه (Unreleased) بالأعلى لتتبع التغييرات القادمة.

يخدم هذا غرضين:

هل يمكن أن تكون سجلات التغيير سيئة؟

نعم. فيما يلي بعض الأمثلة التي يمكن أن تكون فيها سجلات التغيير عديمة فائدة.

تضمين تبديلات السجلات

استخدام تضمينات Git (commits) كسجلات التغيير هو فكرة سيئة: فهي مليئة بالضوضاء. أشياء مثل دمج التضمينات، تضمينات بعناوين غامضة، تغييرات التوثيق وما إلى ذلك

الغرض من التضمين هو توثيق خطوة في تطوير شفرة المصدر. بعض المشاريع تنظف تضميناتها ، وبعضها الآخر لا يفعل ذلك.

الغرض من فصول سجلات التغيير هو توثيق الاختلافات البارزة بين نسختين ، غالبًا عبر تضمينات عديدة ، لإيصالها بوضوح إلى المستخدمين النهائيين.

تجاهل التخريدات (Deprecations)

عندما تتم الترقية من إصدار إلى آخر ، يجب أن يكون جليا متى ينكسر شيء ما. يجب أن يمكن الترقية إلى إصدار يعد التخريدات ، وإزالة ما تم تخريده ، ثم الترقية إلى الإصدار حيث يصبح التخريد عملية إزالة وظائف.

إذا لم تفعل شيئًا آخر ، فقم بعد التخريدات، عمليات الإزالة وأي تغييرات مُعطبة للبرنامج في سجل التغيير الخاص بك.

تواريخ مربكة

تتنوع تنسيقات التاريخ الإقليمية في جميع أنحاء العالم وغالبًا ما يكون من الصعب العثور على تنسيق تاريخ يُشعر أنه بديهي للجميع. تتمثل ميزة التواريخ المنسقة مثل 2017-07-17 في أنها تتبع ترتيب الوحدات الأكبر إلى الأصغر: السنة والشهر واليوم. لا يتداخل هذا التنسيق بطرق غامضة مع تنسيقات التاريخ الأخرى ، على عكس بعض التنسيقات الإقليمية التي تغير موضع أرقام الشهر واليوم. بما أن تنسيق التاريخ هذا هو standard ISO فإنه تنسيق التاريخ الموصى به لفصول سجلات التغيير.

أسئلة شائعة

هل هناك تنسيق قياسي لسجلات التغيير؟

ليس حقا. هناك إرشادات GNU changelog style guide أو two-paragraph-long GNU NEWS file . كلاهما إما غير كافٍ أو غير مناسب.

يهدف هذا المشروع إلى أن يكون تحسين الصيغة الاصلاحية لسجلات التغيير. تمت صياغته من مراقبة الممارسات الجيدة في مجتمع المصادر المفتوحة وجمعها.

كل من النقد السليم والمناقشة والاقتراحات للتحسين مرحبٌ بها

كيف يجب تسمية ملف سجلات التغيير؟

أطلق عليه اسم CHANGELOG.md . تستخدم بعض المشاريع التسميات التالية HISTORY أو NEWS أو RELEASES .

بما أن اسم ملف سجل التغيير الخاص بك لا يهم كثيرًا ، فلماذا تجعل من الصعب على المستخدمين النهائيين العثور على التغييرات البارزة؟

وماذا عن إصدارات GitHub؟

إنها مبادرة رائعة. يمكن استخدام الإصدارات لتحويل علامات git البسيطة ( على سبيل المثال علامة باسم v1.0.0 ) إلى ملاحظات إصدار منسقة عن طريق إضافة ملاحظات الإصدار يدويًا أو يمكنها سحب رسائل علامة git المشروحة وتحويلها إلى ملاحظات.

تُنشئ إصدارات GitHub سجل تغيير غير محمول والذي لا يمكن عرضه إلا للمستخدمين في سياق GitHub. من الممكن جعلها تشبه إلى حد كبير تنسيق Keep a Changelog ، لكنها تميل إلى أن تكون أكثر مشاركة قليلاً.

يمكن القول أيضًا أن الإصدار الحالي من إصدارات GitHub يصعب استعماله من قبل المستخدمين النهائيين ، على عكس الملفات النموذجية ذات الأحرف الكبيرة (وما إلى ذلك README و CONTRIBUTING ) هناك مشكلة ثانوية أخرى وهي أن الواجهة لا تقدم حاليًا روابط لتضمين السجلات بين كل إصدار.

هل يمكن التحليل النحوي لسجلات التغيير تلقائيًا؟

يصعب فعل ذلك لأن الأشخاص يتبعون تنسيقات وأسماء ملفات مختلفة تمامًا.

Vandamme هو جوهرة Ruby تم إنشاؤها بواسطة فريق Gemnasium والتي تحلل نحويا العديد من (ولكن ليس كل) سجلات تغيير المشروع مفتوحة المصدر.

وماذا عن الإصدارات المسحوبة "Yanked"؟

الإصدارات المسحوبة هي نسخ حذفت بسبب عطب خطير أو مشكلة أمنية. غالبًا لا تظهر هذه الإصدارات في سجلات التغيير ولكن يجب فعل ذلك. هذه هي الطريقة التي يجب أن تعرضهم بها:

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

تم تسليط الضوء على علامة [YANKED] لسبب وجيه.إذ من المهم أن يلاحظها الناس. نظرًا لأنها محاطة بأقواس ، فمن السهل أيضًا القيام بالتحليل النحوي لها برمجيًا.

هل يجب عليك إعادة كتابة سجل التغيير؟

بالتأكيد. هناك دائمًا أسباب وجيهة لتحسين سجلات التغيير. أقوم بفتح طلبات السحب بانتظام لإضافة الإصدارات المفقودة إلى مشاريع مفتوحة المصدر مع سجلات التغيير المتروكة.

من الممكن أيضًا أن تكتشف أنك نسيت معالجة تغيير مُعطِب في ملاحظات النسخة. من الواضح أنه مهم بالنسبة لك تحديث سجل التغيير في هذه الحالة.

كيف يمكنني المساهمة؟

هذه الوثيقة ليست الحقيقة ؛ إنه رأيي المدروس بعناية ، إلى جانب المعلومات والأمثلة التي جمعتها.

هذا لأنني أريد أن يتوصل مجتمعنا إلى إجماع. أعتقد أن المناقشة لا تقل أهمية عن النتيجة النهائية.

لذا يرجى المشاركة.

محادثات

حضرت بودكاست سجلات التغيير للحديث عن سبب اهتمام المشرفين والمساهمين بسجلات التغيير ، وكذلك عن الدوافع وراء هذا المشروع.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Udržuj CHANGELOG

Nenech své kamarády házet do CHANGELOGů™ git logy.

Version 0.3.0

Co je to changelog?

Changelog je soubor, který obsahuje organizovaný, chronologicky seřazený seznam podstatných změn pro každou verzi daného projektu.

# 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.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?".

Co je smyslem changelogu?

Usnadnit uživatelům a přispěvatelům přesné zobrazení podstatných změn, které byly provedeny mezi jednotlivými vydáními (verzemi) daného projektu.

Proč by mi na tom mělo záležet?

Protože softwarové nástroje jsou pro lidi. Pokud ti na tom nezáleží, tak proč přispíváš do open source projektů? Určitě musí být v tvém úžasném malém mozku alespoň jádro (haha!) ochoty.

Bavil jsem se s Adamem Stacoviakem a Jerodem Santem na podcastu The Changelog (název sedí, co?) o tom proč by na tom mělo vedoucím a přispěvatelům projektů záležet a o tom jaká motivace je za tímto projektem. Jestli máš chvilku času (1:06), stojí to za poslech.

Co dělá changelog dobrým?

Výborná otázka, díky za ni.

Dobrý changelog se drří těchto principů:

Jak mohu vyžadovanou snahu snížit na minimum?

Vždycky měj nahoře sekci "Unreleased", ve které budou schromažďovány všechny změny.

To plní hned dva účely:

Co zaručeně rozbrečí jednorožce?

Dobrá… Tak si to povíme.

To ale není všechno. Pomoz mi sbírat jednorožčí slzy tím že otevřeš issue nebo pull request.

Existuje pro formát changelogů nějaký standard?

Bohužel ne. Klid. Vím, že se zuřivě snažíš najít ten odkaz na GNU návod jakým stylem psát changelog, nebo onen dvouodstavcový GNU NEWS soubor, který si říká "směrnice". Zmíněný GNU návod je sice hezký začátek, ale je smutně naivní. Být naivní není nic špatného, ale když lidé potřebují radu, málokdy to někomu pomůže. Obzvlášť, když existuje tolik situací a okrajových případů, se kterými se musí člověk nějak poprat.

Tento projekt obsahuje něco, co se doufám jednou stane lepší konvencí pro CHANGELOGy. Nemyslím si, že je momentální stav dostatečně dobrý, a jsem toho názoru, že jsme jako komunita schopni vymyslet lepší konvence, pokud se budeme snažit vybrat ty nejlepší praktiky z doopravdových softwarových projektů. Porozhlédněte se a mějte na paměti, že diskuse a návrhy na zlepšení jsou vítány!

Jak by se měl changelog jmenovat?

Inu, pokud jste to už nepoznali z příkladu výše, CHANGELOG.md je zatím ta nejlepší konvence.

Některé projekty používají HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, apod.

Je v tom binec. Všecha tato jména jen komplikují život lidem, kteří se ten dokument snaží najít.

Proč lidé jednoduše nepoužívají git log diff?

Protože diffy logů jsou plné šumu — přirozeně. Nebyly by vyhovujícím changelogem ani v hypotetickém projektu vedeném dokonalými lidmi, kteří nikdy nedělají překlepy, nikdy nezapomínají commitnout nové soubory a nikdy jim neunikne ani ta nejmenší část refactoringu. Cílem commitu je dokumentovat jeden miniaturní krok při procesu, ve kterém se kód vyvíjí z jedné podoby do druhé. Cílem changelogu je dokumentovat podstatné změny mezi těmito podobami.

Stějně jako je rozdíl mezi dobrými komentáři a samotným kódem, je také rozdíl mezi changelogem a commitlogem: jeden říká proč a druhý jak.

Mohou být changelogy automaticky parsované?

Je to složité, jelikož se lidé uchylují k nejrůznějším formátům a názvům souborů.

Vandamme je Ruby gem vytvořený týmem Gemnasium, který parsuje mnoho (ale ne všechny) changelogů open source projektů.

Proč používáš jednou "CHANGELOG" a jindy "changelog"?

"CHANGELOG" je název samotného souboru. Je to třichu křiklavé, ale to už je historická konvence, kterou se řídí mnoho open source projektů. Příklady podobných souborů mohou být README, LICENSE a CONTRIBUTING.

Název psaný kapitálkami (díky kterému se ve starých operačních systémech soubory držely na nejvyšších pozicích) je používán za účelem upoutání pozornosti. Vzhledem k tomu, že se jedná o důležitá metadata o projektu a mohla by být užitečná pro kohokoliv, kdo ho chce používat nebo do něho přispívat, podobně open source projektovým odznakům.

Když mluvím o "changelogu", myslím tím funkci tohoto souboru: logování změn.

Jak potom vypadají ta vydání, která byla zpětně stažena?

Zpětně stažená vydání jsou verze, které musely být zpětně odebrány kvůli vážné chybě nebo bezpečnostním rizikům. Tyto verze se často v changelogu ani neobjevují, ale měly by. Zobrazovat by se měli takto:

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

Tag [YANKED] je naschvál křiklavý. Je důležité, aby si ho lidé všimli. Díky tomu, že je v hranatých závorkách je take jednoduší ho parsovat programem.

Měl by se někdy changelog přepisovat?

Jasně. Vždy se najde dobrý důvod pro zlepšení changelogu. Sám často otevírám pull requesty pro přidání chybějících vydání v open source projektech s neudržovanými changelogy.

Je také možné, že zjistíš, že v poznámkách k verzi ve tvém projektu není zmíněna změna, která něco mohla rozbít. V tom případě jě samozřejmě důležité, aby byl changelog aktualizován.

Jak mohu přidat ruku k dílu?

Tento dokument není čistá pravda; je to můj názor, nad kterým jsem opatrně uvažoval, v kombinaci s informacemi a příklady, které se mi podařilo získat. I přesto, že uvádím vlastní CHANGELOG v repozitáři na GitHubu, naschvál jsem nevytvořil náležité vydání nebo jasný seznam pravidel, kterými se někdo má řídit (jako to například udělali na SemVer.org).

Je tomu tak proto, že chci aby komunita došla ke společné shodě. Já sám jsem toho názoru, že diskuse je důležitou součástí finálního výsledku.

Takže prosím přispějte svou trochou do mlýna.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Udržuj CHANGELOG

Nenech své kamarády házet do CHANGELOGů™ git logy.

Version 0.3.0

Co je to changelog?

Changelog je soubor, který obsahuje organizovaný, chronologicky seřazený seznam podstatných změn pro každou verzi daného projektu.

# 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.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?".

Co je smyslem changelogu?

Usnadnit uživatelům a přispěvatelům přesné zobrazení podstatných změn, které byly provedeny mezi jednotlivými vydáními (verzemi) daného projektu.

Proč by mi na tom mělo záležet?

Protože softwarové nástroje jsou pro lidi. Pokud ti na tom nezáleží, tak proč přispíváš do open source projektů? Určitě musí být v tvém úžasném malém mozku alespoň jádro (haha!) ochoty.

Bavil jsem se s Adamem Stacoviakem a Jerodem Santem na podcastu The Changelog (název sedí, co?) o tom proč by na tom mělo vedoucím a přispěvatelům projektů záležet a o tom jaká motivace je za tímto projektem. Jestli máš chvilku času (1:06), stojí to za poslech.

Co dělá changelog dobrým?

Výborná otázka, díky za ni.

Dobrý changelog se drří těchto principů:

Jak mohu vyžadovanou snahu snížit na minimum?

Vždycky měj nahoře sekci "Unreleased", ve které budou schromažďovány všechny změny.

To plní hned dva účely:

Co zaručeně rozbrečí jednorožce?

Dobrá… Tak si to povíme.

To ale není všechno. Pomoz mi sbírat jednorožčí slzy tím že otevřeš issue nebo pull request.

Existuje pro formát changelogů nějaký standard?

Bohužel ne. Klid. Vím, že se zuřivě snažíš najít ten odkaz na GNU návod jakým stylem psát changelog, nebo onen dvouodstavcový GNU NEWS soubor, který si říká "směrnice". Zmíněný GNU návod je sice hezký začátek, ale je smutně naivní. Být naivní není nic špatného, ale když lidé potřebují radu, málokdy to někomu pomůže. Obzvlášť, když existuje tolik situací a okrajových případů, se kterými se musí člověk nějak poprat.

Tento projekt obsahuje něco, co se doufám jednou stane lepší konvencí pro CHANGELOGy. Nemyslím si, že je momentální stav dostatečně dobrý, a jsem toho názoru, že jsme jako komunita schopni vymyslet lepší konvence, pokud se budeme snažit vybrat ty nejlepší praktiky z doopravdových softwarových projektů. Porozhlédněte se a mějte na paměti, že diskuse a návrhy na zlepšení jsou vítány!

Jak by se měl changelog jmenovat?

Inu, pokud jste to už nepoznali z příkladu výše, CHANGELOG.md je zatím ta nejlepší konvence.

Některé projekty používají HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, apod.

Je v tom binec. Všecha tato jména jen komplikují život lidem, kteří se ten dokument snaží najít.

Proč lidé jednoduše nepoužívají git log diff?

Protože diffy logů jsou plné šumu — přirozeně. Nebyly by vyhovujícím changelogem ani v hypotetickém projektu vedeném dokonalými lidmi, kteří nikdy nedělají překlepy, nikdy nezapomínají commitnout nové soubory a nikdy jim neunikne ani ta nejmenší část refactoringu. Cílem commitu je dokumentovat jeden miniaturní krok při procesu, ve kterém se kód vyvíjí z jedné podoby do druhé. Cílem changelogu je dokumentovat podstatné změny mezi těmito podobami.

Stějně jako je rozdíl mezi dobrými komentáři a samotným kódem, je také rozdíl mezi changelogem a commitlogem: jeden říká proč a druhý jak.

Mohou být changelogy automaticky parsované?

Je to složité, jelikož se lidé uchylují k nejrůznějším formátům a názvům souborů.

Vandamme je Ruby gem vytvořený týmem Gemnasium, který parsuje mnoho (ale ne všechny) changelogů open source projektů.

Proč používáš jednou "CHANGELOG" a jindy "changelog"?

"CHANGELOG" je název samotného souboru. Je to třichu křiklavé, ale to už je historická konvence, kterou se řídí mnoho open source projektů. Příklady podobných souborů mohou být README, LICENSE a CONTRIBUTING.

Název psaný kapitálkami (díky kterému se ve starých operačních systémech soubory držely na nejvyšších pozicích) je používán za účelem upoutání pozornosti. Vzhledem k tomu, že se jedná o důležitá metadata o projektu a mohla by být užitečná pro kohokoliv, kdo ho chce používat nebo do něho přispívat, podobně open source projektovým odznakům.

Když mluvím o "changelogu", myslím tím funkci tohoto souboru: logování změn.

Jak potom vypadají ta vydání, která byla zpětně stažena?

Zpětně stažená vydání jsou verze, které musely být zpětně odebrány kvůli vážné chybě nebo bezpečnostním rizikům. Tyto verze se často v changelogu ani neobjevují, ale měly by. Zobrazovat by se měli takto:

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

Tag [YANKED] je naschvál křiklavý. Je důležité, aby si ho lidé všimli. Díky tomu, že je v hranatých závorkách je take jednoduší ho parsovat programem.

Měl by se někdy changelog přepisovat?

Jasně. Vždy se najde dobrý důvod pro zlepšení changelogu. Sám často otevírám pull requesty pro přidání chybějících vydání v open source projektech s neudržovanými changelogy.

Je také možné, že zjistíš, že v poznámkách k verzi ve tvém projektu není zmíněna změna, která něco mohla rozbít. V tom případě jě samozřejmě důležité, aby byl changelog aktualizován.

Jak mohu přidat ruku k dílu?

Tento dokument není čistá pravda; je to můj názor, nad kterým jsem opatrně uvažoval, v kombinaci s informacemi a příklady, které se mi podařilo získat. I přesto, že uvádím vlastní CHANGELOG v repozitáři na GitHubu, naschvál jsem nevytvořil náležité vydání nebo jasný seznam pravidel, kterými se někdo má řídit (jako to například udělali na SemVer.org).

Je tomu tak proto, že chci aby komunita došla ke společné shodě. Já sám jsem toho názoru, že diskuse je důležitou součástí finálního výsledku.

Takže prosím přispějte svou trochou do mlýna.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Udržuj Changelog

Nenech své kamarády sypat git logy do changelogů.

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

## [Unreleased]

## [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

Co je to changelog?

Changelog je soubor, který obsahuje organizovaný, chronologicky seřazený seznam podstatných změn pro každou verzi daného projektu.

Proč udržovat changelog?

Aby uživatelé a přispěvatelé přesně věděli, jaké podstatné změny byly provedeny mezi jednotlivými vydáními (verzemi) daného projektu.

Kdo potřebuje changelog?

Lidé. Ať už se jedná o spotřebitele nebo vývojáře, koncoví uživatelé softwaru jsou lidská stvoření, kterým záleží na tom, co software obsahuje. Když se daný software změní, lidé chtějí vědět proč a jak.

Jak vytvořit dobrý changelog?

Hlavní zásady

  • Changelogy jsou pro lidi, ne pro stroje.
  • Changelog by měl obsahovat záznam pro každou verzi.
  • Stejné typy změn by měly být seskupené.
  • Měla by existovat možnost odkazovat na jednotlivé verze a sekce.
  • Poslední verze je na prvním místě.
  • U každé verze je poznamenáno datum jejího vydání.
  • Zmiňte, zda se držíte Sémantického verzování

Typy změn

  • Added pro nové funkce.
  • Changed pro změny v existující funkcionalitě.
  • Deprecated pro funkce, které budou brzy odstraněny.
  • Removed pro odstraněné funkce.
  • Fixed pro opravy chyb.
  • Security v případě bezpečnostních zranitelností.

Jak minimalizovat úsilí potřebné k udržování changelogu?

Udržováním Unreleased sekce na začátku souboru pro zaznamenávání nadcházejících změn.

To plní hned dva účely:

  • Lidé uvidí, jaké změny mohou očekávat v následujících vydáních
  • V čas vydání stačí přesunout změny z Unreleased sekce do sekce nového vydání.

Mohou být changelogy špatné?

Ano. Zde je několik případů, kdy mohou být opakem užitečného.

Diffy z commit logu

Používání diffů z commit logu jako changelogu je špatný nápad: jsou plné šumu. Obsahují věci jako merge commity, commity s nejasnými nadpisy, změny v dokumentaci, atd.

Účelem commitu je zdokumentovat krok v evoluci zdrojového kódu. Některé projekty commity pročišťují, jiné zas ne.

Účelem záznamu v changelogu je zdokumentovat podstatné změny, často napříč několika commity, a jasně je sdělit koncovým uživatelům.

Ignorování odstraněných funkcí

Když lidé upgradují z jedné verze na druhou, mělo by jim být bolestně jasné, když se něco rozbije. Mělo by být možné nejprve upgradovat na verzi, která oznámí, jaké funkce budou odstraněny, dané funkce odstranit a poté upgradovat na verzi, kde jsou zmíněné funkce již odstraněny.

Když už nic jiného, je dobré alespoň vypsat odstraněné funkce a změny, které něco rozbíjí, do changelogu.

Matoucí data

Regionální formáty dat se liší napříč světem a je často složité najít formát, který je přátelský a intuitivní pro všechny. Výhodou dat formátovaných jako 2017-07-17 je pořadí jednotek od největší po nejmenší: rok, měsíc a den. Tento formát se navíc nepřekrývá s jinými, narozdíl od některých regionálních formátů, které prohazují pozici měsíce a dne. Díky těmto důvodům, a také faktu, že je tento formát ISO standard, je doporučeným formátem pro záznamy v changelogu.

Časko kladené otázky

Existuje pro formát changelogu nějaký standard?

Ne. Je tu GNU stylová příručka pro changelog, nebo ta dvouodstavcová GNU "směrnice" pro NEWS soubor. Ani jedno však není vhodné či dostačující.

Tento projekt má za cíl být lepší konvencí pro changelog. Pochází z pozorování osvědčených postupů v open source komunitě a jejich shromažďování.

Zdravá kritika, diskuse a návrhy na zlepšení jsou vítány.

Jak by se soubor s changelogem měl jmenovat?

Pojmenujte ho CHANGELOG.md. Některé projekty používají HISTORY, NEWS nebo RELEASES.

Zatímco je snadné si myslet, že na názvu souboru vašeho changelogu až tak nezáleží, proč koncovým uživatelům ztěžovat hledání významných změn?

A co GitHub Releases?

Je to skvělá iniciativa. Služba Releases může být použita na proměnu obyčejných git tagů (například tag s názvem v1.0.0) na bohaté poznámky k vydání manuálním přidáním daných poznámek, nebo může pullnout zprávy z anotovaných git tagů a udělat poznámky k vydání z nich.

GitHub Releases však vytvářejí nepřenosný changelog, který může být zobrazen uživatelům jen v kontextu GitHubu. Je možné je udělat velmi podobné formátu projektu Udržuj Changelog, ale to má tendenci být trochu náročnější.

Aktuální verze GitHub Releases také pravděpodobně není příliš objevitelná koncovými uživateli, narozdíl od typických souborů s názvy psanými velkými písmeny (README, CONTRIBUTING, atd.). Další menší problém je, že Releases aktuálně nenabízí možnost odkazovat na commit logy mezi jednotlivými vydáními.

Mohou changelogy být automaticky parsovány?

Je to složité, protože lidé používají mnoho rozdílných formátů a názvů souborů.

Vandamme je Ruby gem vytvořený týmem Gemnasium, který parsuje mnoho (ale ne všechny) changelogy open source projektů.

A co zpětně stažená vydání?

Stažená vydání jsou verze, které musely být zpětně odebrány kvůli vážné chybě nebo bezpečnostním rizikům. Tyto verze se často v changelogu ani neobjevují, ale měly by. Zobrazovat by se měly takto:

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

Tag [YANKED] je křiklavý naschvál. Je důležité, aby si ho lidé všimli. Díky tomu, že je v hranatých závorkách, je také jednodušší ho parsovat programem.

Měl by se changelog někdy přepisovat?

Jistě. Vždy se najde dobrý důvod pro zlepšení changelogu. Sám často otevírám pull requesty pro přidání chybějících vydání v open source projektech s neudržovanými changelogy.

Je také možné, že zjistíte, že v poznámkách k verzi ve vašem projektu není zmíněna změna, která něco rozbila. V tom případě je samozřejmě důležité, aby byl changelog aktualizován.

Jak mohu přispět?

Tento dokument není čistá pravda; je to můj pečlivě zvážený názor, společně s informacemi a příklady, které jsem shromáždil.

Je tomu tak proto, že chci aby naše komunita došla ke společné shodě. Věřím, že diskuse je stejně důležitá jako konečný výsledek.

Takže prosím, přiložte ruku k dílu.

Rozhovory

Zúčastnil jsem se podcastu The Changelog, abych promluvil o tom, proč by se správci projektů a přispěvatelé měli starat o changelogy a také o motivaci za tímto projektem.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Udržuj Changelog

Nenech své kamarády sypat git logy do changelogů.

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

## [Unreleased]

## [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

Co je to changelog?

Changelog je soubor, který obsahuje organizovaný, chronologicky seřazený seznam podstatných změn pro každou verzi daného projektu.

Proč udržovat changelog?

Aby uživatelé a přispěvatelé přesně věděli, jaké podstatné změny byly provedeny mezi jednotlivými vydáními (verzemi) daného projektu.

Kdo potřebuje changelog?

Lidé. Ať už se jedná o spotřebitele nebo vývojáře, koncoví uživatelé softwaru jsou lidská stvoření, kterým záleží na tom, co software obsahuje. Když se daný software změní, lidé chtějí vědět proč a jak.

Jak vytvořit dobrý changelog?

Hlavní zásady

  • Changelogy jsou pro lidi, ne pro stroje.
  • Changelog by měl obsahovat záznam pro každou verzi.
  • Stejné typy změn by měly být seskupené.
  • Měla by existovat možnost odkazovat na jednotlivé verze a sekce.
  • Poslední verze je na prvním místě.
  • U každé verze je poznamenáno datum jejího vydání.
  • Zmiňte, zda se držíte Sémantického verzování

Typy změn

  • Added pro nové funkce.
  • Changed pro změny v existující funkcionalitě.
  • Deprecated pro funkce, které budou brzy odstraněny.
  • Removed pro odstraněné funkce.
  • Fixed pro opravy chyb.
  • Security v případě bezpečnostních zranitelností.

Jak minimalizovat úsilí potřebné k udržování changelogu?

Udržováním Unreleased sekce na začátku souboru pro zaznamenávání nadcházejících změn.

To plní hned dva účely:

  • Lidé uvidí, jaké změny mohou očekávat v následujících vydáních
  • V čas vydání stačí přesunout změny z Unreleased sekce do sekce nového vydání.

Mohou být changelogy špatné?

Ano. Zde je několik případů, kdy mohou být opakem užitečného.

Diffy z commit logu

Používání diffů z commit logu jako changelogu je špatný nápad: jsou plné šumu. Obsahují věci jako merge commity, commity s nejasnými nadpisy, změny v dokumentaci, atd.

Účelem commitu je zdokumentovat krok v evoluci zdrojového kódu. Některé projekty commity pročišťují, jiné zas ne.

Účelem záznamu v changelogu je zdokumentovat podstatné změny, často napříč několika commity, a jasně je sdělit koncovým uživatelům.

Ignorování odstraněných funkcí

Když lidé upgradují z jedné verze na druhou, mělo by jim být bolestně jasné, když se něco rozbije. Mělo by být možné nejprve upgradovat na verzi, která oznámí, jaké funkce budou odstraněny, dané funkce odstranit a poté upgradovat na verzi, kde jsou zmíněné funkce již odstraněny.

Když už nic jiného, je dobré alespoň vypsat odstraněné funkce a změny, které něco rozbíjí, do changelogu.

Matoucí data

Regionální formáty dat se liší napříč světem a je často složité najít formát, který je přátelský a intuitivní pro všechny. Výhodou dat formátovaných jako 2017-07-17 je pořadí jednotek od největší po nejmenší: rok, měsíc a den. Tento formát se navíc nepřekrývá s jinými, narozdíl od některých regionálních formátů, které prohazují pozici měsíce a dne. Díky těmto důvodům, a také faktu, že je tento formát ISO standard, je doporučeným formátem pro záznamy v changelogu.

Časko kladené otázky

Existuje pro formát changelogu nějaký standard?

Ne. Je tu GNU stylová příručka pro changelog, nebo ta dvouodstavcová GNU "směrnice" pro NEWS soubor. Ani jedno však není vhodné či dostačující.

Tento projekt má za cíl být lepší konvencí pro changelog. Pochází z pozorování osvědčených postupů v open source komunitě a jejich shromažďování.

Zdravá kritika, diskuse a návrhy na zlepšení jsou vítány.

Jak by se soubor s changelogem měl jmenovat?

Pojmenujte ho CHANGELOG.md. Některé projekty používají HISTORY, NEWS nebo RELEASES.

Zatímco je snadné si myslet, že na názvu souboru vašeho changelogu až tak nezáleží, proč koncovým uživatelům ztěžovat hledání významných změn?

A co GitHub Releases?

Je to skvělá iniciativa. Služba Releases může být použita na proměnu obyčejných git tagů (například tag s názvem v1.0.0) na bohaté poznámky k vydání manuálním přidáním daných poznámek, nebo může pullnout zprávy z anotovaných git tagů a udělat poznámky k vydání z nich.

GitHub Releases však vytvářejí nepřenosný changelog, který může být zobrazen uživatelům jen v kontextu GitHubu. Je možné je udělat velmi podobné formátu projektu Udržuj Changelog, ale to má tendenci být trochu náročnější.

Aktuální verze GitHub Releases také pravděpodobně není příliš objevitelná koncovými uživateli, narozdíl od typických souborů s názvy psanými velkými písmeny (README, CONTRIBUTING, atd.). Další menší problém je, že Releases aktuálně nenabízí možnost odkazovat na commit logy mezi jednotlivými vydáními.

Mohou changelogy být automaticky parsovány?

Je to složité, protože lidé používají mnoho rozdílných formátů a názvů souborů.

Vandamme je Ruby gem vytvořený týmem Gemnasium, který parsuje mnoho (ale ne všechny) changelogy open source projektů.

A co zpětně stažená vydání?

Stažená vydání jsou verze, které musely být zpětně odebrány kvůli vážné chybě nebo bezpečnostním rizikům. Tyto verze se často v changelogu ani neobjevují, ale měly by. Zobrazovat by se měly takto:

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

Tag [YANKED] je křiklavý naschvál. Je důležité, aby si ho lidé všimli. Díky tomu, že je v hranatých závorkách, je také jednodušší ho parsovat programem.

Měl by se changelog někdy přepisovat?

Jistě. Vždy se najde dobrý důvod pro zlepšení changelogu. Sám často otevírám pull requesty pro přidání chybějících vydání v open source projektech s neudržovanými changelogy.

Je také možné, že zjistíte, že v poznámkách k verzi ve vašem projektu není zmíněna změna, která něco rozbila. V tom případě je samozřejmě důležité, aby byl changelog aktualizován.

Jak mohu přispět?

Tento dokument není čistá pravda; je to můj pečlivě zvážený názor, společně s informacemi a příklady, které jsem shromáždil.

Je tomu tak proto, že chci aby naše komunita došla ke společné shodě. Věřím, že diskuse je stejně důležitá jako konečný výsledek.

Takže prosím, přiložte ruku k dílu.

Rozhovory

Zúčastnil jsem se podcastu The Changelog, abych promluvil o tom, proč by se správci projektů a přispěvatelé měli starat o changelogy a také o motivaci za tímto projektem.

Hold en changelog

Du skal ikke lade dine venner smide git logs i changelogs.

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

## [Unreleased]

## [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

Hvad er en changelog?

En changelog er en fil, der indeholder en organiseret, kronologisk sorteret liste af bemærkelsesværdige ændringer for hver version af et projekt.

Hvorfor have en changelog?

For at gøre det nemmere for brugere og bidragsydere at se præcist hvilke bemærkelsesværdige ændringer, der er lavet mellem hver udgivelse eller version af et projekt.

Hvem skal bruge en changelog?

Det skal folk. Om det er forbrugere eller udviklere, er slutbrugere mennesker, der bekymrer sig om, hvad der er i et stykke software. Når softwaren ændrer sig, vil folk gerne vide hvad, og hvordan.

Hvordan laver jeg en god changelog?

Retningslinjer

  • Changelogs er til for mennesker, ikke maskiner.
  • Der skal være et indlæg for hver eneste version.
  • Ens typer af ændringer skal grupperes.
  • Versioner og sektioner skal være link-bare.
  • Den seneste version står først.
  • Udgivelsesdatoen for hver version vises.
  • Nævn hvorvidt du følger Semantisk Versionering.

Ændringstyper

  • Tilføjet (Added) til nye funktioner.
  • Ændret (Dhanged) til rettelser i eksisterende funktionalitet.
  • Udfaset (Deprecated) til funktioner, der fjernes snart.
  • Fjernet (Removed) til fjernede funktioner.
  • Rettet (Fixed) til fejlrettelser.
  • Sikkerhed (Security) i tilfælde af sårbarheder.

Hvordan kan jeg reducere indsatsen ved at opretholde en changelog?

Hav en Unreleased sektion i toppen til kommende rettelser.

Dette tjener to formål:

  • Folk kan se, hvilke rettelser de kan forvente i den kommende udgivelse
  • Ved udgivelsen kan du flytte Unreleased sektionens rettelser ind i en ny versionssektion.

Kan changelogs være dårlige?

Ja. Her er et par måder, de kan være mindre brugbare.

Commit log diffs

At bruge commit log differenser som changelog er en dårlig idé: De er fyldt med støj. Ting som merge-commits, commits med obskure titler, dokumentationsrettelser osv.

Formålet med et commit er at dokumentere et trin i udviklingen af kildekoden. Nogle projekter rydder op i deres commits, andre gør ikke.

Formålet med en changelog-indlæg er at dokumentere de bemærkelsesværdige forskelle, ofte fordelt over flere commits, for at formidle dem klart til slutbrugerene.

At ignorere udfasninger

Når folk opgraderer fra én version til en anden, skal det være helt tydeligt, hvorvidt noget vil gå i stykker. Det skal være muligt at opgradere til en version, der opsummerer udfasninger, fjerner gamle udfasniner, og opgradere til dén version, hvor udfasningerne bliver til oprydninger.

Hvis du ikke gør andet, så notér udfasninger, fjernede funktioner og andre ødelæggende ændringer.

Forvirrende datoer

Regionale dataformater er varierende i hele verden, og det er ofte besværligt at finde et læsbart datoformat, der føles intuitivt for alle Fordelen ved datoer formatteret som 2017-07-17 er at de følger rækkefølgen for største til mindste enhed: år, måned og dag. Dette format overlapper heller ikke på en tvetydig måde med andre datoformater, der ombytter måneden og daten. Af disse årsager, og det faktum at dette datoformat er en ISO standard, er dette det anbefalede datoformat for changelog-indlæg.

Ukonsistente rettelser

En changelog, der kun nævner nogle af ændringerne, kan være lige så farlig som ikke at have en changelog. Mens mange af ændringerne måske ikke er relevante - for eksempel er det ikke være nødvendigt at notere, at vi har fjernet et enkelt mellemrum - bør væsentlige ændringer være nævnt i changeloggen. Ved inkonsekvent at anvende ændringer, kan dine brugere fejlagtigt tro, at changelog er den eneste kilde til sandhed. Det bør den være. Med store magtbeføjelser følger store forpligtigelser. At have en god changelog er at have en konsekvent opdateret changelog.

Ofte stillede spørgsmål

Er der et standard changelog-format?

Ikke rigtig. Der er GNU changelog style guide, eller two-paragraph-long GNU NEWS file. De er begge utilstrækkelige eller uhensigtsmæssige.

Dette projekt sigter efter at være en bedre changelog konvention. Det kommer af at observere god praksis i opensource-verdenen og samle disse.

Konstruktiv kritik diskussion og forbedringsforslag er velkomne.

Hvad skal changelog-filen hedde?

Kald den CHANGELOG.md. Nogle projekter bruger HISTORY, NEWS eller RELEASES.

Selvom det er nemt at mene, at navnet på changelog-filen er irrelevant, hvorfor så gøre det sværere for dine slugbrugere at finde bemærkelsesværdige ændringer?

Hvad med GitHub Releases?

Det er et godt initiativ. Releases kan bruges til at gøre simple git tags (for eksempel, et tag v1.0.0) til fyldige udgivelsesnoter ved manuelt at tilføje noter til disse eller bruge en annoteret git-tag-besked som udgivelsesnoter.

GitHub Releases laver en ikke-flytbar changelog, der kun kan vises til bruger i konteksten af GitHub. Det er muligt at få dem til at ligne Hold en changelog-formatet, men det har en tendens til at være lidt mere kompliceret.

Den nuværende version af GitHub releases er, diskutérbart, ikke særligt synlig for slutbrugere, ikke lig de typiske kapitaliserede filer (README, CONTRIBUTING, osv.). Et andet mindre problem, er at interfacet ikke tilbyder links til commit logs mellem hvert release.

Kan changelogs læses og fortolkes automatisk?

Det er besværligt, fordi folk følger vidt forskellige formater og filnavne.

Vandamme er en Ruby gem lavet af holdet bag Gemnasium, som læser og fortolker mange (men ikke alle) open source projekters changelogs.

Hvad med tilbagetrukkede udgivelser?

Tilbagetrukkede udgivelser er versioner, der er blevet trukket tilbage på grund af en seriøs fejl eller sikkerhedsbrist. Ofte vises disse versioner slet ikke i changelogs. Det bør de. Dette er hvordan du bør vise dem:

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

Notationen [YANKED], er højlydt af en årsag: Det er vigtig information for folk. Siden den er pakket ind i klammer, er den nemmere at fortolke og læse systematiseret.

Bør man nogensinde omskrive en changelog?

Klart! Der er altid gode grunde til at forbedre en changelog. Jeg åbner jævnligt pull-requests, der tilføjer manglende releases til open source projekter uden en vedligeholdt changelog.

Det er også muligt, at du vil opdage at du har glemt at addressere en ødelæggende rettelse i noterne for en version. Det er selvfølgelig vigtigt at du opdaterer en changelog i disse tilfælde.

Hvordan kan jeg hjælpe til?

Dette dokument er ikke sandheden; det er min velovervejede mening sammen med information og eksempler jeg har samlet.

Det er fordi, jeg gerne vil have at vores fællesskab når en konsensus. Jeg mener at diskussionen er lige så vigtig som slutresultatet.

Så, vær med!

Samtaler

Jeg var med i The Changelog podcast for at snakke om, hvorfor vedligeholdere og bidragsydere bør bekymre sig om changelogs og også om motivationen bag dette projekt.

Hold en changelog

Du skal ikke lade dine venner smide git logs i changelogs.

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

## [Unreleased]

## [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

Hvad er en changelog?

En changelog er en fil, der indeholder en organiseret, kronologisk sorteret liste af bemærkelsesværdige ændringer for hver version af et projekt.

Hvorfor have en changelog?

For at gøre det nemmere for brugere og bidragsydere at se præcist hvilke bemærkelsesværdige ændringer, der er lavet mellem hver udgivelse eller version af et projekt.

Hvem skal bruge en changelog?

Det skal folk. Om det er forbrugere eller udviklere, er slutbrugere mennesker, der bekymrer sig om, hvad der er i et stykke software. Når softwaren ændrer sig, vil folk gerne vide hvad, og hvordan.

Hvordan laver jeg en god changelog?

Retningslinjer

  • Changelogs er til for mennesker, ikke maskiner.
  • Der skal være et indlæg for hver eneste version.
  • Ens typer af ændringer skal grupperes.
  • Versioner og sektioner skal være link-bare.
  • Den seneste version står først.
  • Udgivelsesdatoen for hver version vises.
  • Nævn hvorvidt du følger Semantisk Versionering.

Ændringstyper

  • Tilføjet (Added) til nye funktioner.
  • Ændret (Dhanged) til rettelser i eksisterende funktionalitet.
  • Udfaset (Deprecated) til funktioner, der fjernes snart.
  • Fjernet (Removed) til fjernede funktioner.
  • Rettet (Fixed) til fejlrettelser.
  • Sikkerhed (Security) i tilfælde af sårbarheder.

Hvordan kan jeg reducere indsatsen ved at opretholde en changelog?

Hav en Unreleased sektion i toppen til kommende rettelser.

Dette tjener to formål:

  • Folk kan se, hvilke rettelser de kan forvente i den kommende udgivelse
  • Ved udgivelsen kan du flytte Unreleased sektionens rettelser ind i en ny versionssektion.

Kan changelogs være dårlige?

Ja. Her er et par måder, de kan være mindre brugbare.

Commit log diffs

At bruge commit log differenser som changelog er en dårlig idé: De er fyldt med støj. Ting som merge-commits, commits med obskure titler, dokumentationsrettelser osv.

Formålet med et commit er at dokumentere et trin i udviklingen af kildekoden. Nogle projekter rydder op i deres commits, andre gør ikke.

Formålet med en changelog-indlæg er at dokumentere de bemærkelsesværdige forskelle, ofte fordelt over flere commits, for at formidle dem klart til slutbrugerene.

At ignorere udfasninger

Når folk opgraderer fra én version til en anden, skal det være helt tydeligt, hvorvidt noget vil gå i stykker. Det skal være muligt at opgradere til en version, der opsummerer udfasninger, fjerner gamle udfasniner, og opgradere til dén version, hvor udfasningerne bliver til oprydninger.

Hvis du ikke gør andet, så notér udfasninger, fjernede funktioner og andre ødelæggende ændringer.

Forvirrende datoer

Regionale dataformater er varierende i hele verden, og det er ofte besværligt at finde et læsbart datoformat, der føles intuitivt for alle Fordelen ved datoer formatteret som 2017-07-17 er at de følger rækkefølgen for største til mindste enhed: år, måned og dag. Dette format overlapper heller ikke på en tvetydig måde med andre datoformater, der ombytter måneden og daten. Af disse årsager, og det faktum at dette datoformat er en ISO standard, er dette det anbefalede datoformat for changelog-indlæg.

Ukonsistente rettelser

En changelog, der kun nævner nogle af ændringerne, kan være lige så farlig som ikke at have en changelog. Mens mange af ændringerne måske ikke er relevante - for eksempel er det ikke være nødvendigt at notere, at vi har fjernet et enkelt mellemrum - bør væsentlige ændringer være nævnt i changeloggen. Ved inkonsekvent at anvende ændringer, kan dine brugere fejlagtigt tro, at changelog er den eneste kilde til sandhed. Det bør den være. Med store magtbeføjelser følger store forpligtigelser. At have en god changelog er at have en konsekvent opdateret changelog.

Ofte stillede spørgsmål

Er der et standard changelog-format?

Ikke rigtig. Der er GNU changelog style guide, eller two-paragraph-long GNU NEWS file. De er begge utilstrækkelige eller uhensigtsmæssige.

Dette projekt sigter efter at være en bedre changelog konvention. Det kommer af at observere god praksis i opensource-verdenen og samle disse.

Konstruktiv kritik diskussion og forbedringsforslag er velkomne.

Hvad skal changelog-filen hedde?

Kald den CHANGELOG.md. Nogle projekter bruger HISTORY, NEWS eller RELEASES.

Selvom det er nemt at mene, at navnet på changelog-filen er irrelevant, hvorfor så gøre det sværere for dine slugbrugere at finde bemærkelsesværdige ændringer?

Hvad med GitHub Releases?

Det er et godt initiativ. Releases kan bruges til at gøre simple git tags (for eksempel, et tag v1.0.0) til fyldige udgivelsesnoter ved manuelt at tilføje noter til disse eller bruge en annoteret git-tag-besked som udgivelsesnoter.

GitHub Releases laver en ikke-flytbar changelog, der kun kan vises til bruger i konteksten af GitHub. Det er muligt at få dem til at ligne Hold en changelog-formatet, men det har en tendens til at være lidt mere kompliceret.

Den nuværende version af GitHub releases er, diskutérbart, ikke særligt synlig for slutbrugere, ikke lig de typiske kapitaliserede filer (README, CONTRIBUTING, osv.). Et andet mindre problem, er at interfacet ikke tilbyder links til commit logs mellem hvert release.

Kan changelogs læses og fortolkes automatisk?

Det er besværligt, fordi folk følger vidt forskellige formater og filnavne.

Vandamme er en Ruby gem lavet af holdet bag Gemnasium, som læser og fortolker mange (men ikke alle) open source projekters changelogs.

Hvad med tilbagetrukkede udgivelser?

Tilbagetrukkede udgivelser er versioner, der er blevet trukket tilbage på grund af en seriøs fejl eller sikkerhedsbrist. Ofte vises disse versioner slet ikke i changelogs. Det bør de. Dette er hvordan du bør vise dem:

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

Notationen [YANKED], er højlydt af en årsag: Det er vigtig information for folk. Siden den er pakket ind i klammer, er den nemmere at fortolke og læse systematiseret.

Bør man nogensinde omskrive en changelog?

Klart! Der er altid gode grunde til at forbedre en changelog. Jeg åbner jævnligt pull-requests, der tilføjer manglende releases til open source projekter uden en vedligeholdt changelog.

Det er også muligt, at du vil opdage at du har glemt at addressere en ødelæggende rettelse i noterne for en version. Det er selvfølgelig vigtigt at du opdaterer en changelog i disse tilfælde.

Hvordan kan jeg hjælpe til?

Dette dokument er ikke sandheden; det er min velovervejede mening sammen med information og eksempler jeg har samlet.

Det er fordi, jeg gerne vil have at vores fællesskab når en konsensus. Jeg mener at diskussionen er lige så vigtig som slutresultatet.

Så, vær med!

Samtaler

Jeg var med i The Changelog podcast for at snakke om, hvorfor vedligeholdere og bidragsydere bør bekymre sig om changelogs og også om motivationen bag dette projekt.

Die neuste version (1.1.0) ist noch nicht auf Deutsch verfügbar, aber du kannst sie dir auf Englisch durchlesen und bei der Übersetzung mithelfen.

Führe ein CHANGELOG

Lass Deine Freunde nicht CHANGELOGs mit git logs füllen™

Version 0.3.0

Was ist ein Changelog?

Ein Changelog ist eine Datei, welche eine handgepflegte, chronologisch sortierte Liste aller erheblichen Änderungen enthält, die zwischen Veröffentlichungen (oder Versionen) des Projekts umgesetzt wurden.

# 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.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?".

Was ist der Zweck eines Changelogs?

Es Benutzern und Entwicklern einfacher zu machen, gerade die beachtenswerten Änderungen, welche zwischen Veröffentlichungen (oder Versionen) des Projekts gemacht wurden, zu sehen.

Warum sollte mich das kümmern?

Weil Software-Werkzeuge für Menschen gemacht sind. Wenn es Dich nicht kümmert, warum trägst Du dann zu Open Source bei? Wenn Du tief in Dich gehst, findest Du bestimmt einen kleinen Teil, dem das wichtig ist.

Ich habe mit Adam Stacoviak and Jerod Santo im The Changelog-Podcast (passt, oder?) darüber gesprochen (Englisch), weshalb sich Entwickler darum kümmern sollten und über die Beweggründe hinter diesem Projekt. Falls Du die Zeit hast (1:06), es lohnt sich, reinzuhören.

Was macht ein gutes Changelog aus?

Schön, dass Du fragst.

Ein gutes Changelog hält sich an die folgenden Prinzipien:

Wie kann ich den Aufwand so klein wie möglich halten?

Hab immer einen "Unreleased"-Abschnitt zuoberst, um Änderungen im Auge zu behalten.

Dies verfolgt zwei Ziele:

Was bringt Einhörner zum weinen?

Also… Schauen wir uns das an.

Das war noch nicht alles. Hilf mir, diese Einhorn-Tränen zu sammeln und eröffne ein Issue oder einen Pull-Request.

Gibt es ein standardisiertes Changelog-Format?

Leider nicht. Beruhige Dich. Ich weiss, dass Du wie wild nach dem Link für den GNU Changelog Styleguide oder den zwei Absätze langen GNU NEWS-Datei "Leitfaden" suchst. Der GNU Styleguide ist ein guter Anfang, aber er ist leider sehr naiv. Es ist sicher nichts falsch daran, naiv zu zu sein, aber beim Verfassen eines Leitfadens ist es nicht wirklich hilfreich. Vor allem nicht, wenn es viele Spezialfälle zu beachten gibt.

Dieses Projekt enthält das, wovon ich hoffe, dass es zu einer besseren CHANGELOG-Datei-Konvention wird. Ich glaube nicht, dass der status quo gut genug ist, und ich denke, dass wir als Community eine bessere Konvention entwickeln können, wenn wir Bewährtes aus echten Software-Projekten entnehmen. Schau Dich um und denk daran, dass Diskussionen und Verbesserungsvorschläge sehr willkommen sind!

Wie soll ich meine Changelog-Datei nennen?

Nun, falls Du es noch nicht am Beispiel oben gesehen hast, CHANGELOG.md ist bisher die beste Konvention.

Einige Projekte nutzen auch HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.

Es ist ein Chaos. Alle diese Namen machen es nur schwerer, die Datei zu finden.

Wieso sollte man nicht einfach ein git log Diff verwenden?

Weil log Diffs voller unnötiger Information sind - von Natur aus. Sie wären nicht einmal ein geeignetes Changelog in einem hypothetischen Projekt, welches von perfekten Menschen geführt wird, welche sich niemals vertippen, niemals vergessen, neue Dateien zu comitten und nie einen Teil eines Refactorings übersehen. Der Zweck eines Commits ist es, einen atomaren Schritt eines Prozesses zu dokumentieren, welcher den Code von einem Zustand in den nächsten bringt. Der Zweck eines Changelogs ist es, die nennenswerten Veränderungen zwischen diesen Zuständen zu dokumentieren.

Der Unterschied zwischen dem Changelog und dem Commit-Log ist wie der Unterschied zwischen guten Kommentaren und dem Code selbst: Das eine beschreibt das wieso, das andere das wie.

Kann man Changelogs automatisiert parsen?

Es ist nicht einfach, weil äusserst unterschiedliche Formate und Dateinamen verwendet werden.

Vandamme ist ein Ruby gem vom Gemnasium-Team, welches viele (aber nicht alle) Changelogs von Open-Source-Projekten parsen kann.

Wieso schreibst Du mal "CHANGELOG" und mal "Changelog"?

"CHANGELOG" ist der Name der Datei selbst. Es ist ein bisschen laut, aber es ist eine historische Konvention, welche von vielen Open-Source-Projekten angewendet wird. Andere Beispiele von ähnlichen Dateien sind README, LICENSE und CONTRIBUTING.

Die Grossschreibung (welche in alten Betriebssystemen dafür gesorgt hat, dass die Dateien zuerst aufgelistet wurden) wird verwendet, um die Aufmerksamkeit auf diese Dateien zu lenken. Da sie wichtige Metadaten über das Projekt enthalten, können sie wichtig für jeden sein, der das Projekt gerne benutzen oder mitentwickeln möchte, ähnlich wie Open-Source-Projekt-Badges.

Wenn ich über ein "Changelog" spreche, dann meine ich die Funktion der Datei: das Festhalten von Änderungen.

Wie sieht es mit zurückgezogenen Releases aus?

Sogenannte "Yanked Releases" sind Versionen, welche wegen schwerwiegenden Bugs oder Sicherheitsproblemen zurückgezogen werden mussten. Häufig kommen diese im Changelog gar nicht vor. Das sollten sie aber. So solltest Du diese darstellen:

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

Das [YANKED]-Tag ist aus einem guten Grund laut. Es ist wichtig, dass es wahrgenommen wird. Dass es von Klammern umfasst ist, vereinfacht auch das automatisierte Parsen.

Sollte ich ein Changelog je umschreiben?

Klar. Es gibt immer gute Gründe, ein Changelog zu verbessern. Ich öffne regelmässig Pull Requests um Open-Source-Projekten mit schlecht gewarteten Changelogs fehlende Releases hinzuzufügen.

Es ist auch möglich, dass Du eine wichtige Änderung vergessen hast, in einer Version zu erwähnen. Natürlich ist es in diesem Fall wichtig, das Changelog zu aktualisieren.

Wie kann ich mithelfen?

Dieses Dokument ist nicht die Wahrheit; Es ist meine wohl überlegte Meinung, zusammen mit von mir zusammengetragenen Informationen und Beispielen. Obwohl ich im GitHub-Repository ein CHANGELOG führe, habe ich keine echten Releases oder klare zu befolgenden Regeln geschrieben (wie dies zum Beispiel SemVer.org tut).

Das ist so, weil ich möchte, dass die Community sich einig wird. Ich glaube, dass die Diskussion genau so wichtig wie das Endresultat ist.

Deshalb pack bitte mit an.

Die neuste version (1.1.0) ist noch nicht auf Deutsch verfügbar, aber du kannst sie dir auf Englisch durchlesen und bei der Übersetzung mithelfen.

Führe ein CHANGELOG

Lass Deine Freunde nicht CHANGELOGs mit git logs füllen™

Version 0.3.0

Was ist ein Changelog?

Ein Changelog ist eine Datei, welche eine handgepflegte, chronologisch sortierte Liste aller erheblichen Änderungen enthält, die zwischen Veröffentlichungen (oder Versionen) des Projekts umgesetzt wurden.

# 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.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?".

Was ist der Zweck eines Changelogs?

Es Benutzern und Entwicklern einfacher zu machen, gerade die beachtenswerten Änderungen, welche zwischen Veröffentlichungen (oder Versionen) des Projekts gemacht wurden, zu sehen.

Warum sollte mich das kümmern?

Weil Software-Werkzeuge für Menschen gemacht sind. Wenn es Dich nicht kümmert, warum trägst Du dann zu Open Source bei? Wenn Du tief in Dich gehst, findest Du bestimmt einen kleinen Teil, dem das wichtig ist.

Ich habe mit Adam Stacoviak and Jerod Santo im The Changelog-Podcast (passt, oder?) darüber gesprochen (Englisch), weshalb sich Entwickler darum kümmern sollten und über die Beweggründe hinter diesem Projekt. Falls Du die Zeit hast (1:06), es lohnt sich, reinzuhören.

Was macht ein gutes Changelog aus?

Schön, dass Du fragst.

Ein gutes Changelog hält sich an die folgenden Prinzipien:

Wie kann ich den Aufwand so klein wie möglich halten?

Hab immer einen "Unreleased"-Abschnitt zuoberst, um Änderungen im Auge zu behalten.

Dies verfolgt zwei Ziele:

Was bringt Einhörner zum weinen?

Also… Schauen wir uns das an.

Das war noch nicht alles. Hilf mir, diese Einhorn-Tränen zu sammeln und eröffne ein Issue oder einen Pull-Request.

Gibt es ein standardisiertes Changelog-Format?

Leider nicht. Beruhige Dich. Ich weiss, dass Du wie wild nach dem Link für den GNU Changelog Styleguide oder den zwei Absätze langen GNU NEWS-Datei "Leitfaden" suchst. Der GNU Styleguide ist ein guter Anfang, aber er ist leider sehr naiv. Es ist sicher nichts falsch daran, naiv zu zu sein, aber beim Verfassen eines Leitfadens ist es nicht wirklich hilfreich. Vor allem nicht, wenn es viele Spezialfälle zu beachten gibt.

Dieses Projekt enthält das, wovon ich hoffe, dass es zu einer besseren CHANGELOG-Datei-Konvention wird. Ich glaube nicht, dass der status quo gut genug ist, und ich denke, dass wir als Community eine bessere Konvention entwickeln können, wenn wir Bewährtes aus echten Software-Projekten entnehmen. Schau Dich um und denk daran, dass Diskussionen und Verbesserungsvorschläge sehr willkommen sind!

Wie soll ich meine Changelog-Datei nennen?

Nun, falls Du es noch nicht am Beispiel oben gesehen hast, CHANGELOG.md ist bisher die beste Konvention.

Einige Projekte nutzen auch HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.

Es ist ein Chaos. Alle diese Namen machen es nur schwerer, die Datei zu finden.

Wieso sollte man nicht einfach ein git log Diff verwenden?

Weil log Diffs voller unnötiger Information sind - von Natur aus. Sie wären nicht einmal ein geeignetes Changelog in einem hypothetischen Projekt, welches von perfekten Menschen geführt wird, welche sich niemals vertippen, niemals vergessen, neue Dateien zu comitten und nie einen Teil eines Refactorings übersehen. Der Zweck eines Commits ist es, einen atomaren Schritt eines Prozesses zu dokumentieren, welcher den Code von einem Zustand in den nächsten bringt. Der Zweck eines Changelogs ist es, die nennenswerten Veränderungen zwischen diesen Zuständen zu dokumentieren.

Der Unterschied zwischen dem Changelog und dem Commit-Log ist wie der Unterschied zwischen guten Kommentaren und dem Code selbst: Das eine beschreibt das wieso, das andere das wie.

Kann man Changelogs automatisiert parsen?

Es ist nicht einfach, weil äusserst unterschiedliche Formate und Dateinamen verwendet werden.

Vandamme ist ein Ruby gem vom Gemnasium-Team, welches viele (aber nicht alle) Changelogs von Open-Source-Projekten parsen kann.

Wieso schreibst Du mal "CHANGELOG" und mal "Changelog"?

"CHANGELOG" ist der Name der Datei selbst. Es ist ein bisschen laut, aber es ist eine historische Konvention, welche von vielen Open-Source-Projekten angewendet wird. Andere Beispiele von ähnlichen Dateien sind README, LICENSE und CONTRIBUTING.

Die Grossschreibung (welche in alten Betriebssystemen dafür gesorgt hat, dass die Dateien zuerst aufgelistet wurden) wird verwendet, um die Aufmerksamkeit auf diese Dateien zu lenken. Da sie wichtige Metadaten über das Projekt enthalten, können sie wichtig für jeden sein, der das Projekt gerne benutzen oder mitentwickeln möchte, ähnlich wie Open-Source-Projekt-Badges.

Wenn ich über ein "Changelog" spreche, dann meine ich die Funktion der Datei: das Festhalten von Änderungen.

Wie sieht es mit zurückgezogenen Releases aus?

Sogenannte "Yanked Releases" sind Versionen, welche wegen schwerwiegenden Bugs oder Sicherheitsproblemen zurückgezogen werden mussten. Häufig kommen diese im Changelog gar nicht vor. Das sollten sie aber. So solltest Du diese darstellen:

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

Das [YANKED]-Tag ist aus einem guten Grund laut. Es ist wichtig, dass es wahrgenommen wird. Dass es von Klammern umfasst ist, vereinfacht auch das automatisierte Parsen.

Sollte ich ein Changelog je umschreiben?

Klar. Es gibt immer gute Gründe, ein Changelog zu verbessern. Ich öffne regelmässig Pull Requests um Open-Source-Projekten mit schlecht gewarteten Changelogs fehlende Releases hinzuzufügen.

Es ist auch möglich, dass Du eine wichtige Änderung vergessen hast, in einer Version zu erwähnen. Natürlich ist es in diesem Fall wichtig, das Changelog zu aktualisieren.

Wie kann ich mithelfen?

Dieses Dokument ist nicht die Wahrheit; Es ist meine wohl überlegte Meinung, zusammen mit von mir zusammengetragenen Informationen und Beispielen. Obwohl ich im GitHub-Repository ein CHANGELOG führe, habe ich keine echten Releases oder klare zu befolgenden Regeln geschrieben (wie dies zum Beispiel SemVer.org tut).

Das ist so, weil ich möchte, dass die Community sich einig wird. Ich glaube, dass die Diskussion genau so wichtig wie das Endresultat ist.

Deshalb pack bitte mit an.

Die neuste version (1.1.0) ist noch nicht auf Deutsch verfügbar, aber du kannst sie dir auf Englisch durchlesen und bei der Übersetzung mithelfen.

Führe ein CHANGELOG

Lass Deine Freunde nicht CHANGELOGs mit git logs füllen.

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

## [Unreleased]

## [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

Was ist ein Changelog?

Ein Changelog ist eine Datei, die eine handgepflegte, chronologisch sortierte Liste aller erheblichen Änderungen enthält, die zwischen einzelnen Veröffentlichungen (oder Versionen) des Projekts umgesetzt wurden.

Was ist der Zweck eines Changelogs?

Ein Changelog soll es Benutzern und Entwicklern einfacher machen, gerade die beachtenswerten Änderungen, die zwischen Veröffentlichungen (oder Versionen) des Projekts gemacht wurden, zu sehen.

Wer braucht schon ein Changelog?

Menschen brauchen es. Seien es Konsumenten oder Entwickler, die Endnutzer der Software sind Menschen, die es interessiert, was in der Software passiert. Wenn sich die Software ändert, dann wollen diese Menschen wissen, wie und warum sie sich ändert.

Wie erstelle ich einen guten Changelog?

Grundlegende Prinzipien

  • Changelogs werden für Menschen geschrieben, nicht für Maschinen.
  • Für jede einzelne Version sollte es einen Eintrag geben.
  • Änderungen der selben Art sollten in Bereiche gruppiert werden.
  • Versionen und Bereiche sollten verlinkt werden können.
  • Die neuste Version kommt als erstes.
  • Das Release-Datum jeder Version muss angegeben sein.
  • Gib an, ob du dich an die Semantische Versionierung hältst.

Arten von Änderungen

  • Added für neue Features.
  • Changed für Änderungen an der bestehenden Funktionalität.
  • Deprecated für Features, die in zukünftigen Versionen entfernt werden.
  • Removed für Deprecated-Features, die in dieser Version entfernt wurden.
  • Fixed für alle Bug-Fixes.
  • Security um Benutzer im Fall von geschlossenen Sicherheitslücken zu einer Aktualisierung aufzufordern.

Wie kann ich den Aufwand der Changelog-Pflege so klein wie möglich halten?

Habe immer einen Unreleased-Abschnitt über der neusten Version, um zukünftige Änderungen im Auge zu behalten.

Dies hat zwei Vorteile:

  • Menschen können sehen, welche Änderungen sie mit dem nächsten Release zu erwarten haben.
  • Wenn der Zeitpunkt für den Release gekommen ist, kannst du den Inhalt des Unreleased-Abschnitts in den neuen Release-Abschnitt verschieben.

Kann man beim Changelog etwas falsch machen?

Ja. Hier sind einige Dinge, die eher unbrauchbar sind.

Einen Diff von Commit-Logs ausgeben

Commit-Logs in einem Changelog sind eine schlechte Idee: Sie beinhalten lauter überflüssige Dinge, wie Merge-Commit, Commits mit schlechten Bezeichnungen, Änderungen an der Dokumentation, etc.

Der Sinn eines Commits ist die Entwicklung des Source Code zu dokumentieren. Manche Projekte haben saubere Commits, andere nicht.

Der Sinn eines Changelog-Eintrags ist die Dokumentation der merkbaren Unterschiede, die meist über mehrere Commits hinweg entstanden sind, dem Endnutzer klar und deutlich zu kommunizieren.

Features ohne Deprecation-Warnung entfernen

Wenn der Endnutzer auf eine neue Version upgradet, sollte ihm unmissverständlich klar gemacht werden, wenn etwas kaputt gehen wird. Es sollte immer möglich sein, zu einer Version zu upgraden, die die zu entfernenden Features auflistet, um so in seinem Source Code auf diese Features zu verzichten. Anschließend sollte man auf eine Version upgraden können, in der die Features entfernt wurden.

Auch wenn du sonst nichts geändert hast, liste trotzdem alle veralteten und entfernten Features, sowie jede funktionsgefährdende Änderung in deinem Changelog auf.

Verwirrende Datumsformate

In den USA setzen die Menschen den Monat an den Anfang eines Datums (06-02-2012 für den 2. Juni 2012), wohingegen viele Menschen im Rest der Welt ein roboterhaft aussehendes 2 June 2012 schreiben, aber es völlig unterschiedlich aussprechen. 2012-06-02 folgt der Logik vom größten zum kleinsten Wert, kann nicht mit anderen Formaten verwechselt werden und ist ein ISO Standard. Deshalb ist es das empfohlene Datumsformat in Changelogs.

Häufig gestellte Fragen

Gibt es ein standardisiertes Changelog-Format?

Leider nicht. Es gibt zwar den GNU Changelog Styleguide oder den zwei Absätze langen GNU NEWS-Datei "Leitfaden". Beide sind aber unzureichend.

Dieses Projekt versucht eine bessere Changelog Konvention zu sein. Dazu beobachten wir bewährte Praktiken aus der Open Source Community und tragen sie zusammen.

Gesunde Kritik, Diskussionen und Verbesserungsvorschläge sind herzlich willkommen.

Wie sollte die Changelog-Datei benannt sein?

Nenne sie CHANGELOG.md. Manche Projekte verwenden auch HISTORY, NEWS oder RELEASES.

Man könnte zwar meinen, dass der Name der Changelog-Datei keine große Bedeutung hat, aber warum sollte man es den Endnutzern nicht einfach machen, die Änderungen des Projekts zu finden, indem man einen einheitlichen Namen verwendet?

Was ist mit GitHub Releases?

Prinzipiell sind GitHub Releases eine gute Sache. Sie können dazu benutzt werden, um einfache Git Tags (zum Beispiel einen Tag namens v1.0.0) mit vielen Hinweisen zum Release auszustatten, indem man sie manuell bearbeitet, oder die Änderungen in eine Git Tag Nachricht schreibt, wo sie durch GitHub automatisch in die Release-Notizen gesetzt werden.

Leider lassen sich GitHub Releases aber nicht so einfach exportieren und sind nur über GitHub selber zu lesen. Man kann sie auch so gestalten, dass sie dem Keep a Changelog Format sehr ähnlich sehen, aber dazu betreibt man in der Regel einen größeren Aufwand.

Die derzeitige Version der GitHub Releases sind außerdem nicht leicht durch die Endnutzer zu finden, ganz im Gegenteil zu den typischerweise großgeschriebenen Dateien (README, CONTRIBUTING, etc.). Ein weiterer kleiner Nachteil ist, dass das Web Interface zurzeit keinen Link anbietet, um die Commits zwischen einzelnen Releases miteinander zu vergleichen.

Können Changelogs automatisiert ausgelesen werden?

Es ist schwierig, weil Menschen meist unterschiedliche Formate und Dateinamen verwenden.

Vandamme ist ein Ruby gem erstellt vom Gemnasium Team, das viele (aber nicht alle) Changelogs von Open-Source-Projekten einlesen kann.

Wie sieht es mit zurückgezogenen Releases aus?

Sogenannte "Yanked Releases" sind Versionen, welche wegen schwerwiegenden Bugs oder Sicherheitsproblemen zurückgezogen werden mussten. Häufig kommen diese im Changelog gar nicht vor, aber das sollten sie. So solltest Du diese Versionen darstellen:

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

Der [YANKED] ist nicht ohne Grund großgeschrieben. Es ist wichtig, dass sie von Menschen bemerkt werden. Weil er von eckigen Klammern umgeben ist, kann man sie außerdem einfacher automatisiert einlesen.

Sollte ich ein Changelog je umschreiben?

Klar. Es gibt immer gute Gründe, ein Changelog zu verbessern. Ich öffne regelmässig Pull Requests, um Open-Source-Projekten mit schlecht gewarteten Changelogs fehlende Releases hinzuzufügen.

Es ist auch möglich, dass Du eine wichtige Änderung vergessen hast, in einer Version zu erwähnen. Natürlich ist es in diesem Fall wichtig, das Changelog zu aktualisieren.

Wie kann ich mithelfen?

Dieses Dokument ist nicht die Wahrheit. Es ist meine wohl überlegte Meinung, zusammen mit von mir zusammengetragenen Informationen und Beispielen.

So möchte ich erreichen, dass die Community einen Konsens findet. Ich glaube, dass die Disskussion genauso wichtig ist wie das Endergebnis.

Also bitte bring dich ein.

Gespräche

Ich habe im The Changelog podcast darüber gesprochen, warum sich Entwickler und Mitwirkende eines Projekts um ein Changelog kümmern sollten, sowie meine Motivationen hinter diesem Projekt erklärt.

Die neuste version (1.1.0) ist noch nicht auf Deutsch verfügbar, aber du kannst sie dir auf Englisch durchlesen und bei der Übersetzung mithelfen.

Führe ein CHANGELOG

Lass Deine Freunde nicht CHANGELOGs mit git logs füllen.

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

## [Unreleased]

## [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

Was ist ein Changelog?

Ein Changelog ist eine Datei, die eine handgepflegte, chronologisch sortierte Liste aller erheblichen Änderungen enthält, die zwischen einzelnen Veröffentlichungen (oder Versionen) des Projekts umgesetzt wurden.

Was ist der Zweck eines Changelogs?

Ein Changelog soll es Benutzern und Entwicklern einfacher machen, gerade die beachtenswerten Änderungen, die zwischen Veröffentlichungen (oder Versionen) des Projekts gemacht wurden, zu sehen.

Wer braucht schon ein Changelog?

Menschen brauchen es. Seien es Konsumenten oder Entwickler, die Endnutzer der Software sind Menschen, die es interessiert, was in der Software passiert. Wenn sich die Software ändert, dann wollen diese Menschen wissen, wie und warum sie sich ändert.

Wie erstelle ich einen guten Changelog?

Grundlegende Prinzipien

  • Changelogs werden für Menschen geschrieben, nicht für Maschinen.
  • Für jede einzelne Version sollte es einen Eintrag geben.
  • Änderungen der selben Art sollten in Bereiche gruppiert werden.
  • Versionen und Bereiche sollten verlinkt werden können.
  • Die neuste Version kommt als erstes.
  • Das Release-Datum jeder Version muss angegeben sein.
  • Gib an, ob du dich an die Semantische Versionierung hältst.

Arten von Änderungen

  • Added für neue Features.
  • Changed für Änderungen an der bestehenden Funktionalität.
  • Deprecated für Features, die in zukünftigen Versionen entfernt werden.
  • Removed für Deprecated-Features, die in dieser Version entfernt wurden.
  • Fixed für alle Bug-Fixes.
  • Security um Benutzer im Fall von geschlossenen Sicherheitslücken zu einer Aktualisierung aufzufordern.

Wie kann ich den Aufwand der Changelog-Pflege so klein wie möglich halten?

Habe immer einen Unreleased-Abschnitt über der neusten Version, um zukünftige Änderungen im Auge zu behalten.

Dies hat zwei Vorteile:

  • Menschen können sehen, welche Änderungen sie mit dem nächsten Release zu erwarten haben.
  • Wenn der Zeitpunkt für den Release gekommen ist, kannst du den Inhalt des Unreleased-Abschnitts in den neuen Release-Abschnitt verschieben.

Kann man beim Changelog etwas falsch machen?

Ja. Hier sind einige Dinge, die eher unbrauchbar sind.

Einen Diff von Commit-Logs ausgeben

Commit-Logs in einem Changelog sind eine schlechte Idee: Sie beinhalten lauter überflüssige Dinge, wie Merge-Commit, Commits mit schlechten Bezeichnungen, Änderungen an der Dokumentation, etc.

Der Sinn eines Commits ist die Entwicklung des Source Code zu dokumentieren. Manche Projekte haben saubere Commits, andere nicht.

Der Sinn eines Changelog-Eintrags ist die Dokumentation der merkbaren Unterschiede, die meist über mehrere Commits hinweg entstanden sind, dem Endnutzer klar und deutlich zu kommunizieren.

Features ohne Deprecation-Warnung entfernen

Wenn der Endnutzer auf eine neue Version upgradet, sollte ihm unmissverständlich klar gemacht werden, wenn etwas kaputt gehen wird. Es sollte immer möglich sein, zu einer Version zu upgraden, die die zu entfernenden Features auflistet, um so in seinem Source Code auf diese Features zu verzichten. Anschließend sollte man auf eine Version upgraden können, in der die Features entfernt wurden.

Auch wenn du sonst nichts geändert hast, liste trotzdem alle veralteten und entfernten Features, sowie jede funktionsgefährdende Änderung in deinem Changelog auf.

Verwirrende Datumsformate

In den USA setzen die Menschen den Monat an den Anfang eines Datums (06-02-2012 für den 2. Juni 2012), wohingegen viele Menschen im Rest der Welt ein roboterhaft aussehendes 2 June 2012 schreiben, aber es völlig unterschiedlich aussprechen. 2012-06-02 folgt der Logik vom größten zum kleinsten Wert, kann nicht mit anderen Formaten verwechselt werden und ist ein ISO Standard. Deshalb ist es das empfohlene Datumsformat in Changelogs.

Häufig gestellte Fragen

Gibt es ein standardisiertes Changelog-Format?

Leider nicht. Es gibt zwar den GNU Changelog Styleguide oder den zwei Absätze langen GNU NEWS-Datei "Leitfaden". Beide sind aber unzureichend.

Dieses Projekt versucht eine bessere Changelog Konvention zu sein. Dazu beobachten wir bewährte Praktiken aus der Open Source Community und tragen sie zusammen.

Gesunde Kritik, Diskussionen und Verbesserungsvorschläge sind herzlich willkommen.

Wie sollte die Changelog-Datei benannt sein?

Nenne sie CHANGELOG.md. Manche Projekte verwenden auch HISTORY, NEWS oder RELEASES.

Man könnte zwar meinen, dass der Name der Changelog-Datei keine große Bedeutung hat, aber warum sollte man es den Endnutzern nicht einfach machen, die Änderungen des Projekts zu finden, indem man einen einheitlichen Namen verwendet?

Was ist mit GitHub Releases?

Prinzipiell sind GitHub Releases eine gute Sache. Sie können dazu benutzt werden, um einfache Git Tags (zum Beispiel einen Tag namens v1.0.0) mit vielen Hinweisen zum Release auszustatten, indem man sie manuell bearbeitet, oder die Änderungen in eine Git Tag Nachricht schreibt, wo sie durch GitHub automatisch in die Release-Notizen gesetzt werden.

Leider lassen sich GitHub Releases aber nicht so einfach exportieren und sind nur über GitHub selber zu lesen. Man kann sie auch so gestalten, dass sie dem Keep a Changelog Format sehr ähnlich sehen, aber dazu betreibt man in der Regel einen größeren Aufwand.

Die derzeitige Version der GitHub Releases sind außerdem nicht leicht durch die Endnutzer zu finden, ganz im Gegenteil zu den typischerweise großgeschriebenen Dateien (README, CONTRIBUTING, etc.). Ein weiterer kleiner Nachteil ist, dass das Web Interface zurzeit keinen Link anbietet, um die Commits zwischen einzelnen Releases miteinander zu vergleichen.

Können Changelogs automatisiert ausgelesen werden?

Es ist schwierig, weil Menschen meist unterschiedliche Formate und Dateinamen verwenden.

Vandamme ist ein Ruby gem erstellt vom Gemnasium Team, das viele (aber nicht alle) Changelogs von Open-Source-Projekten einlesen kann.

Wie sieht es mit zurückgezogenen Releases aus?

Sogenannte "Yanked Releases" sind Versionen, welche wegen schwerwiegenden Bugs oder Sicherheitsproblemen zurückgezogen werden mussten. Häufig kommen diese im Changelog gar nicht vor, aber das sollten sie. So solltest Du diese Versionen darstellen:

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

Der [YANKED] ist nicht ohne Grund großgeschrieben. Es ist wichtig, dass sie von Menschen bemerkt werden. Weil er von eckigen Klammern umgeben ist, kann man sie außerdem einfacher automatisiert einlesen.

Sollte ich ein Changelog je umschreiben?

Klar. Es gibt immer gute Gründe, ein Changelog zu verbessern. Ich öffne regelmässig Pull Requests, um Open-Source-Projekten mit schlecht gewarteten Changelogs fehlende Releases hinzuzufügen.

Es ist auch möglich, dass Du eine wichtige Änderung vergessen hast, in einer Version zu erwähnen. Natürlich ist es in diesem Fall wichtig, das Changelog zu aktualisieren.

Wie kann ich mithelfen?

Dieses Dokument ist nicht die Wahrheit. Es ist meine wohl überlegte Meinung, zusammen mit von mir zusammengetragenen Informationen und Beispielen.

So möchte ich erreichen, dass die Community einen Konsens findet. Ich glaube, dass die Disskussion genauso wichtig ist wie das Endergebnis.

Also bitte bring dich ein.

Gespräche

Ich habe im The Changelog podcast darüber gesprochen, warum sich Entwickler und Mitwirkende eines Projekts um ein Changelog kümmern sollten, sowie meine Motivationen hinter diesem Projekt erklärt.

A new version is available: English 1.1.0

Keep a CHANGELOG

Don’t let your friends dump git logs into CHANGELOGs™

Version 0.3.0

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.

# 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.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?".

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 (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:

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:

What makes unicorns cry?

Alright…let’s get into it.

There’s more. Help me collect those unicorn tears by opening an issue 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. 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!

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 is a Ruby gem created by the 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, LICENSE, and 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.

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, I have purposefully not created a proper release or clear list of rules to follow (as SemVer.org 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.

A new version is available: English 1.1.0

Keep a CHANGELOG

Don’t let your friends dump git logs into CHANGELOGs™

Version 0.3.0

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.

# 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.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?".

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 (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:

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:

What makes unicorns cry?

Alright…let’s get into it.

There’s more. Help me collect those unicorn tears by opening an issue 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. 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!

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 is a Ruby gem created by the 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, LICENSE, and 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.

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, I have purposefully not created a proper release or clear list of rules to follow (as SemVer.org 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.

A new version is available: English 1.1.0

Keep a Changelog

Don’t let your friends dump git logs into changelogs.

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

## [Unreleased]

## [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

What is a changelog?

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

Why keep a changelog?

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.

Who needs a changelog?

People do. Whether consumers or developers, the end users of software are human beings who care about what's in the software. When the software changes, people want to know why and how.

How do I make a good changelog?

Guiding Principles

  • Changelogs are for humans, not machines.
  • There should be an entry for every single version.
  • The same types of changes should be grouped.
  • Versions and sections should be linkable.
  • The latest version comes first.
  • The release date of each version is displayed.
  • Mention whether you follow Semantic Versioning.

Types of changes

  • Added for new features.
  • Changed for changes in existing functionality.
  • Deprecated for soon-to-be removed features.
  • Removed for now removed features.
  • Fixed for any bug fixes.
  • Security in case of vulnerabilities.

How can I reduce the effort required to maintain a changelog?

Keep an Unreleased section at the top to track upcoming changes.

This serves two purposes:

  • People can see what changes they might expect in upcoming releases
  • At release time, you can move the Unreleased section changes into a new release version section.

Can changelogs be bad?

Yes. Here are a few ways they can be less than useful.

Commit log diffs

Using commit log diffs as changelogs is a bad idea: they're full of noise. Things like merge commits, commits with obscure titles, documentation changes, etc.

The purpose of a commit is to document a step in the evolution of the source code. Some projects clean up commits, some don't.

The purpose of a changelog entry is to document the noteworthy difference, often across multiple commits, to communicate them clearly to end users.

Ignoring Deprecations

When people upgrade from one version to another, it should be painfully clear when something will break. It should be possible to upgrade to a version that lists deprecations, remove what's deprecated, then upgrade to the version where the deprecations become removals.

If you do nothing else, list deprecations, removals, and any breaking changes in your changelog.

Confusing Dates

Regional date formats vary throughout the world and it's often difficult to find a human-friendly date format that feels intuitive to everyone. The advantage of dates formatted like 2017-07-17 is that they follow the order of largest to smallest units: year, month, and day. This format also doesn't overlap in ambiguous ways with other date formats, unlike some regional formats that switch the position of month and day numbers. These reasons, and the fact this date format is an ISO standard, are why it is the recommended date format for changelog entries.

Frequently Asked Questions

Is there a standard changelog format?

Not really. There's the GNU changelog style guide, or the two-paragraph-long GNU NEWS file "guideline". Both are inadequate or insufficient.

This project aims to be a better changelog convention. It comes from observing good practices in the open source community and gathering them.

Healthy criticism, discussion and suggestions for improvements are welcome.

What should the changelog file be named?

Call it CHANGELOG.md. Some projects use HISTORY, NEWS or RELEASES.

While it's easy to think that the name of your changelog file doesn't matter that much, why make it harder for your end users to consistently find notable changes?

What about GitHub Releases?

It's a great initiative. Releases can be used to turn simple git tags (for example a tag named v1.0.0) into rich release notes by manually adding release notes or it can pull annotated git tag messages and turn them into notes.

GitHub Releases create a non-portable changelog that can only be displayed to users within the context of GitHub. It's possible to make them look very much like the Keep a Changelog format, but it tends to be a bit more involved.

The current version of GitHub releases is also arguably not very discoverable by end-users, unlike the typical uppercase files (README, CONTRIBUTING, etc.). Another minor issue is that the interface doesn't currently offer links to commit logs between each release.

Can changelogs be automatically parsed?

It’s difficult, because people follow wildly different formats and file names.

Vandamme is a Ruby gem created by the Gemnasium team and which parses many (but not all) open source project changelogs.

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 changelog?

Sure. There are always good reasons to improve a changelog. I regularly open pull requests to add missing releases to open source projects with unmaintained changelogs.

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 changelog 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.

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.

Conversations

I went on The Changelog podcast to talk about why maintainers and contributors should care about changelogs, and also about the motivations behind this project.

A new version is available: English 1.1.0

Keep a Changelog

Don’t let your friends dump git logs into changelogs.

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

## [Unreleased]

## [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

What is a changelog?

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

Why keep a changelog?

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.

Who needs a changelog?

People do. Whether consumers or developers, the end users of software are human beings who care about what's in the software. When the software changes, people want to know why and how.

How do I make a good changelog?

Guiding Principles

  • Changelogs are for humans, not machines.
  • There should be an entry for every single version.
  • The same types of changes should be grouped.
  • Versions and sections should be linkable.
  • The latest version comes first.
  • The release date of each version is displayed.
  • Mention whether you follow Semantic Versioning.

Types of changes

  • Added for new features.
  • Changed for changes in existing functionality.
  • Deprecated for soon-to-be removed features.
  • Removed for now removed features.
  • Fixed for any bug fixes.
  • Security in case of vulnerabilities.

How can I reduce the effort required to maintain a changelog?

Keep an Unreleased section at the top to track upcoming changes.

This serves two purposes:

  • People can see what changes they might expect in upcoming releases
  • At release time, you can move the Unreleased section changes into a new release version section.

Can changelogs be bad?

Yes. Here are a few ways they can be less than useful.

Commit log diffs

Using commit log diffs as changelogs is a bad idea: they're full of noise. Things like merge commits, commits with obscure titles, documentation changes, etc.

The purpose of a commit is to document a step in the evolution of the source code. Some projects clean up commits, some don't.

The purpose of a changelog entry is to document the noteworthy difference, often across multiple commits, to communicate them clearly to end users.

Ignoring Deprecations

When people upgrade from one version to another, it should be painfully clear when something will break. It should be possible to upgrade to a version that lists deprecations, remove what's deprecated, then upgrade to the version where the deprecations become removals.

If you do nothing else, list deprecations, removals, and any breaking changes in your changelog.

Confusing Dates

Regional date formats vary throughout the world and it's often difficult to find a human-friendly date format that feels intuitive to everyone. The advantage of dates formatted like 2017-07-17 is that they follow the order of largest to smallest units: year, month, and day. This format also doesn't overlap in ambiguous ways with other date formats, unlike some regional formats that switch the position of month and day numbers. These reasons, and the fact this date format is an ISO standard, are why it is the recommended date format for changelog entries.

Frequently Asked Questions

Is there a standard changelog format?

Not really. There's the GNU changelog style guide, or the two-paragraph-long GNU NEWS file "guideline". Both are inadequate or insufficient.

This project aims to be a better changelog convention. It comes from observing good practices in the open source community and gathering them.

Healthy criticism, discussion and suggestions for improvements are welcome.

What should the changelog file be named?

Call it CHANGELOG.md. Some projects use HISTORY, NEWS or RELEASES.

While it's easy to think that the name of your changelog file doesn't matter that much, why make it harder for your end users to consistently find notable changes?

What about GitHub Releases?

It's a great initiative. Releases can be used to turn simple git tags (for example a tag named v1.0.0) into rich release notes by manually adding release notes or it can pull annotated git tag messages and turn them into notes.

GitHub Releases create a non-portable changelog that can only be displayed to users within the context of GitHub. It's possible to make them look very much like the Keep a Changelog format, but it tends to be a bit more involved.

The current version of GitHub releases is also arguably not very discoverable by end-users, unlike the typical uppercase files (README, CONTRIBUTING, etc.). Another minor issue is that the interface doesn't currently offer links to commit logs between each release.

Can changelogs be automatically parsed?

It’s difficult, because people follow wildly different formats and file names.

Vandamme is a Ruby gem created by the Gemnasium team and which parses many (but not all) open source project changelogs.

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 changelog?

Sure. There are always good reasons to improve a changelog. I regularly open pull requests to add missing releases to open source projects with unmaintained changelogs.

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 changelog 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.

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.

Conversations

I went on The Changelog podcast to talk about why maintainers and contributors should care about changelogs, and also about the motivations behind this project.

Keep a Changelog

Don’t let your friends dump git logs into changelogs.

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

## [Unreleased]

## [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

What is a changelog?

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

Why keep a changelog?

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.

Who needs a changelog?

People do. Whether consumers or developers, the end users of software are human beings who care about what's in the software. When the software changes, people want to know why and how.

How do I make a good changelog?

Guiding Principles

  • Changelogs are for humans, not machines.
  • There should be an entry for every single version.
  • The same types of changes should be grouped.
  • Versions and sections should be linkable.
  • The latest version comes first.
  • The release date of each version is displayed.
  • Mention whether you follow Semantic Versioning.

Types of changes

  • Added for new features.
  • Changed for changes in existing functionality.
  • Deprecated for soon-to-be removed features.
  • Removed for now removed features.
  • Fixed for any bug fixes.
  • Security in case of vulnerabilities.

How can I reduce the effort required to maintain a changelog?

Keep an Unreleased section at the top to track upcoming changes.

This serves two purposes:

  • People can see what changes they might expect in upcoming releases
  • At release time, you can move the Unreleased section changes into a new release version section.

Can changelogs be bad?

Yes. Here are a few ways they can be less than useful.

Commit log diffs

Using commit log diffs as changelogs is a bad idea: they're full of noise. Things like merge commits, commits with obscure titles, documentation changes, etc.

The purpose of a commit is to document a step in the evolution of the source code. Some projects clean up commits, some don't.

The purpose of a changelog entry is to document the noteworthy difference, often across multiple commits, to communicate them clearly to end users.

Ignoring Deprecations

When people upgrade from one version to another, it should be painfully clear when something will break. It should be possible to upgrade to a version that lists deprecations, remove what's deprecated, then upgrade to the version where the deprecations become removals.

If you do nothing else, list deprecations, removals, and any breaking changes in your changelog.

Confusing Dates

Regional date formats vary throughout the world and it's often difficult to find a human-friendly date format that feels intuitive to everyone. The advantage of dates formatted like 2017-07-17 is that they follow the order of largest to smallest units: year, month, and day. This format also doesn't overlap in ambiguous ways with other date formats, unlike some regional formats that switch the position of month and day numbers. These reasons, and the fact this date format is an ISO standard, are why it is the recommended date format for changelog entries.

Inconsistent Changes

A changelog which only mentions some of the changes can be as dangerous as not having a changelog. While many of the changes may not be relevant - for instance, removing a single whitespace may not need to be recorded in all instances - any important changes should be mentioned in the changelog. By inconsistently applying changes, your users may mistakenly think that the changelog is the single source of truth. It ought to be. With great power comes great responsibility - having a good changelog means having a consistently updated changelog.

Frequently Asked Questions

Is there a standard changelog format?

Not really. There's the GNU changelog style guide, or the two-paragraph-long GNU NEWS file "guideline". Both are inadequate or insufficient.

This project aims to be a better changelog convention. It comes from observing good practices in the open source community and gathering them.

Healthy criticism, discussion and suggestions for improvements are welcome.

What should the changelog file be named?

Call it CHANGELOG.md. Some projects use HISTORY, NEWS or RELEASES.

While it's easy to think that the name of your changelog file doesn't matter that much, why make it harder for your end users to consistently find notable changes?

What about GitHub Releases?

It's a great initiative. Releases can be used to turn simple git tags (for example a tag named v1.0.0) into rich release notes by manually adding release notes or it can pull annotated git tag messages and turn them into notes.

GitHub Releases create a non-portable changelog that can only be displayed to users within the context of GitHub. It's possible to make them look very much like the Keep a Changelog format, but it tends to be a bit more involved.

The current version of GitHub releases is also arguably not very discoverable by end-users, unlike the typical uppercase files (README, CONTRIBUTING, etc.). Another minor issue is that the interface doesn't currently offer links to commit logs between each release.

Can changelogs be automatically parsed?

It’s difficult, because people follow wildly different formats and file names.

Vandamme is a Ruby gem created by the Gemnasium team and which parses many (but not all) open source project changelogs.

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 changelog?

Sure. There are always good reasons to improve a changelog. I regularly open pull requests to add missing releases to open source projects with unmaintained changelogs.

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 changelog 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.

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.

Conversations

I went on The Changelog podcast to talk about why maintainers and contributors should care about changelogs, and also about the motivations behind this project.

Keep a Changelog

Don’t let your friends dump git logs into changelogs.

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

## [Unreleased]

## [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

What is a changelog?

A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of a project.

Why keep a changelog?

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.

Who needs a changelog?

People do. Whether consumers or developers, the end users of software are human beings who care about what's in the software. When the software changes, people want to know why and how.

How do I make a good changelog?

Guiding Principles

  • Changelogs are for humans, not machines.
  • There should be an entry for every single version.
  • The same types of changes should be grouped.
  • Versions and sections should be linkable.
  • The latest version comes first.
  • The release date of each version is displayed.
  • Mention whether you follow Semantic Versioning.

Types of changes

  • Added for new features.
  • Changed for changes in existing functionality.
  • Deprecated for soon-to-be removed features.
  • Removed for now removed features.
  • Fixed for any bug fixes.
  • Security in case of vulnerabilities.

How can I reduce the effort required to maintain a changelog?

Keep an Unreleased section at the top to track upcoming changes.

This serves two purposes:

  • People can see what changes they might expect in upcoming releases
  • At release time, you can move the Unreleased section changes into a new release version section.

Can changelogs be bad?

Yes. Here are a few ways they can be less than useful.

Commit log diffs

Using commit log diffs as changelogs is a bad idea: they're full of noise. Things like merge commits, commits with obscure titles, documentation changes, etc.

The purpose of a commit is to document a step in the evolution of the source code. Some projects clean up commits, some don't.

The purpose of a changelog entry is to document the noteworthy difference, often across multiple commits, to communicate them clearly to end users.

Ignoring Deprecations

When people upgrade from one version to another, it should be painfully clear when something will break. It should be possible to upgrade to a version that lists deprecations, remove what's deprecated, then upgrade to the version where the deprecations become removals.

If you do nothing else, list deprecations, removals, and any breaking changes in your changelog.

Confusing Dates

Regional date formats vary throughout the world and it's often difficult to find a human-friendly date format that feels intuitive to everyone. The advantage of dates formatted like 2017-07-17 is that they follow the order of largest to smallest units: year, month, and day. This format also doesn't overlap in ambiguous ways with other date formats, unlike some regional formats that switch the position of month and day numbers. These reasons, and the fact this date format is an ISO standard, are why it is the recommended date format for changelog entries.

Inconsistent Changes

A changelog which only mentions some of the changes can be as dangerous as not having a changelog. While many of the changes may not be relevant - for instance, removing a single whitespace may not need to be recorded in all instances - any important changes should be mentioned in the changelog. By inconsistently applying changes, your users may mistakenly think that the changelog is the single source of truth. It ought to be. With great power comes great responsibility - having a good changelog means having a consistently updated changelog.

Frequently Asked Questions

Is there a standard changelog format?

Not really. There's the GNU changelog style guide, or the two-paragraph-long GNU NEWS file "guideline". Both are inadequate or insufficient.

This project aims to be a better changelog convention. It comes from observing good practices in the open source community and gathering them.

Healthy criticism, discussion and suggestions for improvements are welcome.

What should the changelog file be named?

Call it CHANGELOG.md. Some projects use HISTORY, NEWS or RELEASES.

While it's easy to think that the name of your changelog file doesn't matter that much, why make it harder for your end users to consistently find notable changes?

What about GitHub Releases?

It's a great initiative. Releases can be used to turn simple git tags (for example a tag named v1.0.0) into rich release notes by manually adding release notes or it can pull annotated git tag messages and turn them into notes.

GitHub Releases create a non-portable changelog that can only be displayed to users within the context of GitHub. It's possible to make them look very much like the Keep a Changelog format, but it tends to be a bit more involved.

The current version of GitHub releases is also arguably not very discoverable by end-users, unlike the typical uppercase files (README, CONTRIBUTING, etc.). Another minor issue is that the interface doesn't currently offer links to commit logs between each release.

Can changelogs be automatically parsed?

It’s difficult, because people follow wildly different formats and file names.

Vandamme is a Ruby gem created by the Gemnasium team and which parses many (but not all) open source project changelogs.

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 changelog?

Sure. There are always good reasons to improve a changelog. I regularly open pull requests to add missing releases to open source projects with unmaintained changelogs.

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 changelog 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.

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.

Conversations

I went on The Changelog podcast to talk about why maintainers and contributors should care about changelogs, and also about the motivations behind this project.

La última versión (1.1.0) aun no está disponible en Español, por ahora puedes leerla en Inglés y ayudar a traducirla.

Mantener un CHANGELOG

No dejes que tus amigos copien y peguen git logs en los CHANGELOGs™

Version 0.3.0

Qué es un registro de cambios (change log)?

Un registro de cambios o “change log” de ahora en adelante, es un archivo que contiene una lista en orden cronológico sobre los cambios que vamos haciendo en cada reléase (o versión) de nuestro proyecto.

# 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.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?".

Cuál es el propósito del change log?

Para que les sea más fácil a los usuarios y contribuyentes, ver exactamente los cambios notables que se han hecho entre cada versión (o versiones) del proyecto.

Por qué me debería importar?

Debido a que las herramientas de software son para la gente. Si no te importa, ¿por qué contribuyes al código abierto? Sin duda, tiene que haber un "kernel" (ha!) de importancia en ese pequeño y encantador cerebro tuyo.

En el podcast "The Changelog" hablé con Adam Stacoviak y Jerod Santo (muy apropiado, ¿no?) acerca de por qué nos debería importar y sobre las motivaciones que es están detrás del proyecto. Si tienes tiempo (1:06), escúchalo, vale la pena

Cómo podemos hacer un buen change log?

Me alegro de que te lo hayas preguntado.

Un buen change log se guía por los siguientes principios:

Cómo puedo minimizar el esfuerzo requerido?

Siempre mantén una sección con el nombre "Unreleased" para hacer un seguimiento sobre los cambios

Esto nos puede servir para dos cosas:

Qué es lo que hace llorar a los unicornios?

Muy bien... vamos allá.

Pero espera! hay más ayúdame a coleccionar esas lágrimas de unicornio abriendo una incidencia o haciendo un pull request.

Hay algún formato estándar de formato para los change log?

Tristemente, no. Pero calma. Sé que estás corriendo furiosamente intentando encontrar ese link al libro de estilo de registro de cambios de GNU, or the two-paragraph GNU NEWS file "guideline". La guía de estilo GNU es un buen comienzo, pero es tristemente cándida. No hay nada malo en ser cándida, pero cuando la gente necesita orientación es rara la vez, que resulta ser muy útil. Sobre todo, cuando hay muchas situaciones y casos muy específicos.

Este proyecto contiene lo que espero se convierta en un mejor patrón de CHANGELOGs.

No creo que la situación actual sea lo suficientemente buena, i creo que como comunidad que somos podemos llegar a mejores convenciones si tratamos de extraer buenas prácticas de proyectos de software reales. Por favor echa un pequeño vistazo y recuerda que las sugerencias y discusiones para mejorar son bienvenidas!

Cómo se debería llamar el change log?

Bueno, si te fijas en en ejemplo anterior, CHANGELOG.md es la convención más usada

Otros proyectos también usan los siguientes nombres HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.

Es un desastre. Todos estos nombres sólo hacen más difícil la búsqueda del fichero.

Por qué la gente no usa simplemente un git log?

Debido a que están llenos de ruido - por naturaleza. No se podría hacer un change log adecuado ni siquiera en un proyecto hipotético dirigido por seres humanos perfectos que nunca se equivocan y que nunca se olvidan meter ningún archivo en un commit... etc. El propósito de un commit es el de documentar un cambio atómico en el cual el software evoluciona desde un estado hacia otro. El propósito del change log es el de documentar las diferencias notables entre estos estados.

Se pueden parsear automáticamente los change logs?

Es difícil, ya que la gente sigue formatos y nombres de archivo muy distintos.

Vandamme es un Ruby gem creado por el equipo Gemnasium, que lo que hace es parsear algunos (no todos) los change logs de varios proyectos open source.

Por que estás continuamente alternando los nombres de "CHANGELOG" a "change log"?

"CHANGELOG" es el nombre del archivo en sí. Es un poco intrusivo pero es una convención histórica seguida por muchos proyectos de código abierto. Otro ejemplo de este tipo de nombres en archivos son README, LICENSE, y CONTRIBUTING.

Los nombres en mayúsculas (que en algunos sistemas operativos antiguos hacían que estos ficheros aparecieran los primeros) se utilizan para llamar la atención sobre ellos. Dado que son importantes metadatos sobre el proyecto, que podría ser útil a cualquier persona con la intención de utilizar o contribuir al mismo.

Cuando me refiero a "change log", estoy hablando de la función del fichero: registrar los cambios.

Qué son las yanked releases?

Las yanked releases son versiones que tuvieron que ser retiradas a causa de un grave error o problema de seguridad. A menudo, estas versiones ni siquiera aparecen en los change logs, y tendrían que aparecer. Así es como se muestran:

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

La sección [YANKED] va entre corchetes por una razón, es importante que destaque, y el echo de estar rodeado por corchetes lo hace más fácil de localizar programáticamente.

Deberías volver a escribir un change log?

Por supuesto. Siempre hay buenas razones para mejorar el change log. A veces abro "pull requests" para añadir registros faltantes en el change log de proyectos open source.

Como puedo contribuir?

Este documento no es la verdad absoluta; es mi cuidadosa opinión, junto con información y ejemplos que recogí.

Esto es porque quiero que la comunidad llegue a un conceso. Creo que la discusión es tan importante como el resultado final.

Contribuye.

La última versión (1.1.0) aun no está disponible en Español, por ahora puedes leerla en Inglés y ayudar a traducirla.

Mantener un CHANGELOG

No dejes que tus amigos copien y peguen git logs en los CHANGELOGs™

Version 0.3.0

Qué es un registro de cambios (change log)?

Un registro de cambios o “change log” de ahora en adelante, es un archivo que contiene una lista en orden cronológico sobre los cambios que vamos haciendo en cada reléase (o versión) de nuestro proyecto.

# 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.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?".

Cuál es el propósito del change log?

Para que les sea más fácil a los usuarios y contribuyentes, ver exactamente los cambios notables que se han hecho entre cada versión (o versiones) del proyecto.

Por qué me debería importar?

Debido a que las herramientas de software son para la gente. Si no te importa, ¿por qué contribuyes al código abierto? Sin duda, tiene que haber un "kernel" (ha!) de importancia en ese pequeño y encantador cerebro tuyo.

En el podcast "The Changelog" hablé con Adam Stacoviak y Jerod Santo (muy apropiado, ¿no?) acerca de por qué nos debería importar y sobre las motivaciones que es están detrás del proyecto. Si tienes tiempo (1:06), escúchalo, vale la pena

Cómo podemos hacer un buen change log?

Me alegro de que te lo hayas preguntado.

Un buen change log se guía por los siguientes principios:

Cómo puedo minimizar el esfuerzo requerido?

Siempre mantén una sección con el nombre "Unreleased" para hacer un seguimiento sobre los cambios

Esto nos puede servir para dos cosas:

Qué es lo que hace llorar a los unicornios?

Muy bien... vamos allá.

Pero espera! hay más ayúdame a coleccionar esas lágrimas de unicornio abriendo una incidencia o haciendo un pull request.

Hay algún formato estándar de formato para los change log?

Tristemente, no. Pero calma. Sé que estás corriendo furiosamente intentando encontrar ese link al libro de estilo de registro de cambios de GNU, or the two-paragraph GNU NEWS file "guideline". La guía de estilo GNU es un buen comienzo, pero es tristemente cándida. No hay nada malo en ser cándida, pero cuando la gente necesita orientación es rara la vez, que resulta ser muy útil. Sobre todo, cuando hay muchas situaciones y casos muy específicos.

Este proyecto contiene lo que espero se convierta en un mejor patrón de CHANGELOGs.

No creo que la situación actual sea lo suficientemente buena, i creo que como comunidad que somos podemos llegar a mejores convenciones si tratamos de extraer buenas prácticas de proyectos de software reales. Por favor echa un pequeño vistazo y recuerda que las sugerencias y discusiones para mejorar son bienvenidas!

Cómo se debería llamar el change log?

Bueno, si te fijas en en ejemplo anterior, CHANGELOG.md es la convención más usada

Otros proyectos también usan los siguientes nombres HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.

Es un desastre. Todos estos nombres sólo hacen más difícil la búsqueda del fichero.

Por qué la gente no usa simplemente un git log?

Debido a que están llenos de ruido - por naturaleza. No se podría hacer un change log adecuado ni siquiera en un proyecto hipotético dirigido por seres humanos perfectos que nunca se equivocan y que nunca se olvidan meter ningún archivo en un commit... etc. El propósito de un commit es el de documentar un cambio atómico en el cual el software evoluciona desde un estado hacia otro. El propósito del change log es el de documentar las diferencias notables entre estos estados.

Se pueden parsear automáticamente los change logs?

Es difícil, ya que la gente sigue formatos y nombres de archivo muy distintos.

Vandamme es un Ruby gem creado por el equipo Gemnasium, que lo que hace es parsear algunos (no todos) los change logs de varios proyectos open source.

Por que estás continuamente alternando los nombres de "CHANGELOG" a "change log"?

"CHANGELOG" es el nombre del archivo en sí. Es un poco intrusivo pero es una convención histórica seguida por muchos proyectos de código abierto. Otro ejemplo de este tipo de nombres en archivos son README, LICENSE, y CONTRIBUTING.

Los nombres en mayúsculas (que en algunos sistemas operativos antiguos hacían que estos ficheros aparecieran los primeros) se utilizan para llamar la atención sobre ellos. Dado que son importantes metadatos sobre el proyecto, que podría ser útil a cualquier persona con la intención de utilizar o contribuir al mismo.

Cuando me refiero a "change log", estoy hablando de la función del fichero: registrar los cambios.

Qué son las yanked releases?

Las yanked releases son versiones que tuvieron que ser retiradas a causa de un grave error o problema de seguridad. A menudo, estas versiones ni siquiera aparecen en los change logs, y tendrían que aparecer. Así es como se muestran:

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

La sección [YANKED] va entre corchetes por una razón, es importante que destaque, y el echo de estar rodeado por corchetes lo hace más fácil de localizar programáticamente.

Deberías volver a escribir un change log?

Por supuesto. Siempre hay buenas razones para mejorar el change log. A veces abro "pull requests" para añadir registros faltantes en el change log de proyectos open source.

Como puedo contribuir?

Este documento no es la verdad absoluta; es mi cuidadosa opinión, junto con información y ejemplos que recogí.

Esto es porque quiero que la comunidad llegue a un conceso. Creo que la discusión es tan importante como el resultado final.

Contribuye.

La última versión (1.1.0) aun no está disponible en Español, por ahora puedes leerla en Inglés y ayudar a traducirla.

Mantenga un changelog

No dejes que tus amigos usen el registro de git en los changelogs.

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

## [Unreleased]

## [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

¿Qué es un registro de cambios (changelog)?

Un registro de cambios, «changelog» de ahora en adelante, es un archivo que contiene una lista cronológicamente ordenada de los cambios más destacables para cada versión de un proyecto.

¿Por qué mantener un changelog?

Para facilitar a los usuarios y colaboradores ver exactamente qué cambios reseñables se han realizado entre cada versión del proyecto.

¿Quién necesita un changelog?

Las personas. Ya sean consumidores o desarrolladores, los usuarios finales del software son seres humanos a los que le importa lo que hay en el software. Cuando el software cambia, la gente quiere saber el porqué y el cómo.

¿Cómo hago un buen changelog?

Directrices

  • Están hechos para los seres humanos, no para las máquinas.
  • Debe haber una entrada para cada versión.
  • Los mismos tipos de cambios deben ser agrupados.
  • Versiones y secciones deben ser enlazables.
  • La última versión va primero.
  • Debe mostrar la fecha de publicación de cada versión.
  • Indicar si el proyecto sigue el Versionamiento Semántico.

Tipos de cambios

  • Added para funcionalidades nuevas.
  • Changed para los cambios en las funcionalidades existentes.
  • Deprecated para indicar que una característica o funcionalidad está obsoleta y que se eliminará en las próximas versiones.
  • Removed para las características en desuso que se eliminaron en esta versión.
  • Fixed para corrección de errores.
  • Security en caso de vulnerabilidades.

¿Cómo puedo minimizar el esfuerzo requerido para mantener el changelog?

Mantén una sección con el nombre Unreleased para hacer un seguimiento sobre los próximos cambios.

Esto nos puede servir para dos cosas:

  • La gente puede ver qué cambios podrían esperar en los próximos lanzamientos.
  • Al lanzar una nueva versión, tan sólo habría que mover el contenido de Unreleased a una sección para la nueva versión.

¿Pueden los changelogs ser malos?

Sí. A continuación algunas formas en las que pueden ser muy poco útiles.

Usar un diff de los logs de los commits

Usar un diff de los logs de los commits es una mala idea: están llenos de ruido. Cosas como hacer merge de los commits, commits con títulos poco claros, cambios de documentación, etc.

El propósito de un commit es documentar un paso en la evolución del código fuente. Algunos proyectos limpian los commits, otros no.

El propósito de una entrada en el changelog es documentar cambios notables, usualmente entre múltiples commits, para comunicarlos claramente a los usuarios finales.

Ignorar funcionalidades sin soporte

Cuando la gente actualiza de una version a otra, debería estar bastante claro cuándo algo se va a romper. Debería ser posible actualizar a una versión que detalle funcionalidades sin soporte, eliminar lo que está obsoleto y actualizar a la versión donde esas funcionalidades han sido eliminadas.

Si no haces nada más, enumera lo que queda obsoleto, lo eliminado y cualquier otro cambio sin compatibilidad hacia atrás en tu changelog.

Fechas confusas

Los formatos de fecha regionales varían en todo el mundo y con frecuencia es difícil encontrar un formato intuitivo para todos. La ventaja de las fechas con el formato 2017-07-17 es que siguen un orden de unidades de mayor a menor: año, mes y día. Este formato tampoco coincide de forma ambigua con otros formatos de fecha, a diferencia de algunos que intercambian la posición del mes y el día. Todo esto, junto al hecho de ser un estándar ISO, son los motivos por los que es el formato de fecha recomendado para las entradas del changelog.

Preguntas frecuentes

¿Hay un formato estándar para el changelog?

No. Hay una guía de estilo del GNU o los dos parrafos del archivo guideline del GNU NEWS. Ambos son inadecuados o insuficientes.

Este proyecto apunta a ser una mejor convención de changelog. Esto se da observando las buenas prácticas en la comunidad open source y recopilando las mismas.

Críticas saludables, discusión y sugerencias para mejoras son bienvenidas.

¿Cómo debería llamarse el archivo de changelog?

Llámalo CHANGELOG.md. Algunos proyectos utilizan HISTORY, NEWS o RELEASES.

Si bien es fácil pensar que el nombre de tu archivo de changelog no importa tanto, ¿Por qué hacer difícil para los usuarios finales conseguir de manera consistente los cambios notables?

¿Y qué hay de los releases de Github?

Es una gran iniciativa. Los releases de Github pueden ser utilizados para convertir simples etiquetas de git (por ejemplo una etiqueta llamada v1.0.0) en ricas notas de lanzamiento ya sea añadiendo estas manualmente o trayendo los mensajes anotados de las etiquetas de git y convertirlas en notas.

Los releases de Github crean un changelog no portable que sólo pueden ser mostrados a usuarios dentro del contexto de Github. Es posible hacer que luzcan muy parecidas al formato de Mantenga un changelog, pero tiende a ser un poco más complicado.

La versión actual de los releases de Github es también discutiblemente no muy detectable por los usuarios finales, diferente a los típicos archivos en mayúsculas (README, CONTRIBUTING, etc.). Otro problema menor es que la interfaz actualmente no ofrece enlaces a los registros de los commits entre cada lanzamiento.

¿Se pueden analizar gramaticalmente los changelogs?

Es difícil, porque las personas usan formatos y nombres de archivos muy distintos.

Vandamme es una gema de Ruby creada por el equipo de Gemnasium que analiza gramaticalmente muchos (pero no todos) los changelogs de proyectos open source.

¿Qué hay sobre las versiones retiradas?

«Yanked releases» son versiones que tuvieron que ser retiradas por un error grave o problema de seguridad. Con frecuencia estas versiones ni siquiera aparecen en los changelogs. Deberían. Así es como deberían mostrarse:

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

La etiqueta [YANKED] está destacada por una razón: es importante que destaque. El hecho de estar entre corchetes la hace también más fácil de localizar programáticamente.

¿Deberías volver a escribir un changelog?

Por supuesto. Siempre hay buenas razones para mejorar el changelog. A veces abro «pull requests» para añadir registros faltantes en el changelog de proyectos open source.

También es posible que puedas descubrir que olvidaste señalar un cambio sin compatibilidad hacia atrás en las notas para una versión. En este caso es importante para ti actualizar el changelog.

¿Cómo puedo contribuir?

Este documento no es la verdad absoluta; es mi cuidadosa opinión, junto con información y ejemplos que recopilé.

Esto es porque quiero que la comunidad llegue a un consenso. Creo que la discusión es tan importante como el resultado final.

Así que por favor comienza a colaborar .

Conversaciones

Fui a The Changelog podcast para hablar acerca del porqué los mantenedores y colaboradores deberían preocuparse por los changelogs, y también acerca de las motivaciones detrás de este proyecto.

La última versión (1.1.0) aun no está disponible en Español, por ahora puedes leerla en Inglés y ayudar a traducirla.

Mantenga un changelog

No dejes que tus amigos usen el registro de git en los changelogs.

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

## [Unreleased]

## [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

¿Qué es un registro de cambios (changelog)?

Un registro de cambios, «changelog» de ahora en adelante, es un archivo que contiene una lista cronológicamente ordenada de los cambios más destacables para cada versión de un proyecto.

¿Por qué mantener un changelog?

Para facilitar a los usuarios y colaboradores ver exactamente qué cambios reseñables se han realizado entre cada versión del proyecto.

¿Quién necesita un changelog?

Las personas. Ya sean consumidores o desarrolladores, los usuarios finales del software son seres humanos a los que le importa lo que hay en el software. Cuando el software cambia, la gente quiere saber el porqué y el cómo.

¿Cómo hago un buen changelog?

Directrices

  • Están hechos para los seres humanos, no para las máquinas.
  • Debe haber una entrada para cada versión.
  • Los mismos tipos de cambios deben ser agrupados.
  • Versiones y secciones deben ser enlazables.
  • La última versión va primero.
  • Debe mostrar la fecha de publicación de cada versión.
  • Indicar si el proyecto sigue el Versionamiento Semántico.

Tipos de cambios

  • Added para funcionalidades nuevas.
  • Changed para los cambios en las funcionalidades existentes.
  • Deprecated para indicar que una característica o funcionalidad está obsoleta y que se eliminará en las próximas versiones.
  • Removed para las características en desuso que se eliminaron en esta versión.
  • Fixed para corrección de errores.
  • Security en caso de vulnerabilidades.

¿Cómo puedo minimizar el esfuerzo requerido para mantener el changelog?

Mantén una sección con el nombre Unreleased para hacer un seguimiento sobre los próximos cambios.

Esto nos puede servir para dos cosas:

  • La gente puede ver qué cambios podrían esperar en los próximos lanzamientos.
  • Al lanzar una nueva versión, tan sólo habría que mover el contenido de Unreleased a una sección para la nueva versión.

¿Pueden los changelogs ser malos?

Sí. A continuación algunas formas en las que pueden ser muy poco útiles.

Usar un diff de los logs de los commits

Usar un diff de los logs de los commits es una mala idea: están llenos de ruido. Cosas como hacer merge de los commits, commits con títulos poco claros, cambios de documentación, etc.

El propósito de un commit es documentar un paso en la evolución del código fuente. Algunos proyectos limpian los commits, otros no.

El propósito de una entrada en el changelog es documentar cambios notables, usualmente entre múltiples commits, para comunicarlos claramente a los usuarios finales.

Ignorar funcionalidades sin soporte

Cuando la gente actualiza de una version a otra, debería estar bastante claro cuándo algo se va a romper. Debería ser posible actualizar a una versión que detalle funcionalidades sin soporte, eliminar lo que está obsoleto y actualizar a la versión donde esas funcionalidades han sido eliminadas.

Si no haces nada más, enumera lo que queda obsoleto, lo eliminado y cualquier otro cambio sin compatibilidad hacia atrás en tu changelog.

Fechas confusas

Los formatos de fecha regionales varían en todo el mundo y con frecuencia es difícil encontrar un formato intuitivo para todos. La ventaja de las fechas con el formato 2017-07-17 es que siguen un orden de unidades de mayor a menor: año, mes y día. Este formato tampoco coincide de forma ambigua con otros formatos de fecha, a diferencia de algunos que intercambian la posición del mes y el día. Todo esto, junto al hecho de ser un estándar ISO, son los motivos por los que es el formato de fecha recomendado para las entradas del changelog.

Preguntas frecuentes

¿Hay un formato estándar para el changelog?

No. Hay una guía de estilo del GNU o los dos parrafos del archivo guideline del GNU NEWS. Ambos son inadecuados o insuficientes.

Este proyecto apunta a ser una mejor convención de changelog. Esto se da observando las buenas prácticas en la comunidad open source y recopilando las mismas.

Críticas saludables, discusión y sugerencias para mejoras son bienvenidas.

¿Cómo debería llamarse el archivo de changelog?

Llámalo CHANGELOG.md. Algunos proyectos utilizan HISTORY, NEWS o RELEASES.

Si bien es fácil pensar que el nombre de tu archivo de changelog no importa tanto, ¿Por qué hacer difícil para los usuarios finales conseguir de manera consistente los cambios notables?

¿Y qué hay de los releases de Github?

Es una gran iniciativa. Los releases de Github pueden ser utilizados para convertir simples etiquetas de git (por ejemplo una etiqueta llamada v1.0.0) en ricas notas de lanzamiento ya sea añadiendo estas manualmente o trayendo los mensajes anotados de las etiquetas de git y convertirlas en notas.

Los releases de Github crean un changelog no portable que sólo pueden ser mostrados a usuarios dentro del contexto de Github. Es posible hacer que luzcan muy parecidas al formato de Mantenga un changelog, pero tiende a ser un poco más complicado.

La versión actual de los releases de Github es también discutiblemente no muy detectable por los usuarios finales, diferente a los típicos archivos en mayúsculas (README, CONTRIBUTING, etc.). Otro problema menor es que la interfaz actualmente no ofrece enlaces a los registros de los commits entre cada lanzamiento.

¿Se pueden analizar gramaticalmente los changelogs?

Es difícil, porque las personas usan formatos y nombres de archivos muy distintos.

Vandamme es una gema de Ruby creada por el equipo de Gemnasium que analiza gramaticalmente muchos (pero no todos) los changelogs de proyectos open source.

¿Qué hay sobre las versiones retiradas?

«Yanked releases» son versiones que tuvieron que ser retiradas por un error grave o problema de seguridad. Con frecuencia estas versiones ni siquiera aparecen en los changelogs. Deberían. Así es como deberían mostrarse:

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

La etiqueta [YANKED] está destacada por una razón: es importante que destaque. El hecho de estar entre corchetes la hace también más fácil de localizar programáticamente.

¿Deberías volver a escribir un changelog?

Por supuesto. Siempre hay buenas razones para mejorar el changelog. A veces abro «pull requests» para añadir registros faltantes en el changelog de proyectos open source.

También es posible que puedas descubrir que olvidaste señalar un cambio sin compatibilidad hacia atrás en las notas para una versión. En este caso es importante para ti actualizar el changelog.

¿Cómo puedo contribuir?

Este documento no es la verdad absoluta; es mi cuidadosa opinión, junto con información y ejemplos que recopilé.

Esto es porque quiero que la comunidad llegue a un consenso. Creo que la discusión es tan importante como el resultado final.

Así que por favor comienza a colaborar .

Conversaciones

Fui a The Changelog podcast para hablar acerca del porqué los mantenedores y colaboradores deberían preocuparse por los changelogs, y también acerca de las motivaciones detrás de este proyecto.

Une nouvelle version est disponible: Français 1.1.0

Tenez un CHANGELOG

Ne laissez pas vos amis utiliser les logs git comme CHANGELOGs™

Version 0.3.0

Qu’est-ce qu’un journal des modifications (change log) ?

Un journal des modifications (ou change log) est un fichier qui contient une liste triée chronologiquement des changements notables pour chaque version d’un projet

# 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.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?".

Quel est l’intérêt d’un change log ?

Il permet aux utilisateurs et aux contributeurs de voir plus simplement les changements notables qui ont été réalisés entre chaque publication (ou version) du projet.

Pourquoi devrais-je m’en préoccuper ?

Parce que les logiciels sont pour les gens. Si vous ne vous en souciez pas, pourquoi contribuez-vous à l’open source ? Il doit sûrement y avoir un "kernel" (ha!) d’intérêt pour ça quelque part dans votre cher petit cerveau.

J’ai discuté avec Adam Stacoviak et Jerod Santo dans le podcast "The Changelog" (approprié, non ?) des raisons pour lesquelles les mainteneurs et les contributeurs devraient s’en préoccuper ; également des motivations derrière ce projet. Si vous avez le temps (1:06), l’écoute vaut le coup.

Qu’est-ce qui fait un bon change log ?

Heureux de vous entendre le demander.

Un bon change log se conforme à ces principes:

Comment puis-je minimiser le travail nécessaire ?

Ayez toujours une section "Unreleased" en haut du fichier afin de lister tous les changements pas encore publiés.

Cela rempli deux objectifs:

Quelles sont les choses qui rendent tristes les licornes ?

Très bien… parlons-en.

Il y en a d’autres. Aidez-moi à collecter ces larmes de licornes en ouvrant une issue ou une pull request.

Y a-t-il un format de change log standard ?

Malheureusement, non. Du calme. Je sais que vous êtes en train de vous précipiter afin de trouver le lien vers le guide pour change logs GNU, ou le fichier GNU NEWS "guideline" de deux paragraphes. Le guide GNU est un bon début mais il est malheureusement simpliste. Il n'y a rien de mal avec le fait d'être simpliste, mais quand les gens ont besoin d'être guidés, ce n'est que rarement utile. Spécialement quand il a beaucoup de situations et de cas particuliers à prendre en compte.

Ce projet contient ce que j'espère devenir une meilleur convention pour les fichiers CHANGELOG. Je ne pense pas que le status quo soit suffisant et je pense qu'en tant que communauté, nous pouvons arriver à de meilleures conventions si nous essayons d'extraire les meilleures pratiques depuis les vrais projets logiciels. S'il vous plaît, jetez-y un coup d'oeil et rappelez vous que les discussions et les suggestions d'améliorations sont les bienvenues!

Comment doit-être nommé le fichier de change log ?

Eh bien, si l'exemple ci-dessus ne vous suffit pas à le deviner, CHANGELOG.md est la meilleure convention à ce jour.

Certains projets utilisent aussi HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.

C'est un véritable bazar. Tous ces noms ne font que rendre plus difficile son repérage par les gens.

Pourquoi les gens ne recopient pas simplement les derniers logs git ?

Parce que les logs gits sont remplis de bruit - par définition. Ils ne peuvent pas faire office de change log convenable, même dans un hypothétique projet tenu par des humains parfaits qui ne font jamais la moindre faute de frappe, n'oublient jamais de committer les nouveaux fichiers, ne manquent jamais aucune partie d'un refactoring. Le but d'un commit est de documenter une étape atomique dans le processus par lequel le code évolue d'un état à un autre. Le but d'un change log est de documenter les différences notables entre ces états.

La différence entre des bons commentaires et le code lui-même est la même que celle entre un change log et les journaux git: l'un décrit le pourquoi, l'autre le comment.

Les change logs peuvent-ils être parsés automatiquement ?

C'est difficile, parce que les gens suivent des formats et utilisent des noms de fichiers très différents.

Vandamme est une Ruby gem créée par l'équipe Gemnasium qui parse les change logs de beaucoup (mais pas tous) de projets open source.

Pourquoi cette alternance entre les graphies "CHANGELOG" et "change log" ?

"CHANGELOG" est le nom pour le fichier même. C'est un peu imposant, mais dû à une convention historique suivie par beaucoup de projets open source. Il existe d'autres fichiers similaires, par exemple : README, LICENSE, and CONTRIBUTING.

L'écriture en majuscule (qui dans les vieux systèmes d'exploitation faisait apparaître ces fichiers en haut) de ces noms de fichiers est utilisée pour attirer l'attention sur eux. Puisqu'ils font partie des méta-données importantes du projet, ils pourraient être utiles à quiconque voulant y l'utiliser ou y contribuer, tout comme les badges de projet open source.

Quand j'utilise la graphie "change log", je fais référence à la fonction de ce fichier: journaliser les changements.

Qu'en est-il des publications "yanked" ?

Les publications yanked sont des version qui ont dû être retirées du fait d'un sérieux bug ou d'un problème de sécurité. Souvent ces version n'apparaissent même pas dans les change logs. Elles devraient. Voilà comment les afficher:

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

Le tag [YANKED] n'est pas mis en avant pour rien. C'est important pour les gens de le remarquer. Puisqu'il est entouré par des crochets, c'est aussi plus facile à parser pour un programme.

Devriez-vous réécrire un change log ?

Bien sûr. Il y a toujours de bonnes raisons d'améliorer un change log. J'ouvre souvent des pull requests pour ajouter des publications manquantes sur des projets open source avec des change logs non-maintenus.

Il est aussi possible que vous découvriez que vous aviez oublié de mentionner un changement majeur dans les notes de version. Il est évidemment important que vous mettiez votre change log à jour dans ce cas.

Comment puis-je contribuer ?

Ce document n'est pas la vérité; c'est mon opinion soigneusement réfléchie, accompagnée d'informations et d'exemples que j'ai rassemblés. Bien que je fournisse un véritable CHANGELOG sur le dépôt GitHub, je n'ai volontairement pas créé de véritable publication ou de liste précise de règles à suivre (comme le fait SemVer.org, par exemple).

C'est parce que je veux que notre communauté atteigne un consensus. Je crois que la discussion est aussi importante que le résultat final.

Donc s'il vous plaît, mettez-vous y.

Une nouvelle version est disponible: Français 1.1.0

Tenez un CHANGELOG

Ne laissez pas vos amis utiliser les logs git comme CHANGELOGs™

Version 0.3.0

Qu’est-ce qu’un journal des modifications (change log) ?

Un journal des modifications (ou change log) est un fichier qui contient une liste triée chronologiquement des changements notables pour chaque version d’un projet

# 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.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?".

Quel est l’intérêt d’un change log ?

Il permet aux utilisateurs et aux contributeurs de voir plus simplement les changements notables qui ont été réalisés entre chaque publication (ou version) du projet.

Pourquoi devrais-je m’en préoccuper ?

Parce que les logiciels sont pour les gens. Si vous ne vous en souciez pas, pourquoi contribuez-vous à l’open source ? Il doit sûrement y avoir un "kernel" (ha!) d’intérêt pour ça quelque part dans votre cher petit cerveau.

J’ai discuté avec Adam Stacoviak et Jerod Santo dans le podcast "The Changelog" (approprié, non ?) des raisons pour lesquelles les mainteneurs et les contributeurs devraient s’en préoccuper ; également des motivations derrière ce projet. Si vous avez le temps (1:06), l’écoute vaut le coup.

Qu’est-ce qui fait un bon change log ?

Heureux de vous entendre le demander.

Un bon change log se conforme à ces principes:

Comment puis-je minimiser le travail nécessaire ?

Ayez toujours une section "Unreleased" en haut du fichier afin de lister tous les changements pas encore publiés.

Cela rempli deux objectifs:

Quelles sont les choses qui rendent tristes les licornes ?

Très bien… parlons-en.

Il y en a d’autres. Aidez-moi à collecter ces larmes de licornes en ouvrant une issue ou une pull request.

Y a-t-il un format de change log standard ?

Malheureusement, non. Du calme. Je sais que vous êtes en train de vous précipiter afin de trouver le lien vers le guide pour change logs GNU, ou le fichier GNU NEWS "guideline" de deux paragraphes. Le guide GNU est un bon début mais il est malheureusement simpliste. Il n'y a rien de mal avec le fait d'être simpliste, mais quand les gens ont besoin d'être guidés, ce n'est que rarement utile. Spécialement quand il a beaucoup de situations et de cas particuliers à prendre en compte.

Ce projet contient ce que j'espère devenir une meilleur convention pour les fichiers CHANGELOG. Je ne pense pas que le status quo soit suffisant et je pense qu'en tant que communauté, nous pouvons arriver à de meilleures conventions si nous essayons d'extraire les meilleures pratiques depuis les vrais projets logiciels. S'il vous plaît, jetez-y un coup d'oeil et rappelez vous que les discussions et les suggestions d'améliorations sont les bienvenues!

Comment doit-être nommé le fichier de change log ?

Eh bien, si l'exemple ci-dessus ne vous suffit pas à le deviner, CHANGELOG.md est la meilleure convention à ce jour.

Certains projets utilisent aussi HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.

C'est un véritable bazar. Tous ces noms ne font que rendre plus difficile son repérage par les gens.

Pourquoi les gens ne recopient pas simplement les derniers logs git ?

Parce que les logs gits sont remplis de bruit - par définition. Ils ne peuvent pas faire office de change log convenable, même dans un hypothétique projet tenu par des humains parfaits qui ne font jamais la moindre faute de frappe, n'oublient jamais de committer les nouveaux fichiers, ne manquent jamais aucune partie d'un refactoring. Le but d'un commit est de documenter une étape atomique dans le processus par lequel le code évolue d'un état à un autre. Le but d'un change log est de documenter les différences notables entre ces états.

La différence entre des bons commentaires et le code lui-même est la même que celle entre un change log et les journaux git: l'un décrit le pourquoi, l'autre le comment.

Les change logs peuvent-ils être parsés automatiquement ?

C'est difficile, parce que les gens suivent des formats et utilisent des noms de fichiers très différents.

Vandamme est une Ruby gem créée par l'équipe Gemnasium qui parse les change logs de beaucoup (mais pas tous) de projets open source.

Pourquoi cette alternance entre les graphies "CHANGELOG" et "change log" ?

"CHANGELOG" est le nom pour le fichier même. C'est un peu imposant, mais dû à une convention historique suivie par beaucoup de projets open source. Il existe d'autres fichiers similaires, par exemple : README, LICENSE, and CONTRIBUTING.

L'écriture en majuscule (qui dans les vieux systèmes d'exploitation faisait apparaître ces fichiers en haut) de ces noms de fichiers est utilisée pour attirer l'attention sur eux. Puisqu'ils font partie des méta-données importantes du projet, ils pourraient être utiles à quiconque voulant y l'utiliser ou y contribuer, tout comme les badges de projet open source.

Quand j'utilise la graphie "change log", je fais référence à la fonction de ce fichier: journaliser les changements.

Qu'en est-il des publications "yanked" ?

Les publications yanked sont des version qui ont dû être retirées du fait d'un sérieux bug ou d'un problème de sécurité. Souvent ces version n'apparaissent même pas dans les change logs. Elles devraient. Voilà comment les afficher:

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

Le tag [YANKED] n'est pas mis en avant pour rien. C'est important pour les gens de le remarquer. Puisqu'il est entouré par des crochets, c'est aussi plus facile à parser pour un programme.

Devriez-vous réécrire un change log ?

Bien sûr. Il y a toujours de bonnes raisons d'améliorer un change log. J'ouvre souvent des pull requests pour ajouter des publications manquantes sur des projets open source avec des change logs non-maintenus.

Il est aussi possible que vous découvriez que vous aviez oublié de mentionner un changement majeur dans les notes de version. Il est évidemment important que vous mettiez votre change log à jour dans ce cas.

Comment puis-je contribuer ?

Ce document n'est pas la vérité; c'est mon opinion soigneusement réfléchie, accompagnée d'informations et d'exemples que j'ai rassemblés. Bien que je fournisse un véritable CHANGELOG sur le dépôt GitHub, je n'ai volontairement pas créé de véritable publication ou de liste précise de règles à suivre (comme le fait SemVer.org, par exemple).

C'est parce que je veux que notre communauté atteigne un consensus. Je crois que la discussion est aussi importante que le résultat final.

Donc s'il vous plaît, mettez-vous y.

Une nouvelle version est disponible: Français 1.1.0

Tenez un Changelog

Ne laissez pas vos amis utiliser les logs git comme changelogs

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

## [Unreleased]

## [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

Qu'est-ce qu'un changelog ?

Un changelog (journal des modifications) est un fichier qui contient une liste triée chronologiquement des changements notables pour chaque version d’un projet

Pourquoi tenir un changelog ?

Pour permettre aux utilisateurs et contributeurs de voir précisément quels changements notables ont été faits entre chaque publication (ou version) d'un projet.

Qui a besoin d'un changelog ?

Tout le monde. Qu'ils soient consommateurs ou développeurs, les utilisateurs de logiciels sont des êtres humains qui se soucient de connaître le contenu des logiciels qu'ils utilisent. Quand un logiciel change, ces mêmes personnes veulent savoir comment et pourquoi.

Comment créer un bon changelog ?

Principes Directeurs

  • Les changelogs sont pour les êtres humains, pas les machines.
  • Il doit y avoir une section pour chaque version.
  • Les changements similaires doivent être groupés.
  • Les versions et sections doivent être liables.
  • La version la plus récente se situe en haut du fichier.
  • La date de publication de chaque version est indiquée.
  • Indiquer si le projet respecte le Versionnage Sémantique.

Types de changements

  • Added pour les nouvelles fonctionnalités.
  • Changed pour les changements aux fonctionnalités préexistantes.
  • Deprecated pour les fonctionnalités qui seront bientôt supprimées.
  • Removed pour les fonctionnalités désormais supprimées.
  • Fixed pour les corrections de bugs.
  • Security en cas de vulnérabilités.

Comment puis-je minimiser le travail nécessaire pour maintenir un changelog ?

Gardez une section Unreleased en haut du fichier afin de lister tous les changements qui n'ont pas encore été publiés.

Cela permet deux choses:

  • Les gens peuvent voir les changements auxquels ils peuvent s’attendre dans les prochaines publications.
  • Au moment de la publication, vous pouvez déplacer les changements listés dans la section Unreleased dans la section d'une nouvelle version.

Est-ce que les changelogs peuvent être mauvais ?

Oui. Voici quelques exemples de changelogs plutôt inutiles.

Diffs de journaux gits

Utiliser des diffs de journaux gits en tant que changelogs est une mauvaise idée: ils sont remplis de bruit. Les journaux gits sont remplis de choses comme des commits de merge, des commits avec des titres obscurs, des changements concernant la documentation, etc.

Le but d'un commit est de documenter une étape dans l'évolution du code source. Certains projets nettoient leurs commits, d'autres non.

Le but d'une section de changelog est de documenter les différences notables entre deux versions, souvent à travers de multiples commits, afin de les communiquer clairement aux utilisateurs.

Ignorer les dépréciations

Lorsque l'on passe d'une version d'un logiciel à une autre, il devrait être très clair si quelque chose peut ne plus fonctionner. Il devrait être possible de mettre à jour vers une version qui offre une liste des fonctionnalités dépréciées, de retirer ce qui est déprécié, puis de mettre à jour vers la version où les dépréciations deviennent des suppressions de fonctionnalités.

Si vous ne faites rien d'autre, listez les dépréciations, les supressions de fonctionnalités, et tous les changements non rétrocompatibles dans votre changelog.

Dates confuses

Aux États-Unis, les gens mettent le mois en premier (06-02-2012 pour le 2 juin 2012), tandis que beaucoup de gens dans le reste du monde l’écrivent de la façon robotique suivante « 2 Juin 2012 », alors qu’ils le prononcent différement. 2012-06-02 fonctionne logiquement, du plus grand au plus petit, ne laisse pas place à la confusion avec un autre format et est un standard ISO. C'est pour cela que ce format de date est recommandé pour les changelogs.

Questions fréquemment posées

Y a-t-il un format de changelog standard ?

Pas vraiment. Il y a le guide de style GNU pour les changelogs, ou les instructions GNU de deux paragraphes pour les fichiers NEWS. Ces deux ressources sont inappropriées et insuffisantes.

Ce projet vise à devenir une meilleure convention pour les changelogs. Il a pour origine l'observation et le rassemblement des bonne pratiques dans la communauté open source.

Les critiques constructives, discussions et suggestions pour améliorer ce projet sont les bienvenues..

Comment doit-être nommé le fichier de changelog ?

Nommez-le CHANGELOG.md. Certains projets utilisent HISTORY, NEWS ou RELEASES.

Même s'il est facile d'imaginer que le nom d'un fichier de changelog n'a pas grand intérêt, pourquoi rendre la tâche plus difficile que nécessaire aux utilisateurs qui cherchent à trouver les changements notables de votre projet ?

Quid de GitHub Releases ?

C'est une excellente initiative. Releases peut être utilisé pour transformer de simples tags git (par exemple un tag nommé v1.0.0) en notes de publication riches soit en ajoutant manuellement des notes soit en utilisant les messages de tags gits annotés et en les transformant en notes.

GitHub Releases crée un changelog non-portable qui n'est visible par les utilisateurs qu'à l'intérieur du contexte de GitHub. Il est possible de suivre le même format que Keep a Changelog, mais c'est plus difficile.

La version actuelle de GitHub Releases est également difficile à découvrir pour les utilisateurs, contrairement aux fichiers en majuscules typiques (README, CONTRIBUTING, etc.). Un autre souci mineur est que l'interface n'offre actuellement pas de lien vers les journaux gits entre chaque publication.

Les changelogs peuvent-ils être parsés automatiquement ?

C'est difficile, parce que les gens suivent des formats et utilisent des noms de fichiers très différents.

Vandamme est une Ruby gem créée par l'équipe Gemnasium qui parse les changelogs de beaucoup (mais pas tous) de projets open source.

Qu'en est-il des publications « yanked » (retirées) ?

Les publications yanked sont des version qui ont dû être retirées du fait d'un sérieux bug ou d'un problème de sécurité. Souvent ces version n'apparaissent même pas dans les changelogs. Elles devraient. Voilà comment les afficher :

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

Le tag [YANKED] n'est pas mis en avant pour rien. Il est important qu'il soit remarqué. Il est également plus facile à digérer pour un programme puisqu'il est entouré par des crochets.

Devriez-vous réécrire un changelog ?

Bien sûr. Il y a toujours de bonnes raisons d'améliorer un changelog. J'ouvre souvent des pull requests pour ajouter des publications manquantes sur des projets open source avec des changelogs non-maintenus.

Il est aussi possible que vous découvriez que vous aviez oublié de mentionner un changement majeur dans les notes de version. Il est évidemment important que vous mettiez votre changelog à jour dans ce cas.

Comment puis-je contribuer ?

Ce document n'est pas la **vérité**; c'est mon opinion soigneusement réfléchie, accompagnée d'informations et d'exemples que j'ai rassemblés.

C'est parce que je veux que notre communauté atteigne un consensus. Je crois que la discussion est aussi importante que le résultat final.

Donc s'il vous plaît, participez.

Conversations

J'ai participé au podcast The Changelog pour expliquer pourquoi les mainteneurs et contributeurs doivent se soucier des changelogs et également des motivations derrière ce projet.

Une nouvelle version est disponible: Français 1.1.0

Tenez un Changelog

Ne laissez pas vos amis utiliser les logs git comme changelogs

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

## [Unreleased]

## [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

Qu'est-ce qu'un changelog ?

Un changelog (journal des modifications) est un fichier qui contient une liste triée chronologiquement des changements notables pour chaque version d’un projet

Pourquoi tenir un changelog ?

Pour permettre aux utilisateurs et contributeurs de voir précisément quels changements notables ont été faits entre chaque publication (ou version) d'un projet.

Qui a besoin d'un changelog ?

Tout le monde. Qu'ils soient consommateurs ou développeurs, les utilisateurs de logiciels sont des êtres humains qui se soucient de connaître le contenu des logiciels qu'ils utilisent. Quand un logiciel change, ces mêmes personnes veulent savoir comment et pourquoi.

Comment créer un bon changelog ?

Principes Directeurs

  • Les changelogs sont pour les êtres humains, pas les machines.
  • Il doit y avoir une section pour chaque version.
  • Les changements similaires doivent être groupés.
  • Les versions et sections doivent être liables.
  • La version la plus récente se situe en haut du fichier.
  • La date de publication de chaque version est indiquée.
  • Indiquer si le projet respecte le Versionnage Sémantique.

Types de changements

  • Added pour les nouvelles fonctionnalités.
  • Changed pour les changements aux fonctionnalités préexistantes.
  • Deprecated pour les fonctionnalités qui seront bientôt supprimées.
  • Removed pour les fonctionnalités désormais supprimées.
  • Fixed pour les corrections de bugs.
  • Security en cas de vulnérabilités.

Comment puis-je minimiser le travail nécessaire pour maintenir un changelog ?

Gardez une section Unreleased en haut du fichier afin de lister tous les changements qui n'ont pas encore été publiés.

Cela permet deux choses:

  • Les gens peuvent voir les changements auxquels ils peuvent s’attendre dans les prochaines publications.
  • Au moment de la publication, vous pouvez déplacer les changements listés dans la section Unreleased dans la section d'une nouvelle version.

Est-ce que les changelogs peuvent être mauvais ?

Oui. Voici quelques exemples de changelogs plutôt inutiles.

Diffs de journaux gits

Utiliser des diffs de journaux gits en tant que changelogs est une mauvaise idée: ils sont remplis de bruit. Les journaux gits sont remplis de choses comme des commits de merge, des commits avec des titres obscurs, des changements concernant la documentation, etc.

Le but d'un commit est de documenter une étape dans l'évolution du code source. Certains projets nettoient leurs commits, d'autres non.

Le but d'une section de changelog est de documenter les différences notables entre deux versions, souvent à travers de multiples commits, afin de les communiquer clairement aux utilisateurs.

Ignorer les dépréciations

Lorsque l'on passe d'une version d'un logiciel à une autre, il devrait être très clair si quelque chose peut ne plus fonctionner. Il devrait être possible de mettre à jour vers une version qui offre une liste des fonctionnalités dépréciées, de retirer ce qui est déprécié, puis de mettre à jour vers la version où les dépréciations deviennent des suppressions de fonctionnalités.

Si vous ne faites rien d'autre, listez les dépréciations, les supressions de fonctionnalités, et tous les changements non rétrocompatibles dans votre changelog.

Dates confuses

Aux États-Unis, les gens mettent le mois en premier (06-02-2012 pour le 2 juin 2012), tandis que beaucoup de gens dans le reste du monde l’écrivent de la façon robotique suivante « 2 Juin 2012 », alors qu’ils le prononcent différement. 2012-06-02 fonctionne logiquement, du plus grand au plus petit, ne laisse pas place à la confusion avec un autre format et est un standard ISO. C'est pour cela que ce format de date est recommandé pour les changelogs.

Questions fréquemment posées

Y a-t-il un format de changelog standard ?

Pas vraiment. Il y a le guide de style GNU pour les changelogs, ou les instructions GNU de deux paragraphes pour les fichiers NEWS. Ces deux ressources sont inappropriées et insuffisantes.

Ce projet vise à devenir une meilleure convention pour les changelogs. Il a pour origine l'observation et le rassemblement des bonne pratiques dans la communauté open source.

Les critiques constructives, discussions et suggestions pour améliorer ce projet sont les bienvenues..

Comment doit-être nommé le fichier de changelog ?

Nommez-le CHANGELOG.md. Certains projets utilisent HISTORY, NEWS ou RELEASES.

Même s'il est facile d'imaginer que le nom d'un fichier de changelog n'a pas grand intérêt, pourquoi rendre la tâche plus difficile que nécessaire aux utilisateurs qui cherchent à trouver les changements notables de votre projet ?

Quid de GitHub Releases ?

C'est une excellente initiative. Releases peut être utilisé pour transformer de simples tags git (par exemple un tag nommé v1.0.0) en notes de publication riches soit en ajoutant manuellement des notes soit en utilisant les messages de tags gits annotés et en les transformant en notes.

GitHub Releases crée un changelog non-portable qui n'est visible par les utilisateurs qu'à l'intérieur du contexte de GitHub. Il est possible de suivre le même format que Keep a Changelog, mais c'est plus difficile.

La version actuelle de GitHub Releases est également difficile à découvrir pour les utilisateurs, contrairement aux fichiers en majuscules typiques (README, CONTRIBUTING, etc.). Un autre souci mineur est que l'interface n'offre actuellement pas de lien vers les journaux gits entre chaque publication.

Les changelogs peuvent-ils être parsés automatiquement ?

C'est difficile, parce que les gens suivent des formats et utilisent des noms de fichiers très différents.

Vandamme est une Ruby gem créée par l'équipe Gemnasium qui parse les changelogs de beaucoup (mais pas tous) de projets open source.

Qu'en est-il des publications « yanked » (retirées) ?

Les publications yanked sont des version qui ont dû être retirées du fait d'un sérieux bug ou d'un problème de sécurité. Souvent ces version n'apparaissent même pas dans les changelogs. Elles devraient. Voilà comment les afficher :

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

Le tag [YANKED] n'est pas mis en avant pour rien. Il est important qu'il soit remarqué. Il est également plus facile à digérer pour un programme puisqu'il est entouré par des crochets.

Devriez-vous réécrire un changelog ?

Bien sûr. Il y a toujours de bonnes raisons d'améliorer un changelog. J'ouvre souvent des pull requests pour ajouter des publications manquantes sur des projets open source avec des changelogs non-maintenus.

Il est aussi possible que vous découvriez que vous aviez oublié de mentionner un changement majeur dans les notes de version. Il est évidemment important que vous mettiez votre changelog à jour dans ce cas.

Comment puis-je contribuer ?

Ce document n'est pas la **vérité**; c'est mon opinion soigneusement réfléchie, accompagnée d'informations et d'exemples que j'ai rassemblés.

C'est parce que je veux que notre communauté atteigne un consensus. Je crois que la discussion est aussi importante que le résultat final.

Donc s'il vous plaît, participez.

Conversations

J'ai participé au podcast The Changelog pour expliquer pourquoi les mainteneurs et contributeurs doivent se soucier des changelogs et également des motivations derrière ce projet.

Une nouvelle version est disponible: Français 1.1.0

Tenez un Changelog

Ne laissez pas vos amis utiliser les logs git comme changelogs

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

## [Unreleased]

## [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

Qu'est-ce qu'un changelog ?

Un changelog (journal des modifications) est un fichier qui contient une liste triée chronologiquement des changements notables pour chaque version d’un projet

Pourquoi tenir un changelog ?

Pour permettre aux utilisateurs et contributeurs de voir précisément quels changements notables ont été faits entre chaque publication (ou version) d'un projet.

Qui a besoin d'un changelog ?

Tout le monde. Qu'ils soient consommateurs ou développeurs, les utilisateurs de logiciels sont des êtres humains qui se soucient de connaître le contenu des logiciels qu'ils utilisent. Quand un logiciel change, ces mêmes personnes veulent savoir comment et pourquoi.

Comment créer un bon changelog ?

Principes Directeurs

  • Les changelogs sont pour les êtres humains, pas les machines.
  • Il doit y avoir une section pour chaque version.
  • Les changements similaires doivent être groupés.
  • Les versions et sections doivent être liables.
  • La version la plus récente se situe en haut du fichier.
  • La date de publication de chaque version est indiquée.
  • Indiquer si le projet respecte le Versionnage Sémantique.

Types de changements

  • Added pour les nouvelles fonctionnalités.
  • Changed pour les changements aux fonctionnalités préexistantes.
  • Deprecated pour les fonctionnalités qui seront bientôt supprimées.
  • Removed pour les fonctionnalités désormais supprimées.
  • Fixed pour les corrections de bugs.
  • Security en cas de vulnérabilités.

Comment puis-je minimiser le travail nécessaire pour maintenir un changelog ?

Gardez une section Unreleased en haut du fichier afin de lister tous les changements qui n'ont pas encore été publiés.

Cela permet deux choses:

  • Les gens peuvent voir les changements auxquels ils peuvent s’attendre dans les prochaines publications.
  • Au moment de la publication, vous pouvez déplacer les changements listés dans la section Unreleased dans la section d'une nouvelle version.

Est-ce que les changelogs peuvent être mauvais ?

Oui. Voici quelques exemples de changelogs plutôt inutiles.

Diffs de journaux gits

Utiliser des diffs de journaux gits en tant que changelogs est une mauvaise idée: ils sont remplis de bruit. Les journaux gits sont remplis de choses comme des commits de merge, des commits avec des titres obscurs, des changements concernant la documentation, etc.

Le but d'un commit est de documenter une étape dans l'évolution du code source. Certains projets nettoient leurs commits, d'autres non.

Le but d'une section de changelog est de documenter les différences notables entre deux versions, souvent à travers de multiples commits, afin de les communiquer clairement aux utilisateurs.

Ignorer les dépréciations

Lorsque l'on passe d'une version d'un logiciel à une autre, il devrait être très clair si quelque chose peut ne plus fonctionner. Il devrait être possible de mettre à jour vers une version qui offre une liste des fonctionnalités dépréciées, de retirer ce qui est déprécié, puis de mettre à jour vers la version où les dépréciations deviennent des suppressions de fonctionnalités.

Si vous ne faites rien d'autre, listez les dépréciations, les supressions de fonctionnalités, et tous les changements non rétrocompatibles dans votre changelog.

Dates confuses

Aux États-Unis, les gens mettent le mois en premier (06-02-2012 pour le 2 juin 2012), tandis que beaucoup de gens dans le reste du monde l’écrivent de la façon robotique suivante « 2 Juin 2012 », alors qu’ils le prononcent différement. 2012-06-02 fonctionne logiquement, du plus grand au plus petit, ne laisse pas place à la confusion avec un autre format et est un standard ISO. C'est pour cela que ce format de date est recommandé pour les changelogs.

Inconsistent Changes

Un changelog qui ne mentionne qu'une portion des changements peut être aussi dangereux que l'absence totale de changelog. Bien que la majorité des changements peuvent être sans conséquence, par exemple retirer un simple espace dans un texte ne nécessite probablement pas de mention, tout changements important devrait être mentionné dans le changelog. Sans consistence dans l'application des changements, vos utilisateurs pourraient être induit en erreur et penser que le changelog est la seule source de d'information. Ça devrait être le cas. Son pouvoir implique des responsabilités: un bon changelog est synonyme avec un changelog mis à jour de façon consistante.

Questions fréquemment posées

Y a-t-il un format de changelog standard ?

Pas vraiment. Il y a le guide de style GNU pour les changelogs, ou les instructions GNU de deux paragraphes pour les fichiers NEWS. Ces deux ressources sont inappropriées et insuffisantes.

Ce projet vise à devenir une meilleure convention pour les changelogs. Il a pour origine l'observation et le rassemblement des bonne pratiques dans la communauté open source.

Les critiques constructives, discussions et suggestions pour améliorer ce projet sont les bienvenues..

Comment doit-être nommé le fichier de changelog ?

Nommez-le CHANGELOG.md. Certains projets utilisent HISTORY, NEWS ou RELEASES.

Même s'il est facile d'imaginer que le nom d'un fichier de changelog n'a pas grand intérêt, pourquoi rendre la tâche plus difficile que nécessaire aux utilisateurs qui cherchent à trouver les changements notables de votre projet ?

Quid de GitHub Releases ?

C'est une excellente initiative. Releases peut être utilisé pour transformer de simples tags git (par exemple un tag nommé v1.0.0) en notes de publication riches soit en ajoutant manuellement des notes soit en utilisant les messages de tags gits annotés et en les transformant en notes.

GitHub Releases crée un changelog non-portable qui n'est visible par les utilisateurs qu'à l'intérieur du contexte de GitHub. Il est possible de suivre le même format que Keep a Changelog, mais c'est plus difficile.

La version actuelle de GitHub Releases est également difficile à découvrir pour les utilisateurs, contrairement aux fichiers en majuscules typiques (README, CONTRIBUTING, etc.). Un autre souci mineur est que l'interface n'offre actuellement pas de lien vers les journaux gits entre chaque publication.

Les changelogs peuvent-ils être parsés automatiquement ?

C'est difficile, parce que les gens suivent des formats et utilisent des noms de fichiers très différents.

Vandamme est une Ruby gem créée par l'équipe Gemnasium qui parse les changelogs de beaucoup (mais pas tous) de projets open source.

Qu'en est-il des publications « yanked » (retirées) ?

Les publications yanked sont des version qui ont dû être retirées du fait d'un sérieux bug ou d'un problème de sécurité. Souvent ces version n'apparaissent même pas dans les changelogs. Elles devraient. Voilà comment les afficher :

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

Le tag [YANKED] n'est pas mis en avant pour rien. Il est important qu'il soit remarqué. Il est également plus facile à digérer pour un programme puisqu'il est entouré par des crochets.

Devriez-vous réécrire un changelog ?

Bien sûr. Il y a toujours de bonnes raisons d'améliorer un changelog. J'ouvre souvent des pull requests pour ajouter des publications manquantes sur des projets open source avec des changelogs non-maintenus.

Il est aussi possible que vous découvriez que vous aviez oublié de mentionner un changement majeur dans les notes de version. Il est évidemment important que vous mettiez votre changelog à jour dans ce cas.

Comment puis-je contribuer ?

Ce document n'est pas la **vérité**; c'est mon opinion soigneusement réfléchie, accompagnée d'informations et d'exemples que j'ai rassemblés.

C'est parce que je veux que notre communauté atteigne un consensus. Je crois que la discussion est aussi importante que le résultat final.

Donc s'il vous plaît, participez.

Conversations

J'ai participé au podcast The Changelog pour expliquer pourquoi les mainteneurs et contributeurs doivent se soucier des changelogs et également des motivations derrière ce projet.

Une nouvelle version est disponible: Français 1.1.0

Tenez un Changelog

Ne laissez pas vos amis utiliser les logs git comme changelogs

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

## [Unreleased]

## [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

Qu'est-ce qu'un changelog ?

Un changelog (journal des modifications) est un fichier qui contient une liste triée chronologiquement des changements notables pour chaque version d’un projet

Pourquoi tenir un changelog ?

Pour permettre aux utilisateurs et contributeurs de voir précisément quels changements notables ont été faits entre chaque publication (ou version) d'un projet.

Qui a besoin d'un changelog ?

Tout le monde. Qu'ils soient consommateurs ou développeurs, les utilisateurs de logiciels sont des êtres humains qui se soucient de connaître le contenu des logiciels qu'ils utilisent. Quand un logiciel change, ces mêmes personnes veulent savoir comment et pourquoi.

Comment créer un bon changelog ?

Principes Directeurs

  • Les changelogs sont pour les êtres humains, pas les machines.
  • Il doit y avoir une section pour chaque version.
  • Les changements similaires doivent être groupés.
  • Les versions et sections doivent être liables.
  • La version la plus récente se situe en haut du fichier.
  • La date de publication de chaque version est indiquée.
  • Indiquer si le projet respecte le Versionnage Sémantique.

Types de changements

  • Added pour les nouvelles fonctionnalités.
  • Changed pour les changements aux fonctionnalités préexistantes.
  • Deprecated pour les fonctionnalités qui seront bientôt supprimées.
  • Removed pour les fonctionnalités désormais supprimées.
  • Fixed pour les corrections de bugs.
  • Security en cas de vulnérabilités.

Comment puis-je minimiser le travail nécessaire pour maintenir un changelog ?

Gardez une section Unreleased en haut du fichier afin de lister tous les changements qui n'ont pas encore été publiés.

Cela permet deux choses:

  • Les gens peuvent voir les changements auxquels ils peuvent s’attendre dans les prochaines publications.
  • Au moment de la publication, vous pouvez déplacer les changements listés dans la section Unreleased dans la section d'une nouvelle version.

Est-ce que les changelogs peuvent être mauvais ?

Oui. Voici quelques exemples de changelogs plutôt inutiles.

Diffs de journaux gits

Utiliser des diffs de journaux gits en tant que changelogs est une mauvaise idée: ils sont remplis de bruit. Les journaux gits sont remplis de choses comme des commits de merge, des commits avec des titres obscurs, des changements concernant la documentation, etc.

Le but d'un commit est de documenter une étape dans l'évolution du code source. Certains projets nettoient leurs commits, d'autres non.

Le but d'une section de changelog est de documenter les différences notables entre deux versions, souvent à travers de multiples commits, afin de les communiquer clairement aux utilisateurs.

Ignorer les dépréciations

Lorsque l'on passe d'une version d'un logiciel à une autre, il devrait être très clair si quelque chose peut ne plus fonctionner. Il devrait être possible de mettre à jour vers une version qui offre une liste des fonctionnalités dépréciées, de retirer ce qui est déprécié, puis de mettre à jour vers la version où les dépréciations deviennent des suppressions de fonctionnalités.

Si vous ne faites rien d'autre, listez les dépréciations, les supressions de fonctionnalités, et tous les changements non rétrocompatibles dans votre changelog.

Dates confuses

Aux États-Unis, les gens mettent le mois en premier (06-02-2012 pour le 2 juin 2012), tandis que beaucoup de gens dans le reste du monde l’écrivent de la façon robotique suivante « 2 Juin 2012 », alors qu’ils le prononcent différement. 2012-06-02 fonctionne logiquement, du plus grand au plus petit, ne laisse pas place à la confusion avec un autre format et est un standard ISO. C'est pour cela que ce format de date est recommandé pour les changelogs.

Inconsistent Changes

Un changelog qui ne mentionne qu'une portion des changements peut être aussi dangereux que l'absence totale de changelog. Bien que la majorité des changements peuvent être sans conséquence, par exemple retirer un simple espace dans un texte ne nécessite probablement pas de mention, tout changements important devrait être mentionné dans le changelog. Sans consistence dans l'application des changements, vos utilisateurs pourraient être induit en erreur et penser que le changelog est la seule source de d'information. Ça devrait être le cas. Son pouvoir implique des responsabilités: un bon changelog est synonyme avec un changelog mis à jour de façon consistante.

Questions fréquemment posées

Y a-t-il un format de changelog standard ?

Pas vraiment. Il y a le guide de style GNU pour les changelogs, ou les instructions GNU de deux paragraphes pour les fichiers NEWS. Ces deux ressources sont inappropriées et insuffisantes.

Ce projet vise à devenir une meilleure convention pour les changelogs. Il a pour origine l'observation et le rassemblement des bonne pratiques dans la communauté open source.

Les critiques constructives, discussions et suggestions pour améliorer ce projet sont les bienvenues..

Comment doit-être nommé le fichier de changelog ?

Nommez-le CHANGELOG.md. Certains projets utilisent HISTORY, NEWS ou RELEASES.

Même s'il est facile d'imaginer que le nom d'un fichier de changelog n'a pas grand intérêt, pourquoi rendre la tâche plus difficile que nécessaire aux utilisateurs qui cherchent à trouver les changements notables de votre projet ?

Quid de GitHub Releases ?

C'est une excellente initiative. Releases peut être utilisé pour transformer de simples tags git (par exemple un tag nommé v1.0.0) en notes de publication riches soit en ajoutant manuellement des notes soit en utilisant les messages de tags gits annotés et en les transformant en notes.

GitHub Releases crée un changelog non-portable qui n'est visible par les utilisateurs qu'à l'intérieur du contexte de GitHub. Il est possible de suivre le même format que Keep a Changelog, mais c'est plus difficile.

La version actuelle de GitHub Releases est également difficile à découvrir pour les utilisateurs, contrairement aux fichiers en majuscules typiques (README, CONTRIBUTING, etc.). Un autre souci mineur est que l'interface n'offre actuellement pas de lien vers les journaux gits entre chaque publication.

Les changelogs peuvent-ils être parsés automatiquement ?

C'est difficile, parce que les gens suivent des formats et utilisent des noms de fichiers très différents.

Vandamme est une Ruby gem créée par l'équipe Gemnasium qui parse les changelogs de beaucoup (mais pas tous) de projets open source.

Qu'en est-il des publications « yanked » (retirées) ?

Les publications yanked sont des version qui ont dû être retirées du fait d'un sérieux bug ou d'un problème de sécurité. Souvent ces version n'apparaissent même pas dans les changelogs. Elles devraient. Voilà comment les afficher :

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

Le tag [YANKED] n'est pas mis en avant pour rien. Il est important qu'il soit remarqué. Il est également plus facile à digérer pour un programme puisqu'il est entouré par des crochets.

Devriez-vous réécrire un changelog ?

Bien sûr. Il y a toujours de bonnes raisons d'améliorer un changelog. J'ouvre souvent des pull requests pour ajouter des publications manquantes sur des projets open source avec des changelogs non-maintenus.

Il est aussi possible que vous découvriez que vous aviez oublié de mentionner un changement majeur dans les notes de version. Il est évidemment important que vous mettiez votre changelog à jour dans ce cas.

Comment puis-je contribuer ?

Ce document n'est pas la **vérité**; c'est mon opinion soigneusement réfléchie, accompagnée d'informations et d'exemples que j'ai rassemblés.

C'est parce que je veux que notre communauté atteigne un consensus. Je crois que la discussion est aussi importante que le résultat final.

Donc s'il vous plaît, participez.

Conversations

J'ai participé au podcast The Changelog pour expliquer pourquoi les mainteneurs et contributeurs doivent se soucier des changelogs et également des motivations derrière ce projet.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Vodite Changelog

Ne dajte prijateljima da trpaju git logove u changelogove.

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

## [Unreleased]

## [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

Što je changelog?

Changelog je datoteka koja sadrži uređeni kronološki poredani popis značajnih promjena unutar svake verzije projekta.

Zašto voditi changelog?

Kako bi korisnici i suradnici detaljno vidjeli značajne promjene među pojedinim izdanjima (ili verzijama) projekta.

Kome treba changelog?

Ljudima. Bilo da su uobičajeni korisnici ili programeri, krajnji su korisnici softvera ljudska bića kojima je stalo do toga od čega je sastavljen. Kada se softver mijenja, korisnici žele znati kako i zašto.

Kako kreirati dobar changelog?

Glavna načela

  • Changelogs služi ljudima, ne strojevima.
  • Potrebno je stvoriti unos za svaku verziju.
  • Slične promjene potrebno je grupirati.
  • Verzije i sekcije trebaju imati poveznicu.
  • Posljednja verzija treba biti na prvom mjestu.
  • Datum izdavanja svake pojedine verzije treba biti vidljiv.
  • Navesti prati li se Semantičko verzioniranje.

Vrste promjena

  • Added za nove funkcionalnosti.
  • Changed za promjene u postojećim funkcionalnostima.
  • Deprecated za funkcionalnosti koje će se ukloniti u budućim verzijama.
  • Removed za uklonjene funkcionalnosti.
  • Fixed za ispravke bugova.
  • Security za slučaj sigurnosnih propusta.

Kako održavati changelog sa što manje napora?

Na vrh postavite Unreleased sekciju gdje ćete navoditi nadolazeće promjene.

To radimo iz dva razloga:

  • Korisnici mogu vidjeti promjene koje mogu očekivati u nadolazećim izdanjima
  • Kod izdavanja nove verzije, moguće je Unreleased sekciju samo preimenovati u novo izdanje.

Može li changelog biti loš?

Naravno. Postoji nekoliko slučajeva u kojima changelog može biti beskoristan.

Commit log diffovi

Korištenje commit log diffova u svrhu changeloga nije dobra ideja: puni su šuma. Npr. merge commitovi, commitovi s nejasnim naslovima, promjene u dokumentaciji i sl.

Svrha commita je da bilježi korake u razvoju izvornog koda. U nekim projektima se comittovi čiste, no ponekad i ne.

Svrha unosa u changelogu je da bilježi značajne razlike, a često kroz više commitova i jasno ih prenese krajnjem korisniku.

Ignoriranje uklonjenih funkcionalnosti

Kad korisnici nadograde softver na noviju verziju, treba biti potpuno jasno da postoji mogućnost da će se neki dio pokvariti. Softver treba biti moguće nadograditi na verziju koja će navesti funkcionalnosti koje trebaju biti uklonjene, uklanja takve te se kasnije može nadograditi na verziju gdje su već uklonjene.

U najmanju ruku, potrebno je u changelogu navoditi funkcionalnosti koje će biti uklonjene, funkcionalnosti koje su uklonjene i promjene koje će utjecati na rad softvera (breaking change).

Nejasni datumi

Regionalni formati datuma variraju diljem svijeta, pa je često teško pronaći format datuma koji će odgovarati svima. Prednost datuma u formatu 2017-07-17 je to što je poredan od veće prema manjoj jedinici: godina, mjesec, dan. Ovaj je format također teško zamijeniti s drugim regionalnim formatima, za razliku od nekih koji, primjerice mijenjaju poziciju oznake mjeseca i dana. Iz tog razloga, a i zbog toga što je navedeni format ISO standard, taj se format preporuča za changelog unose.

Česta pitanja

Postoji li standardni changelog format?

Zapravo ne. Postoji GNU changelog stilski priručnik, i GNU NEWS file "priručnik od dva odlomka". Nijedan nije adekvatan ni dovoljan.

Cilj je ovoga projekta kvalitetniji changelog standard. Nastao je prikupljanjem primjera dobra prakse u open source zajednici.

Konstruktivna kritika, raprave i prijedlozi za poboljšanje su dobrodošli.

Kako nazvati changelog datoteku?

Dajemo joj naziv CHANGELOG.md. Neki projekti još koriste HISTORY, NEWS ili RELEASES.

Iako može djelovati da naziv changelog datoteke i nije toliko bitan, čemu otežavati korisnicima da dođu do informacije o promjenama?

Što s GitHub Releases?

To je ozbiljna inicijativa. Releases se mogu koristiti kako bi git oznake (npr. git oznaka v1.0.0) pretvorili u opširnije bilješke o izdanju, upisujući ih ručno ili pak preuzimajući anotirane git oznake i pretvarajući ih u unose.

GitHub Releases stvara statični changelog vidljiv korisnicima unutar GitHub repozitorija. Moguće ih je urediti u format koji bi odgovarao Vodite changelog formatu, no često je nešto opširniji.

Trenutna GitHub releases verzija i nije baš sasvim vidljiva korisnicima, za razliku od uobičajenih datoteka označenih velikim slovima (README, CONTRIBUTING, itd.). Još je jedan manji problem što trenutno sučelje ne nudi poveznice na commit logove između izdanja.

Mogu li changelogovi automatski parsati?

Teže, jer se koriste vrlo različiti formati, kao i nazivi datoteka.

Vandamme je Ruby gem koji je kreirao Gemnasium tim i može parsati mnoge (ali ne sve) changeloge projekata otvorenog koda.

Što s povučenim izdanjima?

Povučena ili 'Yanked' izdanja su verzije koje su uklonjene zbog ozbiljnijeg buga ili sigurnosnog propusta. Takva se izdanja najčešće i ne pojavljuju u changelogu, iako bi trebala. Trebala bi biti navedena na sljedeći način:

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

[YANKED] oznaka jasno je istaknuta s razlogom. Bitno je da ju je lako primijetiti. Buduće da je okružena zagradama, također ju je lakše parsati.

Je li potrebno prepravljati changelog?

Naravno. Često postoje dobri razlozi da bismo poboljšali changelog. Ja često otvaram pull requestove kako bih dodao nedostajuća izdanja projektima otvorenog koda, koji ne održavaju changeloge.

Moguće je, također da otkrijete, kako ste zaboravili navesti promjenu koja bi utjecala na rad (breaking change). U tom je slučaju, očito, vrlo bitno ažurirati changelog.

Kako doprinijeti?

Ovaj dokument nije Sveto Pismo; ovo je samo pažljivo razmotreno mišljenje, uz informacije i primjere koje sam skupio.

Razlog je tome to što želim da zajednica postigne konsenzus. Vjerujem, također, da je i sama rasprava bitna kao i krajnjni rezultat.

Zato, molimo uskočite.

Razgovori

Gostovao sam na The Changelog podcastu gdje sam pokušao objasniti zašto začetnici projekata i suradnici trebaju brinuti o changelogovima te motivaciji iza ovog projekta.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Vodite Changelog

Ne dajte prijateljima da trpaju git logove u changelogove.

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

## [Unreleased]

## [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

Što je changelog?

Changelog je datoteka koja sadrži uređeni kronološki poredani popis značajnih promjena unutar svake verzije projekta.

Zašto voditi changelog?

Kako bi korisnici i suradnici detaljno vidjeli značajne promjene među pojedinim izdanjima (ili verzijama) projekta.

Kome treba changelog?

Ljudima. Bilo da su uobičajeni korisnici ili programeri, krajnji su korisnici softvera ljudska bića kojima je stalo do toga od čega je sastavljen. Kada se softver mijenja, korisnici žele znati kako i zašto.

Kako kreirati dobar changelog?

Glavna načela

  • Changelogs služi ljudima, ne strojevima.
  • Potrebno je stvoriti unos za svaku verziju.
  • Slične promjene potrebno je grupirati.
  • Verzije i sekcije trebaju imati poveznicu.
  • Posljednja verzija treba biti na prvom mjestu.
  • Datum izdavanja svake pojedine verzije treba biti vidljiv.
  • Navesti prati li se Semantičko verzioniranje.

Vrste promjena

  • Added za nove funkcionalnosti.
  • Changed za promjene u postojećim funkcionalnostima.
  • Deprecated za funkcionalnosti koje će se ukloniti u budućim verzijama.
  • Removed za uklonjene funkcionalnosti.
  • Fixed za ispravke bugova.
  • Security za slučaj sigurnosnih propusta.

Kako održavati changelog sa što manje napora?

Na vrh postavite Unreleased sekciju gdje ćete navoditi nadolazeće promjene.

To radimo iz dva razloga:

  • Korisnici mogu vidjeti promjene koje mogu očekivati u nadolazećim izdanjima
  • Kod izdavanja nove verzije, moguće je Unreleased sekciju samo preimenovati u novo izdanje.

Može li changelog biti loš?

Naravno. Postoji nekoliko slučajeva u kojima changelog može biti beskoristan.

Commit log diffovi

Korištenje commit log diffova u svrhu changeloga nije dobra ideja: puni su šuma. Npr. merge commitovi, commitovi s nejasnim naslovima, promjene u dokumentaciji i sl.

Svrha commita je da bilježi korake u razvoju izvornog koda. U nekim projektima se comittovi čiste, no ponekad i ne.

Svrha unosa u changelogu je da bilježi značajne razlike, a često kroz više commitova i jasno ih prenese krajnjem korisniku.

Ignoriranje uklonjenih funkcionalnosti

Kad korisnici nadograde softver na noviju verziju, treba biti potpuno jasno da postoji mogućnost da će se neki dio pokvariti. Softver treba biti moguće nadograditi na verziju koja će navesti funkcionalnosti koje trebaju biti uklonjene, uklanja takve te se kasnije može nadograditi na verziju gdje su već uklonjene.

U najmanju ruku, potrebno je u changelogu navoditi funkcionalnosti koje će biti uklonjene, funkcionalnosti koje su uklonjene i promjene koje će utjecati na rad softvera (breaking change).

Nejasni datumi

Regionalni formati datuma variraju diljem svijeta, pa je često teško pronaći format datuma koji će odgovarati svima. Prednost datuma u formatu 2017-07-17 je to što je poredan od veće prema manjoj jedinici: godina, mjesec, dan. Ovaj je format također teško zamijeniti s drugim regionalnim formatima, za razliku od nekih koji, primjerice mijenjaju poziciju oznake mjeseca i dana. Iz tog razloga, a i zbog toga što je navedeni format ISO standard, taj se format preporuča za changelog unose.

Česta pitanja

Postoji li standardni changelog format?

Zapravo ne. Postoji GNU changelog stilski priručnik, i GNU NEWS file "priručnik od dva odlomka". Nijedan nije adekvatan ni dovoljan.

Cilj je ovoga projekta kvalitetniji changelog standard. Nastao je prikupljanjem primjera dobra prakse u open source zajednici.

Konstruktivna kritika, raprave i prijedlozi za poboljšanje su dobrodošli.

Kako nazvati changelog datoteku?

Dajemo joj naziv CHANGELOG.md. Neki projekti još koriste HISTORY, NEWS ili RELEASES.

Iako može djelovati da naziv changelog datoteke i nije toliko bitan, čemu otežavati korisnicima da dođu do informacije o promjenama?

Što s GitHub Releases?

To je ozbiljna inicijativa. Releases se mogu koristiti kako bi git oznake (npr. git oznaka v1.0.0) pretvorili u opširnije bilješke o izdanju, upisujući ih ručno ili pak preuzimajući anotirane git oznake i pretvarajući ih u unose.

GitHub Releases stvara statični changelog vidljiv korisnicima unutar GitHub repozitorija. Moguće ih je urediti u format koji bi odgovarao Vodite changelog formatu, no često je nešto opširniji.

Trenutna GitHub releases verzija i nije baš sasvim vidljiva korisnicima, za razliku od uobičajenih datoteka označenih velikim slovima (README, CONTRIBUTING, itd.). Još je jedan manji problem što trenutno sučelje ne nudi poveznice na commit logove između izdanja.

Mogu li changelogovi automatski parsati?

Teže, jer se koriste vrlo različiti formati, kao i nazivi datoteka.

Vandamme je Ruby gem koji je kreirao Gemnasium tim i može parsati mnoge (ali ne sve) changeloge projekata otvorenog koda.

Što s povučenim izdanjima?

Povučena ili 'Yanked' izdanja su verzije koje su uklonjene zbog ozbiljnijeg buga ili sigurnosnog propusta. Takva se izdanja najčešće i ne pojavljuju u changelogu, iako bi trebala. Trebala bi biti navedena na sljedeći način:

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

[YANKED] oznaka jasno je istaknuta s razlogom. Bitno je da ju je lako primijetiti. Buduće da je okružena zagradama, također ju je lakše parsati.

Je li potrebno prepravljati changelog?

Naravno. Često postoje dobri razlozi da bismo poboljšali changelog. Ja često otvaram pull requestove kako bih dodao nedostajuća izdanja projektima otvorenog koda, koji ne održavaju changeloge.

Moguće je, također da otkrijete, kako ste zaboravili navesti promjenu koja bi utjecala na rad (breaking change). U tom je slučaju, očito, vrlo bitno ažurirati changelog.

Kako doprinijeti?

Ovaj dokument nije Sveto Pismo; ovo je samo pažljivo razmotreno mišljenje, uz informacije i primjere koje sam skupio.

Razlog je tome to što želim da zajednica postigne konsenzus. Vjerujem, također, da je i sama rasprava bitna kao i krajnjni rezultat.

Zato, molimo uskočite.

Razgovori

Gostovao sam na The Changelog podcastu gdje sam pokušao objasniti zašto začetnici projekata i suradnici trebaju brinuti o changelogovima te motivaciji iza ovog projekta.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Pencatatan Changelog

Standarisasi pencatatan Changelog untuk kolaborasi yang lebih baik

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

## [Unreleased]

## [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

Apa itu changelog?

Changelog adalah sebuah file yang berisi daftar perubahan yang diurutkan secara kronologis untuk setiap versi dari sebuah proyek.

Kenapa perlu untuk mencatat changelog?

Untuk mempermudah pengguna dan kontributor melihat perubahan apa saja yang terjadi antara setiap rilis (atau versi) dari sebuah proyek.

Siapa yang membutuhkan changelog?

Semua orang membutuhkannya. Baik pengguna ataupun pengembang, setiap orang yang menggunakan perangkat lunak adalah manusia yang peduli tentang apa yang ada di dalam perangkat lunak tersebut. Ketika perangkat lunak berubah, mereka ingin tahu apa yang berubah dan mengapa.

Bagaimana cara membuat changelog yang baik?

Prinsip-prinsip Dasar

  • Changelog ditulis untuk manusia, bukan mesin.
  • Harus ada catatan untuk setiap versi.
  • Setiap tipe perubahan yang sama harus dikelompokkan.
  • Versi dan seksi harus dapat dirujuk.
  • Versi yang terakhir harus ditulis di paling atas.
  • Tanggal rilis setiap versi harus ditulis.
  • Berikan informasi jika kalian menggunakan Semantic Versioning.

Jenis-jenis perubahan

  • Added/Ditambahkan untuk fitur yang baru.
  • Changed/Diubah untuk perubahan di fitur yang sudah ada.
  • Deprecated/Akan Dihilangkan untuk fitur yang akan dihapus dalam waktu dekat.
  • Removed/Dihilangkan untuk fitur yang sudah dihapus.
  • Fixed/Diperbaiki untuk setiap perbaikan bugs.
  • Security/Keamanan jika ada celah keamanan.

Apa yang bisa saya lakukan untuk mempermudah pemeliharaan changelog?

Sisakan bagian Unreleased/Belum Dirilis di bagian paling atas file changelog untuk mencatat perubahan yang akan datang.

Hal ini berguna untuk dua hal:

  • Orang-orang bisa melihat perubahan apa saja yang akan datang.
  • Saat waktu rilis datang, tinggal pindahkan bagian Unreleased/Belum Dirilis ke catatan rilis versi baru di bawah.

Apakah changelog bisa menjadi tidak bermanfaat?

Bisa, berikut beberapa skenario ketika changelog menjadi tidak bermanfaat:

Menggunakan Commit log diffs sebagai changelog

Menggunakan commit log diffs (catatan perbedaan setiap commit) bisa membuat changelog susah untuk dibaca. Commit dengan judul yang tidak jelas, dokumentasi perubahan, dan sebagainya, malah akan membuat changelog terlalu berisik dan susah dibaca.

Tujuan utama dari commit adalah untuk mencatat setiap perubahan dari source code. Beberapa proyek merapikan commitnya, beberapa tidak.

Tujuan dari changelog adalah untuk mencatat perubahan yang pantas untuk dicatat, bisa jadi beberapa commit dijadikan satu catatan untuk lebih memudahkan pembaca.

Mengabaikan Deprecations (fitur yang akan dihilangkan)

Saat menaikkan versi, harus ditulis dengan jelas apa saja yang kira-kira bisa membuat sistem tidak berjalan. Sebaiknya terdapat versi yang mencatat apa saja yang akan dihilangkan, lalu menghapus fitur yang dihilangkan, dan naikkan lagi ke versi dengan fitur yang sudah dihilangkan.

Jika kalian tidak mengubah apapun, tetap catat fitur yang akan dihilangkan, fitur yang sudah dihilangkan, dan perubahan-perubahan lain yang bisa membuat sistem tidak berjalan.

Perbedaan Format Tanggal

Format tanggal regional berbeda-beda sesuai dengan budaya masing-masing, dan seringkali perbedaan ini susah untuk dipahami dan dimengerti. Penggunaan format tanggal 2017-07-17 lebih mudah untuk dimengerti, karena diurutkan berdasarkan unit terbesar: tahun, bulan, dan tanggal. Format ini juga merupakan Standar ISO, sehingga inilah yang dipakai untuk pencatatan changelog.

Pertanyaan yang Sering Ditanyakan

Apakah ada standar untuk format changelog?

Tidak, ada format GNU untuk changelog, atau format 2 paragraf GNU NEWS. Keduanya tidak benar-benar cukup, gunakan format yang disetujui tim masing-masing.

Proyek ini ditujukan untuk membuat aturan changelog yang lebih baik berdasarkan observasi beberapa changelog di komunitas open source dan menyatukan mereka.

Kritik yang membangun, diskusi, dan saran untuk perbaikan sangat diterima.

Apa nama file yang cocok untuk file changelog?

Gunakan nama CHANGELOG.md, beberapa proyek menggunakan HISTORY, NEWS atau RELEASE.

Sebenarnya tidak terlalu susah untuk menamai file changelog, cukup berikan nama yang mudah dikenali oleh orang-orang supaya mudah untuk dibaca.

Apa itu GitHub Releases?

Github Release adalah salah satu insiatif dari GitHub untuk membuat changelog berdasarkan git tags, contohnya, tag dengan nama v1.0.0. Isi dari changelog bisa ditulis manual atau menggunakan pesan yang ditulis bersamaan dengan tags.

GitHub Releases membuat changelog yang tidak portable dan hanya bisa bekerja dengan baik di lingkup GitHub. Sangat mungkin untuk membuat GitHub Releases terlihat mirip dengan format pencatatan changelog yang dijelaskan di sini, tapi butuh usaha ekstra.

Versi GitHub releases yang sekarang juga tidak terlalu umum untuk orang-orang, dan hanya bisa dibuka melalui sub menu di GitHub, berbeda dengan file-file seperti (README, CONTRIBUTING, dsb.) yang langsung terlihat saat proyek pertama kali dibuka. Keterbatasan lainnya adalah tidak adanya link di GitHub releases.

Apakah Changelog Bisa Diparse Secara Otomatis?

Susah, karena orang-orang menggunakan versi dan format changelog yang berbeda-beda.

Vandamme adalah Ruby Gem yang dibuat oleh tim Gemnasium yang bisa mem-parsing (tetapi tidak semua) changelog proyek open source.

Bagaimana dengan Rilis YANKED (rilis yang dibatalkan)?

Rilis yang dibatalkan adalah rilis yang dibatalkan, bisa jadi karena ada bug yang fatal dan permasalahan keamanan. Versi ini sering tidak dimasukkan ke changelog, padahal seharusnya ditulis sebagaimana berikut.

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

Tag [YANKED/DIBATALKAN] ditulis dengan jelas supaya orang memperhatikannya, dan dikurung dengan kurung kotak supaya mudah untuk diparse.

Bolehkah Menulis Ulang Changelog?

Tentu saja, ada banyak alasan bagus untuk menulis ulang changelog, salah satunya untuk rilis-rilis yang lupa untuk dituliskan di beberapa proyek.

Juga sangat mungkin saat menulis ulang, kalian ingat tentang perubahan yang bisa membuat sistem tidak bekerja yang belum dituliskan. Dalam hal ini, sangat penting untuk mengubah changelog supaya datanya lebih akurat.

Bagaimana Saya Bisa Berkontribusi?

Dokumen ini bukan kebenaran absolut, ini hanyalah opini yang dikumpulkan dari beberapa informasi dan contoh yang kami kumpulkan.

Ini karena kami ingin komunitas terus berdiskusi untuk mencapai konsensus yang terbaik untuk pencatatan changelog.

Jadi silahkan, kirimkan saran.

Percakapan

Kami mengisi acara di Podcast Changelog untuk berbicara tentang kenapa maintainer dan kontributor harus peduli dengan changelog, dan motivasi dari proyek ini.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Pencatatan Changelog

Standarisasi pencatatan Changelog untuk kolaborasi yang lebih baik

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

## [Unreleased]

## [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

Apa itu changelog?

Changelog adalah sebuah file yang berisi daftar perubahan yang diurutkan secara kronologis untuk setiap versi dari sebuah proyek.

Kenapa perlu untuk mencatat changelog?

Untuk mempermudah pengguna dan kontributor melihat perubahan apa saja yang terjadi antara setiap rilis (atau versi) dari sebuah proyek.

Siapa yang membutuhkan changelog?

Semua orang membutuhkannya. Baik pengguna ataupun pengembang, setiap orang yang menggunakan perangkat lunak adalah manusia yang peduli tentang apa yang ada di dalam perangkat lunak tersebut. Ketika perangkat lunak berubah, mereka ingin tahu apa yang berubah dan mengapa.

Bagaimana cara membuat changelog yang baik?

Prinsip-prinsip Dasar

  • Changelog ditulis untuk manusia, bukan mesin.
  • Harus ada catatan untuk setiap versi.
  • Setiap tipe perubahan yang sama harus dikelompokkan.
  • Versi dan seksi harus dapat dirujuk.
  • Versi yang terakhir harus ditulis di paling atas.
  • Tanggal rilis setiap versi harus ditulis.
  • Berikan informasi jika kalian menggunakan Semantic Versioning.

Jenis-jenis perubahan

  • Added/Ditambahkan untuk fitur yang baru.
  • Changed/Diubah untuk perubahan di fitur yang sudah ada.
  • Deprecated/Akan Dihilangkan untuk fitur yang akan dihapus dalam waktu dekat.
  • Removed/Dihilangkan untuk fitur yang sudah dihapus.
  • Fixed/Diperbaiki untuk setiap perbaikan bugs.
  • Security/Keamanan jika ada celah keamanan.

Apa yang bisa saya lakukan untuk mempermudah pemeliharaan changelog?

Sisakan bagian Unreleased/Belum Dirilis di bagian paling atas file changelog untuk mencatat perubahan yang akan datang.

Hal ini berguna untuk dua hal:

  • Orang-orang bisa melihat perubahan apa saja yang akan datang.
  • Saat waktu rilis datang, tinggal pindahkan bagian Unreleased/Belum Dirilis ke catatan rilis versi baru di bawah.

Apakah changelog bisa menjadi tidak bermanfaat?

Bisa, berikut beberapa skenario ketika changelog menjadi tidak bermanfaat:

Menggunakan Commit log diffs sebagai changelog

Menggunakan commit log diffs (catatan perbedaan setiap commit) bisa membuat changelog susah untuk dibaca. Commit dengan judul yang tidak jelas, dokumentasi perubahan, dan sebagainya, malah akan membuat changelog terlalu berisik dan susah dibaca.

Tujuan utama dari commit adalah untuk mencatat setiap perubahan dari source code. Beberapa proyek merapikan commitnya, beberapa tidak.

Tujuan dari changelog adalah untuk mencatat perubahan yang pantas untuk dicatat, bisa jadi beberapa commit dijadikan satu catatan untuk lebih memudahkan pembaca.

Mengabaikan Deprecations (fitur yang akan dihilangkan)

Saat menaikkan versi, harus ditulis dengan jelas apa saja yang kira-kira bisa membuat sistem tidak berjalan. Sebaiknya terdapat versi yang mencatat apa saja yang akan dihilangkan, lalu menghapus fitur yang dihilangkan, dan naikkan lagi ke versi dengan fitur yang sudah dihilangkan.

Jika kalian tidak mengubah apapun, tetap catat fitur yang akan dihilangkan, fitur yang sudah dihilangkan, dan perubahan-perubahan lain yang bisa membuat sistem tidak berjalan.

Perbedaan Format Tanggal

Format tanggal regional berbeda-beda sesuai dengan budaya masing-masing, dan seringkali perbedaan ini susah untuk dipahami dan dimengerti. Penggunaan format tanggal 2017-07-17 lebih mudah untuk dimengerti, karena diurutkan berdasarkan unit terbesar: tahun, bulan, dan tanggal. Format ini juga merupakan Standar ISO, sehingga inilah yang dipakai untuk pencatatan changelog.

Pertanyaan yang Sering Ditanyakan

Apakah ada standar untuk format changelog?

Tidak, ada format GNU untuk changelog, atau format 2 paragraf GNU NEWS. Keduanya tidak benar-benar cukup, gunakan format yang disetujui tim masing-masing.

Proyek ini ditujukan untuk membuat aturan changelog yang lebih baik berdasarkan observasi beberapa changelog di komunitas open source dan menyatukan mereka.

Kritik yang membangun, diskusi, dan saran untuk perbaikan sangat diterima.

Apa nama file yang cocok untuk file changelog?

Gunakan nama CHANGELOG.md, beberapa proyek menggunakan HISTORY, NEWS atau RELEASE.

Sebenarnya tidak terlalu susah untuk menamai file changelog, cukup berikan nama yang mudah dikenali oleh orang-orang supaya mudah untuk dibaca.

Apa itu GitHub Releases?

Github Release adalah salah satu insiatif dari GitHub untuk membuat changelog berdasarkan git tags, contohnya, tag dengan nama v1.0.0. Isi dari changelog bisa ditulis manual atau menggunakan pesan yang ditulis bersamaan dengan tags.

GitHub Releases membuat changelog yang tidak portable dan hanya bisa bekerja dengan baik di lingkup GitHub. Sangat mungkin untuk membuat GitHub Releases terlihat mirip dengan format pencatatan changelog yang dijelaskan di sini, tapi butuh usaha ekstra.

Versi GitHub releases yang sekarang juga tidak terlalu umum untuk orang-orang, dan hanya bisa dibuka melalui sub menu di GitHub, berbeda dengan file-file seperti (README, CONTRIBUTING, dsb.) yang langsung terlihat saat proyek pertama kali dibuka. Keterbatasan lainnya adalah tidak adanya link di GitHub releases.

Apakah Changelog Bisa Diparse Secara Otomatis?

Susah, karena orang-orang menggunakan versi dan format changelog yang berbeda-beda.

Vandamme adalah Ruby Gem yang dibuat oleh tim Gemnasium yang bisa mem-parsing (tetapi tidak semua) changelog proyek open source.

Bagaimana dengan Rilis YANKED (rilis yang dibatalkan)?

Rilis yang dibatalkan adalah rilis yang dibatalkan, bisa jadi karena ada bug yang fatal dan permasalahan keamanan. Versi ini sering tidak dimasukkan ke changelog, padahal seharusnya ditulis sebagaimana berikut.

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

Tag [YANKED/DIBATALKAN] ditulis dengan jelas supaya orang memperhatikannya, dan dikurung dengan kurung kotak supaya mudah untuk diparse.

Bolehkah Menulis Ulang Changelog?

Tentu saja, ada banyak alasan bagus untuk menulis ulang changelog, salah satunya untuk rilis-rilis yang lupa untuk dituliskan di beberapa proyek.

Juga sangat mungkin saat menulis ulang, kalian ingat tentang perubahan yang bisa membuat sistem tidak bekerja yang belum dituliskan. Dalam hal ini, sangat penting untuk mengubah changelog supaya datanya lebih akurat.

Bagaimana Saya Bisa Berkontribusi?

Dokumen ini bukan kebenaran absolut, ini hanyalah opini yang dikumpulkan dari beberapa informasi dan contoh yang kami kumpulkan.

Ini karena kami ingin komunitas terus berdiskusi untuk mencapai konsensus yang terbaik untuk pencatatan changelog.

Jadi silahkan, kirimkan saran.

Percakapan

Kami mengisi acara di Podcast Changelog untuk berbicara tentang kenapa maintainer dan kontributor harus peduli dengan changelog, dan motivasi dari proyek ini.

L'ultima versione (1.1.0) non è ancora disponibile in Italiano, ma la potete leggere in Inglese per ora e potete contribuire a tradurla.

Mantenere un CHANGELOG

Non lasciate che i vostri amici copino e incollino i git log nei CHANGELOG ™

Cos'è un change log?

Un change log è un file che contiene una lista curata e ordinata cronologicamente delle modifiche degne di nota per ogni versione di un progetto.

# 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.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?".

A cosa serve un change log?

Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche importanti sono state fatte tra ogni release (o versione) del progetto.

Perché dovrebbe importarmi?

Perché gli strumenti software sono fatti per le persone. Se non ti importa, perché contribuisci all'open source? Di certo ci deve essere un "kernel" (ha!) di interesse da qualche parte in quel tuo amorevole cervello.

Nel podcast "The Changelog" con Adam Stacoviak e Jerod Santo (titolo appropriato, vero?) ho parlato del perché maintainer e contribuenti dovrebbero esserne interessati, e delle motivazioni dietro a questo progetto. Se avete tempo (1:06), vale la pena ascoltarlo.

Come si può fare un buon change log?

Sono contento che tu l'abbia chiesto.

Un buon change log è guidato dai seguenti principi:

Come posso minimizzare lo sforzo richiesto?

Usa sempre una sezione "Unreleased" all'inizio per tenere traccia di qualsiasi modifica.

Questo serve per due scopi:

Cosa fa piangere gli unicorni?

Bene...vediamo un po'.

C'è di più. Aiutatemi a collezionare queste "lacrime di unicorno" aprendo una "issue" o una pull request.

Esiste un formato standard per i change log?

Purtroppo no. Calma. So che state furiosamente correndo a cercare quel link alla guida di stile per i change log GNU, o alle linee guida per or il file a due paragrafi GNU NEWS. La guida GNU è un buon punto di partenza, ma è tristemente ingenuo. Non c'è nulla di male nell'essere ingenuo, ma quando le persone cercano una guida, questa caratteristica è raramente d'aiuto. Specialmente se ci sono molte situazioni e casi limite da gestire.

Questo progetto contiene ciò che spero diventerà una migliore convenzione per i file CHANGELOG. Non credo che lo status quo sia sufficientemente buono, e penso che noi, come comunità, possiamo arrivare a convenzioni migliori se tentiamo di estrarre le pratiche migliori da progetti software reali. Vi consiglio di guardarvi intorno e ricordare che ogni discussione e suggerimento per migliorare sono sempre benvenuti!

Come si dovrebbe chiamare il file contenente il change log?

Se non l'avete dedotto dall'esempio qui sopra, CHANGELOG.md è la convenzione migliore finora.

Alcuni progetti usano anche HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.

È un disastro. Tutti questi nomi contribuiscono solo a rendere più difficile trovarlo.

Perché la gente non si limita ad usare diff di git log?

Perché i log diff sono pieni di rumore, per loro natura. Non potrebbero creare un change log decente nemmeno in un ipotetico progetto gestito da perfetti umani che non fanno mai errori di digitazione, non dimenticano mai di fare commit dei nuovi file, non dimenticano mai alcuna parte di un refactoring. Lo scopo di un commit è di documentare un passo atomico nel processo di evoluzione del codice da uno stato ad un altro. Lo scopo di un change log è di documentare le differenze degne di nota tra questi stati.

La differenza tra un change log e un commit log è come la differenza tra un buon commento nel codice e il codice stesso: uno descrive il perché, l'altro il come.

Si possono analizzare automaticamente i change log?

È difficile, perché le persone usano formati e nomi di file profondamente diversi.

Vandamme è una Ruby gem creata dal team Gemnasium ed è in grado di fare il parsing dei change log di molti (ma non tutti) i progetti open source.

Perché si alterna tra i nomi "CHANGELOG" e "change log"?

"CHANGELOG" è il nome del file. È un po' invadente ma è una convenzione storica seguita da molti progetti open source. Altri esempi di file simili includono README, LICENSE, e CONTRIBUTING.

I nomi in maiuscolo (che su vecchi sistemi operativi erano ordinati per primi) vengono usati per attirare l'attenzione su di essi. Poiché sono metadati importanti relativi al progetto, possono essere utili per chiunque voglia usarlo o contribuire ad esso, un po' come i badge dei progetti open source.

Quando mi riferisco a un "change log", sto parlando della funzione di questo file: registrare le modifiche.

Cosa sono le release "yanked"?

Le release "yanked" sono versioni che sono state rimosse a causa di bug seri o problemi di sicurezza. Spesso queste versioni non appaiono nei change log. Invece dovrebbero esserci, nel seguente modo:

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

L'etichetta [YANKED] è in maiuscolo per un motivo. È importante che la gente la noti. Poiché è racchiusa tra parentesi quadre è anche più semplice da riconoscere nel parsing automatizzato.

Si dovrebbe mai modificare un change log?

Certo. Ci sono sempre buoni motivi per migliorare un change log. Io apro regolarmente delle pull request per aggiungere release mancanti ai progetti open source che non mantengono correttamente i change log.

È anche possibile che si scopra di aver dimenticato di annotare una modifica non retro-compatibile nelle note per una versione. Ovviamente è importante aggiornare il change log in questo caso.

Come posso contribuire?

Questo documento non è la verità assoluta; è solo la mia attenta opinione, arricchita dalle informazioni ed esempi che ho raccolto. Anche se fornisco un CHANGELOG reale sul repository GitHub, ho volutamente evitato di creare una release o una chiara lista di regole da seguire (come fa, ad esempio, SemVer.org).

Questo è perché voglio che la nostra comunità raggiunga un consenso. Credo che la discussione sia importante almeno quanto il risultato finale.

Quindi per favore partecipate.

L'ultima versione (1.1.0) non è ancora disponibile in Italiano, ma la potete leggere in Inglese per ora e potete contribuire a tradurla.

Mantenere un CHANGELOG

Non lasciate che i vostri amici copino e incollino i git log nei CHANGELOG ™

Cos'è un change log?

Un change log è un file che contiene una lista curata e ordinata cronologicamente delle modifiche degne di nota per ogni versione di un progetto.

# 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.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?".

A cosa serve un change log?

Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche importanti sono state fatte tra ogni release (o versione) del progetto.

Perché dovrebbe importarmi?

Perché gli strumenti software sono fatti per le persone. Se non ti importa, perché contribuisci all'open source? Di certo ci deve essere un "kernel" (ha!) di interesse da qualche parte in quel tuo amorevole cervello.

Nel podcast "The Changelog" con Adam Stacoviak e Jerod Santo (titolo appropriato, vero?) ho parlato del perché maintainer e contribuenti dovrebbero esserne interessati, e delle motivazioni dietro a questo progetto. Se avete tempo (1:06), vale la pena ascoltarlo.

Come si può fare un buon change log?

Sono contento che tu l'abbia chiesto.

Un buon change log è guidato dai seguenti principi:

Come posso minimizzare lo sforzo richiesto?

Usa sempre una sezione "Unreleased" all'inizio per tenere traccia di qualsiasi modifica.

Questo serve per due scopi:

Cosa fa piangere gli unicorni?

Bene...vediamo un po'.

C'è di più. Aiutatemi a collezionare queste "lacrime di unicorno" aprendo una "issue" o una pull request.

Esiste un formato standard per i change log?

Purtroppo no. Calma. So che state furiosamente correndo a cercare quel link alla guida di stile per i change log GNU, o alle linee guida per or il file a due paragrafi GNU NEWS. La guida GNU è un buon punto di partenza, ma è tristemente ingenuo. Non c'è nulla di male nell'essere ingenuo, ma quando le persone cercano una guida, questa caratteristica è raramente d'aiuto. Specialmente se ci sono molte situazioni e casi limite da gestire.

Questo progetto contiene ciò che spero diventerà una migliore convenzione per i file CHANGELOG. Non credo che lo status quo sia sufficientemente buono, e penso che noi, come comunità, possiamo arrivare a convenzioni migliori se tentiamo di estrarre le pratiche migliori da progetti software reali. Vi consiglio di guardarvi intorno e ricordare che ogni discussione e suggerimento per migliorare sono sempre benvenuti!

Come si dovrebbe chiamare il file contenente il change log?

Se non l'avete dedotto dall'esempio qui sopra, CHANGELOG.md è la convenzione migliore finora.

Alcuni progetti usano anche HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.

È un disastro. Tutti questi nomi contribuiscono solo a rendere più difficile trovarlo.

Perché la gente non si limita ad usare diff di git log?

Perché i log diff sono pieni di rumore, per loro natura. Non potrebbero creare un change log decente nemmeno in un ipotetico progetto gestito da perfetti umani che non fanno mai errori di digitazione, non dimenticano mai di fare commit dei nuovi file, non dimenticano mai alcuna parte di un refactoring. Lo scopo di un commit è di documentare un passo atomico nel processo di evoluzione del codice da uno stato ad un altro. Lo scopo di un change log è di documentare le differenze degne di nota tra questi stati.

La differenza tra un change log e un commit log è come la differenza tra un buon commento nel codice e il codice stesso: uno descrive il perché, l'altro il come.

Si possono analizzare automaticamente i change log?

È difficile, perché le persone usano formati e nomi di file profondamente diversi.

Vandamme è una Ruby gem creata dal team Gemnasium ed è in grado di fare il parsing dei change log di molti (ma non tutti) i progetti open source.

Perché si alterna tra i nomi "CHANGELOG" e "change log"?

"CHANGELOG" è il nome del file. È un po' invadente ma è una convenzione storica seguita da molti progetti open source. Altri esempi di file simili includono README, LICENSE, e CONTRIBUTING.

I nomi in maiuscolo (che su vecchi sistemi operativi erano ordinati per primi) vengono usati per attirare l'attenzione su di essi. Poiché sono metadati importanti relativi al progetto, possono essere utili per chiunque voglia usarlo o contribuire ad esso, un po' come i badge dei progetti open source.

Quando mi riferisco a un "change log", sto parlando della funzione di questo file: registrare le modifiche.

Cosa sono le release "yanked"?

Le release "yanked" sono versioni che sono state rimosse a causa di bug seri o problemi di sicurezza. Spesso queste versioni non appaiono nei change log. Invece dovrebbero esserci, nel seguente modo:

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

L'etichetta [YANKED] è in maiuscolo per un motivo. È importante che la gente la noti. Poiché è racchiusa tra parentesi quadre è anche più semplice da riconoscere nel parsing automatizzato.

Si dovrebbe mai modificare un change log?

Certo. Ci sono sempre buoni motivi per migliorare un change log. Io apro regolarmente delle pull request per aggiungere release mancanti ai progetti open source che non mantengono correttamente i change log.

È anche possibile che si scopra di aver dimenticato di annotare una modifica non retro-compatibile nelle note per una versione. Ovviamente è importante aggiornare il change log in questo caso.

Come posso contribuire?

Questo documento non è la verità assoluta; è solo la mia attenta opinione, arricchita dalle informazioni ed esempi che ho raccolto. Anche se fornisco un CHANGELOG reale sul repository GitHub, ho volutamente evitato di creare una release o una chiara lista di regole da seguire (come fa, ad esempio, SemVer.org).

Questo è perché voglio che la nostra comunità raggiunga un consenso. Credo che la discussione sia importante almeno quanto il risultato finale.

Quindi per favore partecipate.

L'ultima versione (1.1.0) non è ancora disponibile in Italiano, ma la potete leggere in Inglese per ora e potete contribuire a tradurla.

Tenere un Changelog

Non lasciare che i tuoi amici facciano copia incolla dei git logs nei changelog.

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

## [Unreleased]

## [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

Cos'è un changelog?

Un changelog è un file che contiene una lista curata e ordinata cronologicamente delle modifiche degne di nota per ogni versione di un progetto.

Perché tenere un changelog?

Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche importanti sono state fatte tra ogni release (o versione) del progetto.

Chi ha bisogno di un changelog?

Le persone ne hanno bisogno. Che si tratti di consumatori o di sviluppatori, gli utenti finali sono persone interessate a ciò che avviene in esso. Se il software è cambiato, allora le persone vogliono sapere come e perché.

Come posso fare un buon changelog?

Linee guida

  • I changelog sono per le persone, non per le macchine.
  • Dovrebbe esserci una voce per ogni singola versione.
  • Le modifiche dello stesso tipo dovrebbero essere raggruppate.
  • Versioni e sezioni dovrebbero essere collegabili.
  • L'ultima versione viene per prima.
  • Viene mostrata la data di release di ogni versione.
  • Si dichiara se il progetto segue il Versionamento Semantico.

Tipologie di cambiamenti

  • Added per le nuove funzionalità.
  • Changed per le modifiche a funzionalità esistenti.
  • Deprecated per le funzionalità che saranno rimosse nelle future release.
  • Removed per funzionalità rimosse in questa release.
  • Fixed per tutti i bug fix.
  • Security per invitare gli utilizzatori ad aggiornare in caso di vulnerabilità.

Come posso ridurre gli sforzi necessari a mantenere un changelog?

Tieni una sezione Unreleased in cima al changelog in modo da tenere traccia dei cambiamenti imminenti.

Questo serve per due scopi:

  • Le persone possono vedere quali modifiche si possono aspettare nelle future release.
  • Ad una nuova release, si deve solo spostare i cambiamenti della sezione `"Unreleased"` in una nuova sezione con il corrispettivo numero di versione.

I changelog possono essere cattivi?

Si. Ecco alcuni modi in cui possono essere meno utili.

Commit log diffs

Usare i commit log diffs al posto dei changelog è una brutta idea: contengono solo cose superflue. Cose come i merge commits, i commits con titoli oscuri, le modifiche della documentazione, etc.

Lo scopo di un commit è quello di documentare un passo nell'evoluzione del codice sorgente. Alcuni progetti ripuliscono i commit, altri non lo fanno.

Lo scopo di una voce changelog è quello di documentare le differenze rilevanti, spesso attraverso commit multipli, per comunicarli in modo chiaro agli utenti finali.

Ignorare le deprecazioni

Quando le persone aggiornano da una versione ad un'altra, dovrebbe essere dolorosamente chiaro che qualcosa si romperà. Dovrebbe essere possibile eseguire l'aggiornamento a una versione che elenca le deprecazioni, rimuovere ciò che è deprecato, quindi aggiornare alla versione in cui le deprecazioni diventano rimozioni.

Se non fai nient'altro elenca le deprecazioni, le rimozioni e qualsiasi altro cambiamento nel tuo changelog.

Confusione delle date

I formati di date variano da Paese a Paese e spesso trovare un formato human-friendly che sia intuitivo per tutti è cosa ardua. Il vantaggio delle date formattate come 2017-07-17 è che seguono l'ordine dal maggiore al minore: anno, mese e giorno. Inoltre questo formato non ha sovrapposizioni ambigue con altri formati di date, a differenza di alcuni formati regionali che scambiano la posizione del mese e del giorno. Queste motivazioni e il fatto che questo formato di data è uno standard ISO spiegano perché questo è il formato di date raccomandato per i changelog.

Domande frequenti

Esiste un formato standard per i changelog?

Non esattamente. Esistono le linee guida GNU sullo stile dei changelog, oppure i due lunghi paragrafi nel documento di GNU NEWS denominato "guideline". Entrambe sono inadeguate o insufficienti.

Questo progetto vuole essere una migliore convenzione per i file changelog. Per questo motivo osserviamo le migliori pratiche della comunità open source e le portiamo avanti.

Critiche, discussioni e suggerimenti per migliorare sono ben accetti.

Come si dovrebbe chiamare il file di changelog?

Chiamalo CHANGELOG.md. Alcuni progetti usano anche HISTORY, NEWS o RELEASES.

Risulta facile pensare che il nome del tuo file changelog non sia poi così importante, allora perché non rendere facile la vita ai tuoi utenti, usando sempre lo stesso nome?

Cosa dire delle GitHub Releases?

È una bella iniziativa. Releases può essere usato per rendere semplice i git tags (per esempio il nome del tag v1.0.0) All'interno di note di rilascio ben dettagliate si possono aggiungere le note manualmente oppure è possibile utilizzare i messaggi dei git tag inserendoli dentro le note di rilascio.

GitHub Releases crea un changelog non-portable che può essere solo visualizzato dagli utenti nel contesto di GitHub. È possibile farlo apparire molto simile al formato di Keep a Changelog, tuttavia tende ad essere un po' più complicato.

La versione corrente di GitHub Releases risulta inoltre probabilmente poco rilevante per gli utenti finali, a differenza dei tipici file maiuscoli (README, CONTRIBUTING, etc.). Un altro problema minore è che l'interfaccia non offre attualmente link per la creazione di log tra ciascuna release.

I changelog possono essere analizzati automaticamente?

È difficile, perché le persone usano formati e nomi di file profondamente diversi.

Vandamme è una Ruby gem creata dal team Gemnasium ed è in grado di fare il parsing dei changelog di molti (ma non tutti) i progetti open source.

Cosa sono le release "yanked"?

Le release "yanked" sono versioni che sono state rimosse a causa di bug seri o problemi di sicurezza. Spesso queste versioni non appaiono nei changelog. Invece dovrebbero esserci, nel seguente modo:

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

L'etichetta [YANKED] è in maiuscolo per un motivo. È importante che le persone la notino. Poiché è racchiusa tra parentesi quadre è anche più semplice da riconoscere nel parsing automatico.

Si dovrebbe mai modificare un changelog?

Certo. Ci sono sempre buoni motivi per migliorare un changelog. Io apro regolarmente delle pull request per aggiungere release mancanti ai progetti open source che non mantengono correttamente i changelog.

È anche possibile che si scopra di aver dimenticato di annotare una modifica non retro-compatibile nelle note per una versione. Ovviamente è importante aggiornare il changelog in questo caso.

Come posso contribuire?

Questo documento non è la verità assoluta; è solo la mia attenta opinione, arricchita dalle informazioni ed esempi che ho raccolto.

Questo perché voglio che la nostra comunità raggiunga un consenso. Credo che la discussione sia importante almeno quanto il risultato finale.

Quindi per favore partecipate.

Dialogo

Sono andato a The Changelog podcast per parlare del perché i gestori e i contributori dovrebbero preoccuparsi dei changelog e anche delle motivazioni dietro questo progetto.

L'ultima versione (1.1.0) non è ancora disponibile in Italiano, ma la potete leggere in Inglese per ora e potete contribuire a tradurla.

Tenere un Changelog

Non lasciare che i tuoi amici facciano copia incolla dei git logs nei changelog.

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

## [Unreleased]

## [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

Cos'è un changelog?

Un changelog è un file che contiene una lista curata e ordinata cronologicamente delle modifiche degne di nota per ogni versione di un progetto.

Perché tenere un changelog?

Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche importanti sono state fatte tra ogni release (o versione) del progetto.

Chi ha bisogno di un changelog?

Le persone ne hanno bisogno. Che si tratti di consumatori o di sviluppatori, gli utenti finali sono persone interessate a ciò che avviene in esso. Se il software è cambiato, allora le persone vogliono sapere come e perché.

Come posso fare un buon changelog?

Linee guida

  • I changelog sono per le persone, non per le macchine.
  • Dovrebbe esserci una voce per ogni singola versione.
  • Le modifiche dello stesso tipo dovrebbero essere raggruppate.
  • Versioni e sezioni dovrebbero essere collegabili.
  • L'ultima versione viene per prima.
  • Viene mostrata la data di release di ogni versione.
  • Si dichiara se il progetto segue il Versionamento Semantico.

Tipologie di cambiamenti

  • Added per le nuove funzionalità.
  • Changed per le modifiche a funzionalità esistenti.
  • Deprecated per le funzionalità che saranno rimosse nelle future release.
  • Removed per funzionalità rimosse in questa release.
  • Fixed per tutti i bug fix.
  • Security per invitare gli utilizzatori ad aggiornare in caso di vulnerabilità.

Come posso ridurre gli sforzi necessari a mantenere un changelog?

Tieni una sezione Unreleased in cima al changelog in modo da tenere traccia dei cambiamenti imminenti.

Questo serve per due scopi:

  • Le persone possono vedere quali modifiche si possono aspettare nelle future release.
  • Ad una nuova release, si deve solo spostare i cambiamenti della sezione `"Unreleased"` in una nuova sezione con il corrispettivo numero di versione.

I changelog possono essere cattivi?

Si. Ecco alcuni modi in cui possono essere meno utili.

Commit log diffs

Usare i commit log diffs al posto dei changelog è una brutta idea: contengono solo cose superflue. Cose come i merge commits, i commits con titoli oscuri, le modifiche della documentazione, etc.

Lo scopo di un commit è quello di documentare un passo nell'evoluzione del codice sorgente. Alcuni progetti ripuliscono i commit, altri non lo fanno.

Lo scopo di una voce changelog è quello di documentare le differenze rilevanti, spesso attraverso commit multipli, per comunicarli in modo chiaro agli utenti finali.

Ignorare le deprecazioni

Quando le persone aggiornano da una versione ad un'altra, dovrebbe essere dolorosamente chiaro che qualcosa si romperà. Dovrebbe essere possibile eseguire l'aggiornamento a una versione che elenca le deprecazioni, rimuovere ciò che è deprecato, quindi aggiornare alla versione in cui le deprecazioni diventano rimozioni.

Se non fai nient'altro elenca le deprecazioni, le rimozioni e qualsiasi altro cambiamento nel tuo changelog.

Confusione delle date

I formati di date variano da Paese a Paese e spesso trovare un formato human-friendly che sia intuitivo per tutti è cosa ardua. Il vantaggio delle date formattate come 2017-07-17 è che seguono l'ordine dal maggiore al minore: anno, mese e giorno. Inoltre questo formato non ha sovrapposizioni ambigue con altri formati di date, a differenza di alcuni formati regionali che scambiano la posizione del mese e del giorno. Queste motivazioni e il fatto che questo formato di data è uno standard ISO spiegano perché questo è il formato di date raccomandato per i changelog.

Domande frequenti

Esiste un formato standard per i changelog?

Non esattamente. Esistono le linee guida GNU sullo stile dei changelog, oppure i due lunghi paragrafi nel documento di GNU NEWS denominato "guideline". Entrambe sono inadeguate o insufficienti.

Questo progetto vuole essere una migliore convenzione per i file changelog. Per questo motivo osserviamo le migliori pratiche della comunità open source e le portiamo avanti.

Critiche, discussioni e suggerimenti per migliorare sono ben accetti.

Come si dovrebbe chiamare il file di changelog?

Chiamalo CHANGELOG.md. Alcuni progetti usano anche HISTORY, NEWS o RELEASES.

Risulta facile pensare che il nome del tuo file changelog non sia poi così importante, allora perché non rendere facile la vita ai tuoi utenti, usando sempre lo stesso nome?

Cosa dire delle GitHub Releases?

È una bella iniziativa. Releases può essere usato per rendere semplice i git tags (per esempio il nome del tag v1.0.0) All'interno di note di rilascio ben dettagliate si possono aggiungere le note manualmente oppure è possibile utilizzare i messaggi dei git tag inserendoli dentro le note di rilascio.

GitHub Releases crea un changelog non-portable che può essere solo visualizzato dagli utenti nel contesto di GitHub. È possibile farlo apparire molto simile al formato di Keep a Changelog, tuttavia tende ad essere un po' più complicato.

La versione corrente di GitHub Releases risulta inoltre probabilmente poco rilevante per gli utenti finali, a differenza dei tipici file maiuscoli (README, CONTRIBUTING, etc.). Un altro problema minore è che l'interfaccia non offre attualmente link per la creazione di log tra ciascuna release.

I changelog possono essere analizzati automaticamente?

È difficile, perché le persone usano formati e nomi di file profondamente diversi.

Vandamme è una Ruby gem creata dal team Gemnasium ed è in grado di fare il parsing dei changelog di molti (ma non tutti) i progetti open source.

Cosa sono le release "yanked"?

Le release "yanked" sono versioni che sono state rimosse a causa di bug seri o problemi di sicurezza. Spesso queste versioni non appaiono nei changelog. Invece dovrebbero esserci, nel seguente modo:

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

L'etichetta [YANKED] è in maiuscolo per un motivo. È importante che le persone la notino. Poiché è racchiusa tra parentesi quadre è anche più semplice da riconoscere nel parsing automatico.

Si dovrebbe mai modificare un changelog?

Certo. Ci sono sempre buoni motivi per migliorare un changelog. Io apro regolarmente delle pull request per aggiungere release mancanti ai progetti open source che non mantengono correttamente i changelog.

È anche possibile che si scopra di aver dimenticato di annotare una modifica non retro-compatibile nelle note per una versione. Ovviamente è importante aggiornare il changelog in questo caso.

Come posso contribuire?

Questo documento non è la verità assoluta; è solo la mia attenta opinione, arricchita dalle informazioni ed esempi che ho raccolto.

Questo perché voglio che la nostra comunità raggiunga un consenso. Credo che la discussione sia importante almeno quanto il risultato finale.

Quindi per favore partecipate.

Dialogo

Sono andato a The Changelog podcast per parlare del perché i gestori e i contributori dovrebbero preoccuparsi dei changelog e anche delle motivazioni dietro questo progetto.

There is a newer version available: 日本語 1.1.0

変更履歴を記録する

友達にGitログを変更履歴に移させないでください。

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

## [Unreleased]

## [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

変更履歴とは何ですか？

変更履歴とは、プロジェクトの各バージョンに対する注目に値する変更点の時系列順に並べられたリストを含むファイルです。

なぜ変更履歴を記録するのですか？

プロジェクトの各リリース（またはバージョン）の間で、どのような注目すべき変更が行われたのかをユーザーおよびコントリビューターが正確に把握しやすくするためです。

誰が変更履歴を必要としますか？

人々です。消費者であろうと開発者であろうと、ソフトウェアのエンドユーザーはソフトウェアの内容を気にする人間です。ソフトウェアに変更があるとき、人々は変更の理由や方法を知りたいのです。

良い変更履歴を作るには？

基本理念

  • 変更履歴は機械のためではなく人間のためにあります。
  • バージョンごとに作成する必要があります。
  • 同じ種類の変更をグループ化する必要があります。
  • バージョンとセクションはリンク可能である必要があります。
  • 最新バージョンは先頭にきます。
  • 各バージョンのリリース日を表示されます。
  • Semantic Versioning に従っているかどうか言及してください。

変更の種類

  • Added 新機能について。
  • Changed 既存機能の変更について。
  • Deprecated 間もなく削除される機能について。
  • Removed 今回で削除された機能について。
  • Fixed バグ修正について。
  • Security 脆弱性に関する場合。

変更履歴のメンテナンスに必要な労力を減らすにはどうすればよいですか？

今後の変更を追跡するには Unreleased セクションを上部に配置します。

これには2つの目的があります。

  • 人々は、今後のリリースでどのような変更が予想されるのかを確認することができます。
  • リリース時には、 Unreleased セクションにある変更を 新しいリリースバージョンのセクションに移動することができます。

変更履歴は悪くなる可能性がありますか？

はい。いくつかの方法があります。

コミットログの差分

変更履歴としてコミットログの差分を使用することはよくない考えです。それはノイズに満ちています。 マージコミット、あいまいな表題のコミット、ドキュメントの変更などがあります。

コミットの目的はソースコードの進化における一歩を文書化することです。 コミットをクリーンアップするプロジェクトもあれば、そうでないプロジェクトもあります。

変更履歴エントリの目的は、しばしば複数のコミットにまたがって注目すべき違いを文書化し、 それらをエンドユーザーに明確に伝えることです。

非推奨の無視

人々があるバージョンから別のバージョンにアップグレードするとき、いつ何かが壊れるのは痛いほど明らかです。 廃止予定をリストアップしたバージョンにアップグレードし、廃止予定のものを削除してから、 廃止予定が削除されるバージョンにアップグレードすることが可能です。

あなたが他に何もしないのであれば、変更履歴に非推奨、削除、破壊的変更を列挙してください。

分かりにくい日付

地域の日付形式は世界中で異なり、誰にとっても直感的でヒューマンフレンドリーな日付形式を見つけるのは困難です。 2017-07-17 のように形式化された日付の利点は、年、月、日のように最大から最小の単位の順序に従うということです。 この形式は、月と日の位置を切り替える地域の形式とは異なり、他の日付形式とあいまいに重なり合うこともありません。 これらの理由、およびこの日付形式が ISO standard であるという事実が、それが変更履歴エントリに推奨される日付形式である理由です。

よくある質問と回答

変更履歴の標準的な書式がありますか？

実はありません。 GNU changelog style guide 、 もしくは two-paragraph-long GNU NEWS file "guideline" があります。 どちらも不十分であり不適切です。

このプロジェクトは より良い変更履歴の規約 になることを目指しています。 それはオープンソースコミュニティの良い習慣を観察し、それらを集めることから来ます。

健全な批判、議論、そして改善のための提案を 歓迎しています。

変更履歴ファイルにはどのような名前をつけるべきですか？

CHANGELOG.md と呼びます。いくつかのプロジェクトでは HISTORY や NEWS 、 RELEASES が使われています。

あなたの変更履歴ファイルの名前はそれほど重要でないと考えることは容易ですが、 なぜエンドユーザーが一貫して注目の変更を見つけることを難しくするのですか？

GitHubリリースはどうですか？

素晴らしい主導権です。 Releases は手動でリリースノートを追加することによって、 単純なGitタグ(例えば v1.0.0 という名前のタグ)をリッチなリリースノートに変換するために使用することができます。

Githubリリースは、Githubのコンテキスト内でのみユーザーに表示できる移植性のない変更履歴を作成します。 それらをKeep a Changelogの書式のように見せることは可能ですが、もう少し複雑になる傾向があります。

Githubリリースの現在のバージョンも、典型的な大文字のファイル(README や CONTRIBUTINGなど) とは異なり、おそらくエンドユーザーにはあまり発見できません。 もう一つの目立たない問題は、インターフェースが現在各リリース間のコミット履歴へのリンクを提供していないということです。

変更履歴を自動的に解析できますか？

人々は大きく異なるフォーマットやファイル名に従うので、難しいです。

Vandamme はGemnasiumチームによって作成されたRuby gemであり、 （全てではないが）多くのオープンソースプロジェクトの変更履歴を解析します。

ヤンクリリースについてはどうですか？

ヤンクリリースは、深刻なバグやセキュリティの問題のために 引っ張られなければならなかったバージョンです。 多くの場合、これらのバージョンは変更履歴に表示されません。表示しないべきである。 次のように表示すべきである。

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

[YANKED] は大きな理由です。それに気付くことは人々にとって重要です。 大括弧で囲まれているので、プログラムで解析するのも簡単です。

変更履歴を書き換える必要がありますか？

もちろんです。変更履歴を改善するためには、常にもっともな理由があります。 メンテナンスされていない変更履歴のあるオープンソースプロジェクトに 不足しているリリースを追加するためのプルリクエストが常に開かれています。

バージョンのノートにある破壊的変更への対応を忘れたことを発見するかもしれません。 この場合、変更履歴を更新することは明らかに重要です。

どうやって貢献できますか？

この文書は 真実 ではありません。 私が集めた情報と例と共に、慎重に考えられた私の意見です。

私たちのコミュニティが合意に達することを望んでいるからです。 私は議論が最終結果と同じくらい重要であると思います。

なので 協力 してください。

座談

私は The Changelog podcast で、メンテナーやコントリビューターがなぜ変更履歴を気にすべきなのか、 そしてこのプロジェクトの背後にある動機について話しました。

There is a newer version available: 日本語 1.1.0

変更履歴を記録する

友達にGitログを変更履歴に移させないでください。

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

## [Unreleased]

## [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

変更履歴とは何ですか？

変更履歴とは、プロジェクトの各バージョンに対する注目に値する変更点の時系列順に並べられたリストを含むファイルです。

なぜ変更履歴を記録するのですか？

プロジェクトの各リリース（またはバージョン）の間で、どのような注目すべき変更が行われたのかをユーザーおよびコントリビューターが正確に把握しやすくするためです。

誰が変更履歴を必要としますか？

人々です。消費者であろうと開発者であろうと、ソフトウェアのエンドユーザーはソフトウェアの内容を気にする人間です。ソフトウェアに変更があるとき、人々は変更の理由や方法を知りたいのです。

良い変更履歴を作るには？

基本理念

  • 変更履歴は機械のためではなく人間のためにあります。
  • バージョンごとに作成する必要があります。
  • 同じ種類の変更をグループ化する必要があります。
  • バージョンとセクションはリンク可能である必要があります。
  • 最新バージョンは先頭にきます。
  • 各バージョンのリリース日を表示されます。
  • Semantic Versioning に従っているかどうか言及してください。

変更の種類

  • Added 新機能について。
  • Changed 既存機能の変更について。
  • Deprecated 間もなく削除される機能について。
  • Removed 今回で削除された機能について。
  • Fixed バグ修正について。
  • Security 脆弱性に関する場合。

変更履歴のメンテナンスに必要な労力を減らすにはどうすればよいですか？

今後の変更を追跡するには Unreleased セクションを上部に配置します。

これには2つの目的があります。

  • 人々は、今後のリリースでどのような変更が予想されるのかを確認することができます。
  • リリース時には、 Unreleased セクションにある変更を 新しいリリースバージョンのセクションに移動することができます。

変更履歴は悪くなる可能性がありますか？

はい。いくつかの方法があります。

コミットログの差分

変更履歴としてコミットログの差分を使用することはよくない考えです。それはノイズに満ちています。 マージコミット、あいまいな表題のコミット、ドキュメントの変更などがあります。

コミットの目的はソースコードの進化における一歩を文書化することです。 コミットをクリーンアップするプロジェクトもあれば、そうでないプロジェクトもあります。

変更履歴エントリの目的は、しばしば複数のコミットにまたがって注目すべき違いを文書化し、 それらをエンドユーザーに明確に伝えることです。

非推奨の無視

人々があるバージョンから別のバージョンにアップグレードするとき、いつ何かが壊れるのは痛いほど明らかです。 廃止予定をリストアップしたバージョンにアップグレードし、廃止予定のものを削除してから、 廃止予定が削除されるバージョンにアップグレードすることが可能です。

あなたが他に何もしないのであれば、変更履歴に非推奨、削除、破壊的変更を列挙してください。

分かりにくい日付

地域の日付形式は世界中で異なり、誰にとっても直感的でヒューマンフレンドリーな日付形式を見つけるのは困難です。 2017-07-17 のように形式化された日付の利点は、年、月、日のように最大から最小の単位の順序に従うということです。 この形式は、月と日の位置を切り替える地域の形式とは異なり、他の日付形式とあいまいに重なり合うこともありません。 これらの理由、およびこの日付形式が ISO standard であるという事実が、それが変更履歴エントリに推奨される日付形式である理由です。

よくある質問と回答

変更履歴の標準的な書式がありますか？

実はありません。 GNU changelog style guide 、 もしくは two-paragraph-long GNU NEWS file "guideline" があります。 どちらも不十分であり不適切です。

このプロジェクトは より良い変更履歴の規約 になることを目指しています。 それはオープンソースコミュニティの良い習慣を観察し、それらを集めることから来ます。

健全な批判、議論、そして改善のための提案を 歓迎しています。

変更履歴ファイルにはどのような名前をつけるべきですか？

CHANGELOG.md と呼びます。いくつかのプロジェクトでは HISTORY や NEWS 、 RELEASES が使われています。

あなたの変更履歴ファイルの名前はそれほど重要でないと考えることは容易ですが、 なぜエンドユーザーが一貫して注目の変更を見つけることを難しくするのですか？

GitHubリリースはどうですか？

素晴らしい主導権です。 Releases は手動でリリースノートを追加することによって、 単純なGitタグ(例えば v1.0.0 という名前のタグ)をリッチなリリースノートに変換するために使用することができます。

Githubリリースは、Githubのコンテキスト内でのみユーザーに表示できる移植性のない変更履歴を作成します。 それらをKeep a Changelogの書式のように見せることは可能ですが、もう少し複雑になる傾向があります。

Githubリリースの現在のバージョンも、典型的な大文字のファイル(README や CONTRIBUTINGなど) とは異なり、おそらくエンドユーザーにはあまり発見できません。 もう一つの目立たない問題は、インターフェースが現在各リリース間のコミット履歴へのリンクを提供していないということです。

変更履歴を自動的に解析できますか？

人々は大きく異なるフォーマットやファイル名に従うので、難しいです。

Vandamme はGemnasiumチームによって作成されたRuby gemであり、 （全てではないが）多くのオープンソースプロジェクトの変更履歴を解析します。

ヤンクリリースについてはどうですか？

ヤンクリリースは、深刻なバグやセキュリティの問題のために 引っ張られなければならなかったバージョンです。 多くの場合、これらのバージョンは変更履歴に表示されません。表示しないべきである。 次のように表示すべきである。

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

[YANKED] は大きな理由です。それに気付くことは人々にとって重要です。 大括弧で囲まれているので、プログラムで解析するのも簡単です。

変更履歴を書き換える必要がありますか？

もちろんです。変更履歴を改善するためには、常にもっともな理由があります。 メンテナンスされていない変更履歴のあるオープンソースプロジェクトに 不足しているリリースを追加するためのプルリクエストが常に開かれています。

バージョンのノートにある破壊的変更への対応を忘れたことを発見するかもしれません。 この場合、変更履歴を更新することは明らかに重要です。

どうやって貢献できますか？

この文書は 真実 ではありません。 私が集めた情報と例と共に、慎重に考えられた私の意見です。

私たちのコミュニティが合意に達することを望んでいるからです。 私は議論が最終結果と同じくらい重要であると思います。

なので 協力 してください。

座談

私は The Changelog podcast で、メンテナーやコントリビューターがなぜ変更履歴を気にすべきなのか、 そしてこのプロジェクトの背後にある動機について話しました。

変更履歴を記録する

友達がGit記録を変更履歴に丸写しするのを止めさせよう。

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

## [Unreleased]

## [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

変更履歴とは何ですか？

変更履歴とは、事業の各版に対する注目に値する変更点を 時系列順に並べた一覧を含むファイルです。

なぜ変更履歴を記録するのですか？

事業の各リリース（または各版）の間で、 どのような注目すべき変更が行われたのかを利用者および貢献者が正確に把握しやすくするためです。

誰が変更履歴を必要としますか？

全員が必要とします。 消費者であろうと開発者であろうと、ソフトウェアの末端利用者はソフトウェアの内容を気にします。 ソフトウェアに変更があるとき、人々は変更の理由や方法を知りたいのです。

良い変更履歴を作るには？

基本理念

  • 変更履歴は機械のためではなく人間のためにあります。
  • 版ごとに作成する必要があります。
  • 同じ種類の変更をまとめる必要があります。
  • 版と節はリンク可能である必要があります。
  • 最新版は先頭にきます。
  • 各版のリリース日を表示されます。
  • Semantic Versioning に従っているかどうか言及してください。

変更の種類

  • Added 新機能について。
  • Changed 既存機能の変更について。
  • Deprecated 間もなく削除される機能について。
  • Removed 今回で削除された機能について。
  • Fixed 不具合修正について。
  • Security 脆弱性に関する場合。

変更履歴の維持管理に必要な労力を減らすにはどうすればよいですか？

今後の変更を追跡するには Unreleased 節を上部に配置します。

これには2つの目的があります。

  • 人々は、今後のリリースでどのような変更が予想されるのかを確認することができます。
  • リリース時には、 Unreleased 節にある変更を 新しいリリース版の節に移動することができます。

変更履歴が害悪になる可能性はありますか？

はい、ありえます。

変更履歴を役立たずにしてしまう幾つかの行為をここに述べます。

コミット記録の差分

変更履歴としてコミット記録の差分を使用することはよくない考えです。それは雑音に満ちています。 コミット、あいまいな表題のコミット、文書の変更などがあります。

コミットの目的はソースコードの進化における一歩を文書化することです。 合併コミットを一掃する事業もあれば、そうでない事業もあります。

変更履歴項目の目的は、しばしば複数のコミットにまたがって注目すべき違いを文書化し、 それらを末端利用者に明確に伝えることです。

非推奨の無視

人々がある版から別の版に増強するとき、いつ何かが壊れるのは痛いほど明らかです。 廃止予定を洗い出した版に増強し、廃止予定のものを削除してから、 廃止予定が削除される版に増強することが可能です。

あなたが他に何もしないのであれば、変更履歴に非推奨、削除、破壊的変更を列挙してください。

分かりにくい日付

地域の日付形式は世界中で異なり、 誰にとっても直感的で親しみやすい日付形式を見つけるのは困難です。 2017-07-17 のように形式化された日付の利点は、 年、月、日のように最大から最小の単位の順序に従うということです。 この形式は、月と日の位置を切り替える地域の形式とは異なり、 他の日付形式とあいまいに重なり合うこともありません。 これらの理由、およびこの日付形式が 国際標準 であるという事実が、 それが変更履歴項目に推奨される日付形式である理由です。

一貫性のない変更

変更履歴に全ての変更点を記載しないことは、変更履歴がないのと同じくらい危険です。 たしかに記載しないでもよい変更は多くあります—— 例えば、空白を1つ削除したことはどんな場合でも記録する必要はないかもしれません—— が、重要な変更は全実例において記載すべきです。 変更を一貫して適用しないせいで、変更履歴こそ真実が記された唯一の情報源である という勘違いが生じる可能性があります。 そして可能性は現実になりえます。 大いなる力には大いなる責任が伴います—— 良い変更履歴を作るというのは更新が一貫した変更履歴を作るということを意味します。

よくある質問と回答

変更履歴の標準的な書式がありますか？

実はありません。 GNU changelog style guide 、もしくは two-paragraph-long GNU NEWS file という 「指針」があります。 しかしどちらも不十分であり不適切です。

この事業は より良い変更履歴の規約 になることを目指しています。 それはオープンソース団体の良い習慣を観察し、それらを集めることから来ます。

健全な批判、議論、そして改善のための提案を 歓迎しています。

変更履歴ファイルにはどのような名前をつけるべきですか？

CHANGELOG.md という名前にしましょう。 いくつかの事業では HISTORY や NEWS 、 RELEASES という名前が使われています。

あなたの変更履歴ファイルの名前はそれほど重要でないと考えることは容易ですが、 しかし末端利用者が注目に値する変更を一貫して見つけることを難しくする理由はありません。

GitHubリリースはどうですか？

極めて先駆的です。 Releases に手動でリリース告知を追加することによって、 単純なGitタグ（例えば v1.0.0 という名前の標識）を素敵なリリース告知に変換するために使用できます。

GitHub Releasesは、GitHubの文脈内でのみ利用者に表示できる移植性のない変更履歴を作成します。 それらをKeep a Changelogの書式のように見せることは可能ですが、もう少し複雑になる傾向があります。

GitHub Releasesの現在の版も、典型的な大文字のファイル （README や CONTRIBUTINGなど） とは異なり、おそらく末端利用者が見付けるのは簡単ではないでしょう。 もう一つ目立たない問題として、現在、各リリース間のコミット履歴への リンクが提供されていないということがあります。

変更履歴を自動的に解析できますか？

人々によって形式やファイル名は大きく異なるため、難しいです。

Vandamme はGemnasiumチームが作成したRuby gemであり、 （全てではありませんが）多くのオープンソース事業の変更履歴を解析できます。

リリース引き戻しについてはどうですか？

リリース引き戻し (yanked releases) とは、深刻な不具合や安全上の問題のために リリースを引き戻さ (yank) なれなければならなかった版です。 これらの変更はしばしば変更履歴に記載さえされませんが，必ず記載すべきです。 次のように表示すればよいでしょう。

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

[YANKED] が仰々しいのには訳があります。 利用者が引き戻しに気付くことが重要だからです。 角括弧で囲まれているので、プログラムで解析するのも簡単です。

変更履歴を書き換える必要がありますか？

もちろんです。変更履歴を改善するためには、常にもっともな理由があります。 維持管理されていない変更履歴のあるオープンソース事業に、 不足している資源を追加するためのプルリクエストが常に開かれています。

版の告知にある破壊的変更への対応を忘れたことを発見するかもしれません。 この場合、変更履歴を更新することは明らかに重要です。

どうやって貢献できますか？

この文書は 真実 ではありません。 私が集めた情報と例と共に、慎重に考えられた私の意見です。

私たち一同が合意に達することを望んでいるからです。 私は議論が最終結果と同じくらい重要であると思います。

なので 協力 してください。

座談

私は The Changelog podcast で、 管理者や貢献者がなぜ変更履歴を気にすべきなのか、 そしてこの事業の背後にある動機について話しました。

変更履歴を記録する

友達がGit記録を変更履歴に丸写しするのを止めさせよう。

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

## [Unreleased]

## [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

変更履歴とは何ですか？

変更履歴とは、事業の各版に対する注目に値する変更点を 時系列順に並べた一覧を含むファイルです。

なぜ変更履歴を記録するのですか？

事業の各リリース（または各版）の間で、 どのような注目すべき変更が行われたのかを利用者および貢献者が正確に把握しやすくするためです。

誰が変更履歴を必要としますか？

全員が必要とします。 消費者であろうと開発者であろうと、ソフトウェアの末端利用者はソフトウェアの内容を気にします。 ソフトウェアに変更があるとき、人々は変更の理由や方法を知りたいのです。

良い変更履歴を作るには？

基本理念

  • 変更履歴は機械のためではなく人間のためにあります。
  • 版ごとに作成する必要があります。
  • 同じ種類の変更をまとめる必要があります。
  • 版と節はリンク可能である必要があります。
  • 最新版は先頭にきます。
  • 各版のリリース日を表示されます。
  • Semantic Versioning に従っているかどうか言及してください。

変更の種類

  • Added 新機能について。
  • Changed 既存機能の変更について。
  • Deprecated 間もなく削除される機能について。
  • Removed 今回で削除された機能について。
  • Fixed 不具合修正について。
  • Security 脆弱性に関する場合。

変更履歴の維持管理に必要な労力を減らすにはどうすればよいですか？

今後の変更を追跡するには Unreleased 節を上部に配置します。

これには2つの目的があります。

  • 人々は、今後のリリースでどのような変更が予想されるのかを確認することができます。
  • リリース時には、 Unreleased 節にある変更を 新しいリリース版の節に移動することができます。

変更履歴が害悪になる可能性はありますか？

はい、ありえます。

変更履歴を役立たずにしてしまう幾つかの行為をここに述べます。

コミット記録の差分

変更履歴としてコミット記録の差分を使用することはよくない考えです。それは雑音に満ちています。 コミット、あいまいな表題のコミット、文書の変更などがあります。

コミットの目的はソースコードの進化における一歩を文書化することです。 合併コミットを一掃する事業もあれば、そうでない事業もあります。

変更履歴項目の目的は、しばしば複数のコミットにまたがって注目すべき違いを文書化し、 それらを末端利用者に明確に伝えることです。

非推奨の無視

人々がある版から別の版に増強するとき、いつ何かが壊れるのは痛いほど明らかです。 廃止予定を洗い出した版に増強し、廃止予定のものを削除してから、 廃止予定が削除される版に増強することが可能です。

あなたが他に何もしないのであれば、変更履歴に非推奨、削除、破壊的変更を列挙してください。

分かりにくい日付

地域の日付形式は世界中で異なり、 誰にとっても直感的で親しみやすい日付形式を見つけるのは困難です。 2017-07-17 のように形式化された日付の利点は、 年、月、日のように最大から最小の単位の順序に従うということです。 この形式は、月と日の位置を切り替える地域の形式とは異なり、 他の日付形式とあいまいに重なり合うこともありません。 これらの理由、およびこの日付形式が 国際標準 であるという事実が、 それが変更履歴項目に推奨される日付形式である理由です。

一貫性のない変更

変更履歴に全ての変更点を記載しないことは、変更履歴がないのと同じくらい危険です。 たしかに記載しないでもよい変更は多くあります—— 例えば、空白を1つ削除したことはどんな場合でも記録する必要はないかもしれません—— が、重要な変更は全実例において記載すべきです。 変更を一貫して適用しないせいで、変更履歴こそ真実が記された唯一の情報源である という勘違いが生じる可能性があります。 そして可能性は現実になりえます。 大いなる力には大いなる責任が伴います—— 良い変更履歴を作るというのは更新が一貫した変更履歴を作るということを意味します。

よくある質問と回答

変更履歴の標準的な書式がありますか？

実はありません。 GNU changelog style guide 、もしくは two-paragraph-long GNU NEWS file という 「指針」があります。 しかしどちらも不十分であり不適切です。

この事業は より良い変更履歴の規約 になることを目指しています。 それはオープンソース団体の良い習慣を観察し、それらを集めることから来ます。

健全な批判、議論、そして改善のための提案を 歓迎しています。

変更履歴ファイルにはどのような名前をつけるべきですか？

CHANGELOG.md という名前にしましょう。 いくつかの事業では HISTORY や NEWS 、 RELEASES という名前が使われています。

あなたの変更履歴ファイルの名前はそれほど重要でないと考えることは容易ですが、 しかし末端利用者が注目に値する変更を一貫して見つけることを難しくする理由はありません。

GitHubリリースはどうですか？

極めて先駆的です。 Releases に手動でリリース告知を追加することによって、 単純なGitタグ（例えば v1.0.0 という名前の標識）を素敵なリリース告知に変換するために使用できます。

GitHub Releasesは、GitHubの文脈内でのみ利用者に表示できる移植性のない変更履歴を作成します。 それらをKeep a Changelogの書式のように見せることは可能ですが、もう少し複雑になる傾向があります。

GitHub Releasesの現在の版も、典型的な大文字のファイル （README や CONTRIBUTINGなど） とは異なり、おそらく末端利用者が見付けるのは簡単ではないでしょう。 もう一つ目立たない問題として、現在、各リリース間のコミット履歴への リンクが提供されていないということがあります。

変更履歴を自動的に解析できますか？

人々によって形式やファイル名は大きく異なるため、難しいです。

Vandamme はGemnasiumチームが作成したRuby gemであり、 （全てではありませんが）多くのオープンソース事業の変更履歴を解析できます。

リリース引き戻しについてはどうですか？

リリース引き戻し (yanked releases) とは、深刻な不具合や安全上の問題のために リリースを引き戻さ (yank) なれなければならなかった版です。 これらの変更はしばしば変更履歴に記載さえされませんが，必ず記載すべきです。 次のように表示すればよいでしょう。

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

[YANKED] が仰々しいのには訳があります。 利用者が引き戻しに気付くことが重要だからです。 角括弧で囲まれているので、プログラムで解析するのも簡単です。

変更履歴を書き換える必要がありますか？

もちろんです。変更履歴を改善するためには、常にもっともな理由があります。 維持管理されていない変更履歴のあるオープンソース事業に、 不足している資源を追加するためのプルリクエストが常に開かれています。

版の告知にある破壊的変更への対応を忘れたことを発見するかもしれません。 この場合、変更履歴を更新することは明らかに重要です。

どうやって貢献できますか？

この文書は 真実 ではありません。 私が集めた情報と例と共に、慎重に考えられた私の意見です。

私たち一同が合意に達することを望んでいるからです。 私は議論が最終結果と同じくらい重要であると思います。

なので 協力 してください。

座談

私は The Changelog podcast で、 管理者や貢献者がなぜ変更履歴を気にすべきなのか、 そしてこの事業の背後にある動機について話しました。

A new version is available: English 1.1.0

შეინარჩუნე ცვლილებების ჟურნალი

არ მისცე უფლება მეგობრებს git ჩანაწერები ჩაწერონ ცვლილებების ჟურნალში

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

## [Unreleased]

## [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

რა არის ცვლილებების ჟურნალი (changelog)?

ცვლილებების ჟურნალი არის ფაილი რომელიც შეიცავს ქრონოლოგიურად დალაგებულ და კურირებულ სიას იმ აღწერებისა რაც პროექტის თითოეულ ვერსიას აქვს

რატომ უნდა მოვუფრთხილდეთ ცვილებების ჟურნალს?

რათა მომხმარებლებმა და კონტრიბუტორებმა ნათლად დაინახონ რა შეიცვალა პროექტის გამოშვებებს (ან ვერსიებს) შორის.

ვის სჭირდება ცვლილებების ჟურნალი?

ხალხს სჭირდება. მნიშვნელობა არ აქვს მომხმარებელი იქნება თუ დეველოპერი, საბოლოო ჯამში ადამიანები არიან ისინი ვინც ზრუნავენ რა არის ამ პროგრამაში. როდესაც პროგრამა იცვლება, ხალხს უნდა იცოდეს რატომ და როგორ.

როგორ გავაკეთო კარგი ცვლილებების ჟურნალი?

მიყევი პრინციპებს

  • ცვლილებების ჟურნალი განკუთვნილია ადამიანებისთვის, არა მანქანებისთვის.
  • თითოეული ვერსიისთვის უნდა არსებობდეს ჩანაწერი.
  • ერთნაირი ტიპის ჩანაწერები უნდა დაჯგფუდეს.
  • ვერსიები და სექციების გადაბმა შესაძლებელი უნდა იყოს.
  • უკანასკნელი ვერსია უნდა ეწეროს პირველი.
  • გამოშვების თარიღი უნდა ეწეროს თითოეულ ვერსიას.
  • ახსენე თუ იყენებ სემანტიკურ ვერსიონირებას.

ცვლილებების ტიპი

  • Added ახალი ფუნქციონალისთვის.
  • Changed არსებულ ფუნქციონალში შეტანილი ცვლილებებისთვის.
  • Deprecated მალე წასაშლელი ფუნქციონალისთვის.
  • Removed უკვე წაშლილი ფუნქციონალისთვის.
  • Fixed შეცდომების გასწორებისთვის.
  • Security მოწყვლადობის აღმოჩენის შემთხვევაში.

როგორ შევამცირო ძალისხმევა ცვლილებების ჟურნალის შესანარჩუნებლად?

Unreleased სექცია დატოვე ყოველთვის მაღლა რათა მარტივად შეიძლებოდეს დანახვა მომავალი ცვლილებების

ამას ორი მიზეზი აქვს:

  • ხალხს შეეძლება დაინახოს რა მოსალოდნელი ცვლილებებია მომავალ გამოშვებებში
  • გაშვების დროს შეგიძლია უბრალოდ Unreleased სექცია შეცვალო ახალი ვერსიის სექციად.

შესაძლებელია ცვლილებების ჟურნალი იყოს ცუდი?

დიახ. აქ არის რამოდენიმე მაგალითი რომელიც ნათლად გვაჩვენებს ამას.

commit-ების ჩანაწერების სხვაობა.

commit-ების ჩანაწერების სხვაობის გამოყენება ცვლილებების ჟურნალის სახით ცუდი იდეაა: სავსეა უსარგებლო ინფორმაციით, მათ შორის: არასწორი სახელებით და დოკუმენტაციის ცვლილებებით.

commit-ის დანიშნულება არის კოდის ევოლუციის აღწერა. ზოგიერთი პროექტი შლის მათ, ზოგიერთი არა.

ცვლილებების ჟურნალში ჩანაწერის მიზანი არის მნიშვნელოვანი ცვლილებები აღწეროს, ხშირად რამოდენიმე კომიტის ერთად, რათა მარტივად იყოს საბოლოო მომხმარებლებისთვის გასაგები.

მოძველებული ფუნქციონალის იგნორირება

როდესაც ხალხი ერთი ვერსიიდან განახლებას აკეთებს შემდგომზე, აშკარა უნდა იყოს რა შეიძლება გაფუჭდეს. ჯერ განაახლე ისეთ ვერსიაზე რომელსაც აქვს მოძველებული ფუნქციონალის სია, წაშალე რაც მოძველდა და შემდგომ ისეთ ვერსიაზე განაახლე სადაც მოძველებული ფუნქციონალი უკვე წაშლილია.

თუ სხვა არაფერს აკეთებ, ჩამოწერე რაც მოძველდა, რაც წაიშალა და ნებისმიერი სხვა ცვლილება ამ ჟურნალში.

დამაბნეველი თარიღები

რეგიონალური თარიღის ფორმატები განსხვავდება მთელი მსოფლიოს მასშტაბით და ხშირად რთულია იპოვო ადამიანისთვის მარტივად გასაგები თარირის ფორმატი, რომელიც ინტუიციურია ყველასთვის. 2017-07-17 ასეთი ფორმატების უპირატესობა არის ის, რომ მიმდევრობას ემორჩილება უდიდესიდან უმცირეს საზომ ერთეულამდე: წელი, თვე და დღე. ეს ფორმატი ასევე არ ემთხვევა სხვა თარიღის ფორმატებს უცნაური ვარიანტებით, განსხვავებით სხვა ფორმატებისგან რომლებიც ზოგჯერ ცვლიან დღის და თვის რიცხვების პოზიციას. ამ მიზეზთან გამო და იმის გამო, რომ ეს ფორმატი ISO სტანდარტია, იგი რეკომენდირებული თარიღის ფორმატია ცვლილებების ჟურნალის ჩანაწერებისთვის.

ხშირად დასმული კითხვები

არის თუ არა რაიმე სტანდარტული ფორმატი ცვლილებების ჟურნალისთვის?

არა. არსებობს GNU ცვლილებების ჟურნალის სტილი, ან 2 პარაგრაფის სიგრძის GNU NEWS ფაილი "დირექტივა". ორივე შეუფერებელი და არასაკმარისია.

პროექტის მიზანია ჩამოაყალიბოს უკეთესი კონვენცია ცვლილებების ჟურნალისთვის. რომელიც შედეგია წარმატებულ გამოცდილებებზე დაკვირვების ჩვენს კომუნაში და შემდგომ ერთად თავმოყრის.

ჯანსაღი კრიტიკა, დისკუსია და გაუმჯობესების რჩევები მისასალმებელია.

რა უნდა დაერქვას ცვლილებების ჟურნალის ფაილს?

დაარქვი CHANGELOG.md. ზოგი პროექტი იყენებს HISTORY, NEWS ან RELEASES სახელს.

ადვილია იფიქრო რომ ჟურნალის ფაილის სახელს დიდი მნიშვნელობა არ აქვს, მაგრამ რატომ უნდა გაურთულო შენი პროგრამის მომხმარებლებს ცვლილებების ძიება?

რა ხდება GitHub Releases დროს?

შესანიშნავი ინიციატივაა. Releases შესაძლებელია გამოყენებულ იქნას როგორც, უბრალო git იარლიყების(tag) (მაგალითად იარლიყი სახელად v1.0.0) გადასაქცევად სრულყოფილ გამოშვების ჩანაწერებად ჩვენს მიერ ან შესაძლებელია git იარლიყების შეტყობინების ავტომატურად წამოღება და ჩანაწერად ქცევა.

GitHub Releases ქმნის არაპორტაბელურ ცვლილებების ჟურნალს რომელიც მხოლოდ GitHub-ის შიგნით შეიძლება იქნას გამოყენებული. შესაძლებელია მათი წარმოჩენა სხვა ფორმატით თუმცა უფრო მეტი შრომა სჭირდება.

GitHub Releases მიმდინარე ვერსია არ არის მარტივად საპოვნელი მომხმარებლებისთვის, განსხავებით სხვა ტიპიური ფაილებისგან (README, CONTRIBUTING და სხვა.). ასევე ინტერფეისი ამ ეტაპზე არ იძლევა საშუალებას გვქონდეს ბმული commit ჩანაწერებზე თითოეულ გამოშვებას შორის.

შესაძლებელია ცვლილებების ჟურნალის ავტომატური სინტაქსური ანალიზი?

რთულია, რადგან ხალხი იყენებს რადიკალურად განსხვავებულ ფორმატებს და ფაილის სახელებს.

Vandamme არის Ruby gem შექმნილი Gemnasium გუნდის მიერ რომელიც აანალიზებს უმრავლეს (თუმცა ყველას არა) ,ღია პროექტის, ცვლილებების ჟურნალს.

რა ხდება yanked გამოშვებებისას?

Yanked გამოშვებები არის ისეთი ვერსიები რომლებიც უკან უნდა დაბრუნდეს სერიოზული შეცდომის ან უსაფრთხოების პრობლემის გამო. ხშირად ასეთი ვერსიები არც ხვდება ცვლილებების ჟურნალში. არადა უნდა გამოჩნდეს და ასე მაგალითად:

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

[YANKED] იარლიყი სპეციალურად არის. მნიშვნელოვანია რომ შეამჩნიოს ხალხმა. ასევე რადგანაც ის კვადრატულ ფრჩხილებშია მოქცეული, პროგრამულადაც ადვილია სინტაქსური დამუშავება.

უნდა გადაწერო თუ არა როდისმე ცვლილებების ჟურნალი?

რათქმაუნდა. ყოველთვის არის მიზეზი რათა გააუმჯობესო ჟურნალი. რეგულარულად გახსენი pull მოთხოვნები რათა დაამატო გამოტოვებული გამოშვებები სხვადასხვა ღია პროექტების უპატრონოდ მიტოვებულ ცვლილებების ჟურნალს.

ასევე შესაძლებელია აღმოაჩინო რომ დაგავიწყდა რომელიმე ისეთი ცვლილების ჩაწერა კონკრეტული ვერსიისთვის, რაც აფუჭებს პროგრამას. ამ შემთხვევაში აშკარაზე აშკარაა რომ განაახლო შენი ცვლილებების ჟურნალი.

როგორ შემიძლია კონტრიბუცია?

ეს დოკუმენტი არ არის აბსოლუტური ჭეშმარიტება; ეს უფრო არის ჩემს მიერ გათვალისწინებული მოსაზრებები სხვადასხვა მაგალითებთან და მოპოვებულ ინფორმაციასთან ერთად.

მინდა რომ ჩვენმა კომუნამ მიაღწიოს კონსესუსს და მჯერა რომ ეს დისკუსია ისეთივე მნიშვნელოვანია როგორც საბოლოო შედეგი.

ასე რომ გთხოვ ჩაერთე.

საუბრები

ვიყავი The Changelog პოდკასტის სტუმარი და ვისაუბრე რატომ უნდა იზრუნონ ცვლილებების ჟურნალზე კონტრიბუტორებმა და ისინი ვინც კოდს ინარჩუნებენ ყველაზე მეტად. ამავდროულად მოტივაციაზე ამ პროექტის უკან.

A new version is available: English 1.1.0

შეინარჩუნე ცვლილებების ჟურნალი

არ მისცე უფლება მეგობრებს git ჩანაწერები ჩაწერონ ცვლილებების ჟურნალში

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

## [Unreleased]

## [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

რა არის ცვლილებების ჟურნალი (changelog)?

ცვლილებების ჟურნალი არის ფაილი რომელიც შეიცავს ქრონოლოგიურად დალაგებულ და კურირებულ სიას იმ აღწერებისა რაც პროექტის თითოეულ ვერსიას აქვს

რატომ უნდა მოვუფრთხილდეთ ცვილებების ჟურნალს?

რათა მომხმარებლებმა და კონტრიბუტორებმა ნათლად დაინახონ რა შეიცვალა პროექტის გამოშვებებს (ან ვერსიებს) შორის.

ვის სჭირდება ცვლილებების ჟურნალი?

ხალხს სჭირდება. მნიშვნელობა არ აქვს მომხმარებელი იქნება თუ დეველოპერი, საბოლოო ჯამში ადამიანები არიან ისინი ვინც ზრუნავენ რა არის ამ პროგრამაში. როდესაც პროგრამა იცვლება, ხალხს უნდა იცოდეს რატომ და როგორ.

როგორ გავაკეთო კარგი ცვლილებების ჟურნალი?

მიყევი პრინციპებს

  • ცვლილებების ჟურნალი განკუთვნილია ადამიანებისთვის, არა მანქანებისთვის.
  • თითოეული ვერსიისთვის უნდა არსებობდეს ჩანაწერი.
  • ერთნაირი ტიპის ჩანაწერები უნდა დაჯგფუდეს.
  • ვერსიები და სექციების გადაბმა შესაძლებელი უნდა იყოს.
  • უკანასკნელი ვერსია უნდა ეწეროს პირველი.
  • გამოშვების თარიღი უნდა ეწეროს თითოეულ ვერსიას.
  • ახსენე თუ იყენებ სემანტიკურ ვერსიონირებას.

ცვლილებების ტიპი

  • Added ახალი ფუნქციონალისთვის.
  • Changed არსებულ ფუნქციონალში შეტანილი ცვლილებებისთვის.
  • Deprecated მალე წასაშლელი ფუნქციონალისთვის.
  • Removed უკვე წაშლილი ფუნქციონალისთვის.
  • Fixed შეცდომების გასწორებისთვის.
  • Security მოწყვლადობის აღმოჩენის შემთხვევაში.

როგორ შევამცირო ძალისხმევა ცვლილებების ჟურნალის შესანარჩუნებლად?

Unreleased სექცია დატოვე ყოველთვის მაღლა რათა მარტივად შეიძლებოდეს დანახვა მომავალი ცვლილებების

ამას ორი მიზეზი აქვს:

  • ხალხს შეეძლება დაინახოს რა მოსალოდნელი ცვლილებებია მომავალ გამოშვებებში
  • გაშვების დროს შეგიძლია უბრალოდ Unreleased სექცია შეცვალო ახალი ვერსიის სექციად.

შესაძლებელია ცვლილებების ჟურნალი იყოს ცუდი?

დიახ. აქ არის რამოდენიმე მაგალითი რომელიც ნათლად გვაჩვენებს ამას.

commit-ების ჩანაწერების სხვაობა.

commit-ების ჩანაწერების სხვაობის გამოყენება ცვლილებების ჟურნალის სახით ცუდი იდეაა: სავსეა უსარგებლო ინფორმაციით, მათ შორის: არასწორი სახელებით და დოკუმენტაციის ცვლილებებით.

commit-ის დანიშნულება არის კოდის ევოლუციის აღწერა. ზოგიერთი პროექტი შლის მათ, ზოგიერთი არა.

ცვლილებების ჟურნალში ჩანაწერის მიზანი არის მნიშვნელოვანი ცვლილებები აღწეროს, ხშირად რამოდენიმე კომიტის ერთად, რათა მარტივად იყოს საბოლოო მომხმარებლებისთვის გასაგები.

მოძველებული ფუნქციონალის იგნორირება

როდესაც ხალხი ერთი ვერსიიდან განახლებას აკეთებს შემდგომზე, აშკარა უნდა იყოს რა შეიძლება გაფუჭდეს. ჯერ განაახლე ისეთ ვერსიაზე რომელსაც აქვს მოძველებული ფუნქციონალის სია, წაშალე რაც მოძველდა და შემდგომ ისეთ ვერსიაზე განაახლე სადაც მოძველებული ფუნქციონალი უკვე წაშლილია.

თუ სხვა არაფერს აკეთებ, ჩამოწერე რაც მოძველდა, რაც წაიშალა და ნებისმიერი სხვა ცვლილება ამ ჟურნალში.

დამაბნეველი თარიღები

რეგიონალური თარიღის ფორმატები განსხვავდება მთელი მსოფლიოს მასშტაბით და ხშირად რთულია იპოვო ადამიანისთვის მარტივად გასაგები თარირის ფორმატი, რომელიც ინტუიციურია ყველასთვის. 2017-07-17 ასეთი ფორმატების უპირატესობა არის ის, რომ მიმდევრობას ემორჩილება უდიდესიდან უმცირეს საზომ ერთეულამდე: წელი, თვე და დღე. ეს ფორმატი ასევე არ ემთხვევა სხვა თარიღის ფორმატებს უცნაური ვარიანტებით, განსხვავებით სხვა ფორმატებისგან რომლებიც ზოგჯერ ცვლიან დღის და თვის რიცხვების პოზიციას. ამ მიზეზთან გამო და იმის გამო, რომ ეს ფორმატი ISO სტანდარტია, იგი რეკომენდირებული თარიღის ფორმატია ცვლილებების ჟურნალის ჩანაწერებისთვის.

ხშირად დასმული კითხვები

არის თუ არა რაიმე სტანდარტული ფორმატი ცვლილებების ჟურნალისთვის?

არა. არსებობს GNU ცვლილებების ჟურნალის სტილი, ან 2 პარაგრაფის სიგრძის GNU NEWS ფაილი "დირექტივა". ორივე შეუფერებელი და არასაკმარისია.

პროექტის მიზანია ჩამოაყალიბოს უკეთესი კონვენცია ცვლილებების ჟურნალისთვის. რომელიც შედეგია წარმატებულ გამოცდილებებზე დაკვირვების ჩვენს კომუნაში და შემდგომ ერთად თავმოყრის.

ჯანსაღი კრიტიკა, დისკუსია და გაუმჯობესების რჩევები მისასალმებელია.

რა უნდა დაერქვას ცვლილებების ჟურნალის ფაილს?

დაარქვი CHANGELOG.md. ზოგი პროექტი იყენებს HISTORY, NEWS ან RELEASES სახელს.

ადვილია იფიქრო რომ ჟურნალის ფაილის სახელს დიდი მნიშვნელობა არ აქვს, მაგრამ რატომ უნდა გაურთულო შენი პროგრამის მომხმარებლებს ცვლილებების ძიება?

რა ხდება GitHub Releases დროს?

შესანიშნავი ინიციატივაა. Releases შესაძლებელია გამოყენებულ იქნას როგორც, უბრალო git იარლიყების(tag) (მაგალითად იარლიყი სახელად v1.0.0) გადასაქცევად სრულყოფილ გამოშვების ჩანაწერებად ჩვენს მიერ ან შესაძლებელია git იარლიყების შეტყობინების ავტომატურად წამოღება და ჩანაწერად ქცევა.

GitHub Releases ქმნის არაპორტაბელურ ცვლილებების ჟურნალს რომელიც მხოლოდ GitHub-ის შიგნით შეიძლება იქნას გამოყენებული. შესაძლებელია მათი წარმოჩენა სხვა ფორმატით თუმცა უფრო მეტი შრომა სჭირდება.

GitHub Releases მიმდინარე ვერსია არ არის მარტივად საპოვნელი მომხმარებლებისთვის, განსხავებით სხვა ტიპიური ფაილებისგან (README, CONTRIBUTING და სხვა.). ასევე ინტერფეისი ამ ეტაპზე არ იძლევა საშუალებას გვქონდეს ბმული commit ჩანაწერებზე თითოეულ გამოშვებას შორის.

შესაძლებელია ცვლილებების ჟურნალის ავტომატური სინტაქსური ანალიზი?

რთულია, რადგან ხალხი იყენებს რადიკალურად განსხვავებულ ფორმატებს და ფაილის სახელებს.

Vandamme არის Ruby gem შექმნილი Gemnasium გუნდის მიერ რომელიც აანალიზებს უმრავლეს (თუმცა ყველას არა) ,ღია პროექტის, ცვლილებების ჟურნალს.

რა ხდება yanked გამოშვებებისას?

Yanked გამოშვებები არის ისეთი ვერსიები რომლებიც უკან უნდა დაბრუნდეს სერიოზული შეცდომის ან უსაფრთხოების პრობლემის გამო. ხშირად ასეთი ვერსიები არც ხვდება ცვლილებების ჟურნალში. არადა უნდა გამოჩნდეს და ასე მაგალითად:

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

[YANKED] იარლიყი სპეციალურად არის. მნიშვნელოვანია რომ შეამჩნიოს ხალხმა. ასევე რადგანაც ის კვადრატულ ფრჩხილებშია მოქცეული, პროგრამულადაც ადვილია სინტაქსური დამუშავება.

უნდა გადაწერო თუ არა როდისმე ცვლილებების ჟურნალი?

რათქმაუნდა. ყოველთვის არის მიზეზი რათა გააუმჯობესო ჟურნალი. რეგულარულად გახსენი pull მოთხოვნები რათა დაამატო გამოტოვებული გამოშვებები სხვადასხვა ღია პროექტების უპატრონოდ მიტოვებულ ცვლილებების ჟურნალს.

ასევე შესაძლებელია აღმოაჩინო რომ დაგავიწყდა რომელიმე ისეთი ცვლილების ჩაწერა კონკრეტული ვერსიისთვის, რაც აფუჭებს პროგრამას. ამ შემთხვევაში აშკარაზე აშკარაა რომ განაახლო შენი ცვლილებების ჟურნალი.

როგორ შემიძლია კონტრიბუცია?

ეს დოკუმენტი არ არის აბსოლუტური ჭეშმარიტება; ეს უფრო არის ჩემს მიერ გათვალისწინებული მოსაზრებები სხვადასხვა მაგალითებთან და მოპოვებულ ინფორმაციასთან ერთად.

მინდა რომ ჩვენმა კომუნამ მიაღწიოს კონსესუსს და მჯერა რომ ეს დისკუსია ისეთივე მნიშვნელოვანია როგორც საბოლოო შედეგი.

ასე რომ გთხოვ ჩაერთე.

საუბრები

ვიყავი The Changelog პოდკასტის სტუმარი და ვისაუბრე რატომ უნდა იზრუნონ ცვლილებების ჟურნალზე კონტრიბუტორებმა და ისინი ვინც კოდს ინარჩუნებენ ყველაზე მეტად. ამავდროულად მოტივაციაზე ამ პროექტის უკან.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Changelog 관리

동료가 git 로그를 changelogs에 덤프하게 내버려 두지 마세요.

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

## [Unreleased]

## [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

Changelog는 무엇인가요?

Changelog는 프로젝트의 각 버전에 대해 선별된 눈에 띄는 변경사항을 시간 순서대로 정리해둔 파일입니다.

왜 changelog를 유지해야 하나요?

사용자와 기여자가 프로젝트의 각 릴리즈(또는 버전)간에 정확히 어떤 주목할만한 변경사항이 있는지 보기 쉽도록 합니다.

누가 changelog를 필요로 하나요?

사람들이 필요로 합니다. 개발자이든 사용자이든, 소프트웨어의 최종 사용자는 소프트웨어에 무엇이 있는지 관심이 있는 사람입니다. 소프트웨어가 변할 때, 사람들은 왜 그리고 어떻게 바뀌었는지 알고 싶어합니다.

어떻게 좋은 changelog를 만들수 있나요?

가이드 원칙

  • Changelogs는 사람을 위한 것입니다. 기계를 위한 것이 아닙니다.
  • 모든 단일 버전에 대한 항목이 있어야 합니다.
  • 같은 유형의 변경사항은 모아야 합니다.
  • 버전과 섹션은 연결할 수 있어야 합니다.
  • 최신 버전이 처음에 나옵니다.
  • 각 버전의 릴리즈 날짜를 표시해야 합니다.
  • 시멘틱 버저닝를 따르는지 언급해 주세요.

변경 유형

  • Added 새로운 기능
  • Changed 기존 기능의 변경사항
  • Deprecated 곧 지워질 기능
  • Removed 지금 지워진 기능
  • Fixed 버그 픽스
  • Security 취약점이 있는 경우

changelog를 관리하는 노력을 어떻게 줄일 수 있나요?

Unreleased 섹션을 가장 위에 두어 다가올 변경사항을 추적할 수 있도록 하세요.

이것은 두 가지 용도로 사용됩니다:

  • 사람들이 다음 릴리즈에서 기대하는 변경사항을 확인할 수 있습니다.
  • 릴리즈 시점에 Unreleased 섹션의 변경사항을 새 릴리즈 섹션으로 이동할 수 있습니다.

changelogs가 안좋게 될 수 있습니까?

네. 여기에 changelog가 쓸모없게 되는 몇가지 경우들이 있습니다.

커밋 로그 차이(Commit log diffs)

커밋 로그 차이를 changelog로 사용하는 것은 안좋은 생각입니다: 머지 커밋, 모호한 타이틀을 가진 커밋, 문서 변경 등 노이즈로 가득차 있습니다.

커밋의 목적은 소스 코드 진화의 단계를 기록하기 위함입니다. 어떤 프로젝트는 커밋을 정리하지만, 어떤 프로젝트는 하지 않습니다.

changelog 기입의 목적은 종종 다수의 커밋 중에서 주목할만한 차이를 최종 사용자에게 명확하게 전달하기 위해 문서화하는 것입니다.

없어질 기능들(Deprecations) 무시하기

사람들이 다른 버전으로 업그레이드 할 때, 언제 어떤 것이 손상될수있는지(breakable) 고통스럽게 분명해야 합니다. 앞으로 사라질 기능들(deprecations)이 나열된 버전으로 업그레이드하고, 더 이상 사용하지 않는 것(deprecated)을 제거한 뒤, 그 사라질 기능들이 정말 없어진 버전으로 업데이트 하는 것이 가능해야 합니다.

아무 작업도 수행하지 않는다면, 없어질 기능들, 제거된 것, 모든 급격한 변화를 changelog에 남기십시오.

날짜를 혼동하는 것

지역 날짜 포맷은 전세계에 걸쳐 다르고 종종 모두에게 직관적인 인간 친화적 날짜 포맷을 찾기 힘듭니다. 2017-07-17 같은 날짜 포맷(연, 월, 일)의 장점은 큰 단위부터 작은 단위의 순서를 따른다는 것입니다. 월과 일의 위치가 뒤바뀐 어떤 포맷과 다르게, 이 포맷은 다른 날짜 포맷과 모호하게 겹치는 부분이 없습니다. 이런 이유와 이 포맷이 ISO standard라는 사실이 changelog 기입을 위해 이 날짜 포맷을 추천하는 이유입니다.

자주 하는 질문

changelog의 표준 포맷이 있나요?

없습니다. GNU changelog 스타일 가이드나 두 문단정도의 GNU NEWS '가이드라인'이 있습니다. 하지만 둘다 부적절하거나 충분하지 않습니다.

이 프로젝트의 목표는 더 나은 changelog 규칙 입니다. 이것은 오픈소스 커뮤니티에서 좋은 용례를 관찰하고 모으는데서 나옵니다.

건강한 비판, 토론 및 개선 제안은 환영합니다.

changelog 파일의 이름을 무엇으로 지어야 하나요?

CHANGELOG.md라고 만드세요. 어떤 프로젝트는 HISTORY, NEWS 또는 RELEASES를 사용합니다.

changelog 파일의 이름이 무슨 상관이냐고 생각하기 쉽겠지만, 왜 굳이 여러분의 사용자가 변경사항을 일관적으로 찾기 힘들도록 만드나요?

깃허브 릴리즈는 어떻게 하나요?

이것은 훌륭한 이니셔티브입니다. 릴리즈는 직접 릴리즈 노트를 추가하거나 어노테이션된 깃 태그 메시지를 가져와서 노트로 바꿔 간단한 깃 태그(예를 들어 v1.0.0 태그 )를 풍부한 릴리즈 노트로 전환시키는데 사용될 수 있습니다.

깃허브 릴리즈는 이동 불가능한 깃허브 컨텍스트 내에서만 표시되는 changelog를 생성합니다. Keep a Changelog 포맷처럼 보이게 만드는 게 가능하지만, 좀 더 복잡해지는 경향이 있습니다.

전형적인 대문자 파일들과 달리(README, CONTRIBUTING, 등), 깃허브 릴리즈의 현재 버전은 최종 사용자가 거의 찾아볼 수 없습니다. 다른 사소한 이슈는 인터페이스가 현재 각 릴리즈 사이에 로그를 커밋할 수 있는 링크를 제공하지 않는 것입니다.

Changelog를 자동으로 파싱할 수 있나요?

사람들이 대단히 다양한 포맷과 파일 이름을 따르기 때문에 어렵습니다.

Vandamme은 Gemnasium 팀에 의해 생성된 루비잼이고 많은(전부는 아니고) 오픈소스 프로젝트의 changelog를 파싱합니다.

삭제된 릴리즈(Yanked release)는 어떻게 하나요?

삭제된(Yanked) 릴리즈는 심각한 버그나 보안 이슈 때문에 소스에서 들어내버린 버전을 말합니다. 대게 이런 버전은 changelog에 아예 나오지도 않지만, 나와야 합니다. 이것이 삭제된 릴리즈를 표시하는 방법입니다:

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

[YANKED] 태그가 요란한 이유가 있습니다. 사람들이 알아차리는 것이 중요합니다. 대괄호 안에 있기 때문에 프로그래밍적으로 파싱하기에도 용이합니다.

changelog를 다시 써야하나요?

물론입니다. changelog를 개선할 좋은 이유는 항상 있습니다. 저는 정기적으로 changelog가 관리되지 않는 오픈소스에 빠진 릴리즈를 추가하기 위해 pull request를 오픈합니다.

어떤 버전의 급격한 변화에 대해 언급하는 것을 잊은 것을 발견할 수도 있습니다. 이 경우엔 changelog를 업데이트하는 것이 당연히 중요합니다.

어떻게 기여할 수 있나요?

이 문서가 진리는 아닙니다. 이것은 제가 모은 정보와 예제들과 함께 신중하게 고려한 의견입니다.

왜냐하면 우리 커뮤니티가 공감대를 형성하기를 원하기 때문입니다. 저는 최종결과 못지않게 토론도 중요하다고 생각합니다.

그러니 참여를 부탁합니다.

대화

왜 관리자와 기여자가 changelog를 신경써야하는지, 또한 이 프로젝트를 하게된 동기에 대해 이야기하기 위해 The Changelog 팟캐스트에 다녀왔습니다.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Changelog 관리

동료가 git 로그를 changelogs에 덤프하게 내버려 두지 마세요.

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

## [Unreleased]

## [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

Changelog는 무엇인가요?

Changelog는 프로젝트의 각 버전에 대해 선별된 눈에 띄는 변경사항을 시간 순서대로 정리해둔 파일입니다.

왜 changelog를 유지해야 하나요?

사용자와 기여자가 프로젝트의 각 릴리즈(또는 버전)간에 정확히 어떤 주목할만한 변경사항이 있는지 보기 쉽도록 합니다.

누가 changelog를 필요로 하나요?

사람들이 필요로 합니다. 개발자이든 사용자이든, 소프트웨어의 최종 사용자는 소프트웨어에 무엇이 있는지 관심이 있는 사람입니다. 소프트웨어가 변할 때, 사람들은 왜 그리고 어떻게 바뀌었는지 알고 싶어합니다.

어떻게 좋은 changelog를 만들수 있나요?

가이드 원칙

  • Changelogs는 사람을 위한 것입니다. 기계를 위한 것이 아닙니다.
  • 모든 단일 버전에 대한 항목이 있어야 합니다.
  • 같은 유형의 변경사항은 모아야 합니다.
  • 버전과 섹션은 연결할 수 있어야 합니다.
  • 최신 버전이 처음에 나옵니다.
  • 각 버전의 릴리즈 날짜를 표시해야 합니다.
  • 시멘틱 버저닝를 따르는지 언급해 주세요.

변경 유형

  • Added 새로운 기능
  • Changed 기존 기능의 변경사항
  • Deprecated 곧 지워질 기능
  • Removed 지금 지워진 기능
  • Fixed 버그 픽스
  • Security 취약점이 있는 경우

changelog를 관리하는 노력을 어떻게 줄일 수 있나요?

Unreleased 섹션을 가장 위에 두어 다가올 변경사항을 추적할 수 있도록 하세요.

이것은 두 가지 용도로 사용됩니다:

  • 사람들이 다음 릴리즈에서 기대하는 변경사항을 확인할 수 있습니다.
  • 릴리즈 시점에 Unreleased 섹션의 변경사항을 새 릴리즈 섹션으로 이동할 수 있습니다.

changelogs가 안좋게 될 수 있습니까?

네. 여기에 changelog가 쓸모없게 되는 몇가지 경우들이 있습니다.

커밋 로그 차이(Commit log diffs)

커밋 로그 차이를 changelog로 사용하는 것은 안좋은 생각입니다: 머지 커밋, 모호한 타이틀을 가진 커밋, 문서 변경 등 노이즈로 가득차 있습니다.

커밋의 목적은 소스 코드 진화의 단계를 기록하기 위함입니다. 어떤 프로젝트는 커밋을 정리하지만, 어떤 프로젝트는 하지 않습니다.

changelog 기입의 목적은 종종 다수의 커밋 중에서 주목할만한 차이를 최종 사용자에게 명확하게 전달하기 위해 문서화하는 것입니다.

없어질 기능들(Deprecations) 무시하기

사람들이 다른 버전으로 업그레이드 할 때, 언제 어떤 것이 손상될수있는지(breakable) 고통스럽게 분명해야 합니다. 앞으로 사라질 기능들(deprecations)이 나열된 버전으로 업그레이드하고, 더 이상 사용하지 않는 것(deprecated)을 제거한 뒤, 그 사라질 기능들이 정말 없어진 버전으로 업데이트 하는 것이 가능해야 합니다.

아무 작업도 수행하지 않는다면, 없어질 기능들, 제거된 것, 모든 급격한 변화를 changelog에 남기십시오.

날짜를 혼동하는 것

지역 날짜 포맷은 전세계에 걸쳐 다르고 종종 모두에게 직관적인 인간 친화적 날짜 포맷을 찾기 힘듭니다. 2017-07-17 같은 날짜 포맷(연, 월, 일)의 장점은 큰 단위부터 작은 단위의 순서를 따른다는 것입니다. 월과 일의 위치가 뒤바뀐 어떤 포맷과 다르게, 이 포맷은 다른 날짜 포맷과 모호하게 겹치는 부분이 없습니다. 이런 이유와 이 포맷이 ISO standard라는 사실이 changelog 기입을 위해 이 날짜 포맷을 추천하는 이유입니다.

자주 하는 질문

changelog의 표준 포맷이 있나요?

없습니다. GNU changelog 스타일 가이드나 두 문단정도의 GNU NEWS '가이드라인'이 있습니다. 하지만 둘다 부적절하거나 충분하지 않습니다.

이 프로젝트의 목표는 더 나은 changelog 규칙 입니다. 이것은 오픈소스 커뮤니티에서 좋은 용례를 관찰하고 모으는데서 나옵니다.

건강한 비판, 토론 및 개선 제안은 환영합니다.

changelog 파일의 이름을 무엇으로 지어야 하나요?

CHANGELOG.md라고 만드세요. 어떤 프로젝트는 HISTORY, NEWS 또는 RELEASES를 사용합니다.

changelog 파일의 이름이 무슨 상관이냐고 생각하기 쉽겠지만, 왜 굳이 여러분의 사용자가 변경사항을 일관적으로 찾기 힘들도록 만드나요?

깃허브 릴리즈는 어떻게 하나요?

이것은 훌륭한 이니셔티브입니다. 릴리즈는 직접 릴리즈 노트를 추가하거나 어노테이션된 깃 태그 메시지를 가져와서 노트로 바꿔 간단한 깃 태그(예를 들어 v1.0.0 태그 )를 풍부한 릴리즈 노트로 전환시키는데 사용될 수 있습니다.

깃허브 릴리즈는 이동 불가능한 깃허브 컨텍스트 내에서만 표시되는 changelog를 생성합니다. Keep a Changelog 포맷처럼 보이게 만드는 게 가능하지만, 좀 더 복잡해지는 경향이 있습니다.

전형적인 대문자 파일들과 달리(README, CONTRIBUTING, 등), 깃허브 릴리즈의 현재 버전은 최종 사용자가 거의 찾아볼 수 없습니다. 다른 사소한 이슈는 인터페이스가 현재 각 릴리즈 사이에 로그를 커밋할 수 있는 링크를 제공하지 않는 것입니다.

Changelog를 자동으로 파싱할 수 있나요?

사람들이 대단히 다양한 포맷과 파일 이름을 따르기 때문에 어렵습니다.

Vandamme은 Gemnasium 팀에 의해 생성된 루비잼이고 많은(전부는 아니고) 오픈소스 프로젝트의 changelog를 파싱합니다.

삭제된 릴리즈(Yanked release)는 어떻게 하나요?

삭제된(Yanked) 릴리즈는 심각한 버그나 보안 이슈 때문에 소스에서 들어내버린 버전을 말합니다. 대게 이런 버전은 changelog에 아예 나오지도 않지만, 나와야 합니다. 이것이 삭제된 릴리즈를 표시하는 방법입니다:

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

[YANKED] 태그가 요란한 이유가 있습니다. 사람들이 알아차리는 것이 중요합니다. 대괄호 안에 있기 때문에 프로그래밍적으로 파싱하기에도 용이합니다.

changelog를 다시 써야하나요?

물론입니다. changelog를 개선할 좋은 이유는 항상 있습니다. 저는 정기적으로 changelog가 관리되지 않는 오픈소스에 빠진 릴리즈를 추가하기 위해 pull request를 오픈합니다.

어떤 버전의 급격한 변화에 대해 언급하는 것을 잊은 것을 발견할 수도 있습니다. 이 경우엔 changelog를 업데이트하는 것이 당연히 중요합니다.

어떻게 기여할 수 있나요?

이 문서가 진리는 아닙니다. 이것은 제가 모은 정보와 예제들과 함께 신중하게 고려한 의견입니다.

왜냐하면 우리 커뮤니티가 공감대를 형성하기를 원하기 때문입니다. 저는 최종결과 못지않게 토론도 중요하다고 생각합니다.

그러니 참여를 부탁합니다.

대화

왜 관리자와 기여자가 changelog를 신경써야하는지, 또한 이 프로젝트를 하게된 동기에 대해 이야기하기 위해 The Changelog 팟캐스트에 다녀왔습니다.

Lag en Endringslogg

Ikke la vennene dine dumpe git logger i endringslogger.

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

## [Unreleased]

## [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

Hva er en endringslogg?

En endringslogg er en fil som inneholder en organisert, kronologisk satt opp liste over sentrale endringer for hver versjon av et prosjekt.

Hvorfor lage en endringslogg?

For å gjøre det enklere for brukere og bidragsytere å se nøyaktig hvilke sentrale endringer som har blitt gjort mellom hver utgivelse (eller versjon) av prosjektet.

Hvem trenger en endringslogg?

Folk. Om enn de er konsumenter eller utviklere, sluttbrukerne av programvare er mennesker som bryr seg om hva som er i programvaren. Når programvaren endres, vil folk vite hvorfor og hvordan.

Hvordan lager jeg en god endringslogg?

Veiledende prinsipper

  • Endringslogger er for mennesker, ikke maskiner.
  • Det bør være en oppføring for hver versjon.
  • Samme type endringer bør grupperes.
  • Versjoner og seksjoner bør kunne lenkes til.
  • Den nyeste versjonen bør komme først.
  • Utgivelsesdatoen for hver versjon vises.
  • Nevn hvorvidt du følger Semantisk Versjonering.

Type endringer

  • Lagt til for ny funksjonalitet.
  • Endret for endringer i eksisterende funksjonalitet.
  • Avviklet for funksjonalitet som snart fjernes.
  • Fjernet for fjernet funksjonalitet.
  • Fikset for feilrettinger.
  • Sikkerhet i tilfelle sårbarheter.

Hvorfor kan jeg redusere innsatsen som må til for å vedlikeholde en endringslogg?

Bruk en Ikke utgitt-seksjon øverst for å spore kommende endringer.

Dette tjener to formål:

  • Folk kan se hvilke endringer de kan forvente i kommende utgivelser
  • Når utgivelsen publiseres kan du flytte Ikke utgitt-seksjonen til en seksjon for en ny versjon.

Kan endringslogger være dårlige?

Ja. Her er noen måter de kan være mindre nyttige.

Handlingslogg med endringer

Å bruke endringer i handlingslogg (commit log diffs) som endringslogg er en dårlig idé: De er full av støy. Ting som sammenslåing av endringer, obskure titler, endringer i dokumentasjon, osv.

Formålet med en handlingslogg er å dokumentere et steg i utviklingen av kildekoden. Noen prosjekter rydder handlingslogger, andre ikke.

Formålet med en oppføring i endringslogg er å dokumentere sentrale endringer, gjerne på tvers av flere handlingslogger, samt å kommunisere disse klart til sluttbrukerne.

Ignorere Avviklinger

Når folk oppgraderer fra en versjon til en annen burde det være smertelig tydelig når noe vil gå i stykker. Det burde være mulig å oppgradere til en versjon som oppgir avviklinger, fjerne det som er avviklet, og deretter oppgradere til en versjon hvor avviklinger blir det som er fjernet.

Om ikke annet, oppgi avviklinger, hva som er fjernet, og annet som gjør at noe går i stykker i endringsloggen.

Forvirrende Datoer

Regionale datoformater varierer, og det er ofte vanskelig å finne et menneskevennlig datoformat som føles intuitivt for alle. Fordelen med datoformater som 2017-07-17 er at de følger rekkefølgen med største til minste enhet: År, måned og dato. Dette formatet overlapper heller ikke på tvetydige måter, til forskjell fra noen regionale formater som bytter posisjonen til måneds- og datonumre. Derfor, og fordi dette datoformatet er en ISO-standard, er det anbefalt datoformat for oppføringer i endringslogger.

Tvetydige Endringer

En endringslogg som bare nevner noen av endringene kan være like farlig som å ikke ha en endringslogg. Selv om mange av endringene ikke er relevante - for eksempel, fjerning av et enkelt mellomrom ikke trenger å registreres i alle tilfeller - bør alle sentrale endringer nevnes i endringsloggen. Ved inkonsistent oppførsel av endringer vil brukerne dine feilaktig tro at endringsloggen er den eneste kilden til sannhet. Den bør være det. Ved stor makt kommer stort ansvar - å ha en god endringslogg betyr å ha en konsistent oppdatert endringslogg.

Ofte Spurte Spørsmål

Er det et standard format for endringslogger?

Ikke egentlig. Det finnes GNUs stilguide for endringslogger, eller den to avsnitt lange GNU NEWS filen "retningslinjen". Begge er inadekvate eller utilstrekkelige.

Dette prosjektet søker å være en bedre konvensjon for endringslogger Dette kommer fra observasjon av beste praksis i miljøet for åpen kildekode og innsamling av de.

Sunn kritikk, diskusjon og forslag til forbedringer er velkomne.

Hvordan bør endringsloggfilen navngis?

Kall de CHANGELOG.md. Noen prosjekter bruker HISTORY, NEWS eller RELEASES.

Selv om det er enkelt å tenke at navnet på endringsloggfilen ikke betyr så mye, hvorfor gjøre det vanskeligere for sluttbrukerne å konsekvent finne sentrale endringer?

Hva med utgivelser på GitHub?

Det er et flott initiativ. Utgivelser kan brukes for å gjøre enkle taggede versjoner på git (for eksempel v1.0.0) om til fyldige utgivelsesnotater ved å manuelt legge de til, eller å hente annoterte notater fra taggede versjoner å gjøre de om til utgivelsesnotater.

Utgivelser på GitHub lager en ikke-portabel endringslogg som bare kan vises til brukerne innenfor konteksten GitHub. Det er mulig å gjøre de veldig lik formatet til Lag en Endringslogg, men det er vanligvis mer krevende.

Den nåværende versjonen av utgivelser på GitHub er antageligvis ikke veldig gjenfinnbar for sluttbrukere, i motsetning til de typiske filene med store bokstaver (README, CONTRIBUTING, osv.) Et annet, mindre, problem er at grensesnittet per nå ikke tilbyr lenker til handlingslogger mellom hver utgivelse.

Kan endringslogger automatisk tolkes?

Det er vanskelig, fordi folk følger svært forskjellige formater og filnavn.

Vandamme er en Ruby gem laget av Gemnasium-teamet for å tolke mange (men ikke alle) endringslogger for prosjekter med åpen kildekode.

Hva med tilbaketrukne utgivelser?

Tilbaketrukne utgivelser er versjoner som måtte trekkes tilbake på grunn av en alvorlig feil eller et sikkerhetsproblem. Vanligvis fremgår ikke disse versjonene i endringsloggen. Det bør det. Slik bør de vises frem:

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

Merkelappen [TILBAKETRUKKET] er bevisst uthevet. Det er for at folk skal legge merke til den. Siden den er omgitt av braketter er den også enklere å tolke programmatisk.

Bør du noensinne omskrive en endringslogg?

Selvfølgelig. Det er alltid gode grunner til å forbedre en endringslogg. Jeg lager regelmessig endringsforslag for å legge til manglende utgivelser i prosjekter med åpen kildekode som mangler vedlikeholdte endringslogger.

Det er også mulig at du oppdager at du glemte å addressere en sentral endring i notatene til en versjon. Det er selvfølgelig viktig at du oppdaterer endringsloggen i dette tilfellet.

Hvordan kan jeg bidra?

Dette dokumentet er ikke sannheten; det er min nøye vurderte mening, samt informasjon og eksempler jeg har samlet.

Dette fordi jeg vil at vårt miljø skal nå en enighet. Jeg tror at diskusjonen er like viktig som resultatet.

Så vær så snill, bidra.

Samtaler

Jeg deltok på The Changelog podcast for å snakke om hvorfor vedlikeholdere og bidragsytere burde bry seg om endringslogger, og også om motivasjonene bak dette prosjektet.

Lag en Endringslogg

Ikke la vennene dine dumpe git logger i endringslogger.

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

## [Unreleased]

## [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

Hva er en endringslogg?

En endringslogg er en fil som inneholder en organisert, kronologisk satt opp liste over sentrale endringer for hver versjon av et prosjekt.

Hvorfor lage en endringslogg?

For å gjøre det enklere for brukere og bidragsytere å se nøyaktig hvilke sentrale endringer som har blitt gjort mellom hver utgivelse (eller versjon) av prosjektet.

Hvem trenger en endringslogg?

Folk. Om enn de er konsumenter eller utviklere, sluttbrukerne av programvare er mennesker som bryr seg om hva som er i programvaren. Når programvaren endres, vil folk vite hvorfor og hvordan.

Hvordan lager jeg en god endringslogg?

Veiledende prinsipper

  • Endringslogger er for mennesker, ikke maskiner.
  • Det bør være en oppføring for hver versjon.
  • Samme type endringer bør grupperes.
  • Versjoner og seksjoner bør kunne lenkes til.
  • Den nyeste versjonen bør komme først.
  • Utgivelsesdatoen for hver versjon vises.
  • Nevn hvorvidt du følger Semantisk Versjonering.

Type endringer

  • Lagt til for ny funksjonalitet.
  • Endret for endringer i eksisterende funksjonalitet.
  • Avviklet for funksjonalitet som snart fjernes.
  • Fjernet for fjernet funksjonalitet.
  • Fikset for feilrettinger.
  • Sikkerhet i tilfelle sårbarheter.

Hvorfor kan jeg redusere innsatsen som må til for å vedlikeholde en endringslogg?

Bruk en Ikke utgitt-seksjon øverst for å spore kommende endringer.

Dette tjener to formål:

  • Folk kan se hvilke endringer de kan forvente i kommende utgivelser
  • Når utgivelsen publiseres kan du flytte Ikke utgitt-seksjonen til en seksjon for en ny versjon.

Kan endringslogger være dårlige?

Ja. Her er noen måter de kan være mindre nyttige.

Handlingslogg med endringer

Å bruke endringer i handlingslogg (commit log diffs) som endringslogg er en dårlig idé: De er full av støy. Ting som sammenslåing av endringer, obskure titler, endringer i dokumentasjon, osv.

Formålet med en handlingslogg er å dokumentere et steg i utviklingen av kildekoden. Noen prosjekter rydder handlingslogger, andre ikke.

Formålet med en oppføring i endringslogg er å dokumentere sentrale endringer, gjerne på tvers av flere handlingslogger, samt å kommunisere disse klart til sluttbrukerne.

Ignorere Avviklinger

Når folk oppgraderer fra en versjon til en annen burde det være smertelig tydelig når noe vil gå i stykker. Det burde være mulig å oppgradere til en versjon som oppgir avviklinger, fjerne det som er avviklet, og deretter oppgradere til en versjon hvor avviklinger blir det som er fjernet.

Om ikke annet, oppgi avviklinger, hva som er fjernet, og annet som gjør at noe går i stykker i endringsloggen.

Forvirrende Datoer

Regionale datoformater varierer, og det er ofte vanskelig å finne et menneskevennlig datoformat som føles intuitivt for alle. Fordelen med datoformater som 2017-07-17 er at de følger rekkefølgen med største til minste enhet: År, måned og dato. Dette formatet overlapper heller ikke på tvetydige måter, til forskjell fra noen regionale formater som bytter posisjonen til måneds- og datonumre. Derfor, og fordi dette datoformatet er en ISO-standard, er det anbefalt datoformat for oppføringer i endringslogger.

Tvetydige Endringer

En endringslogg som bare nevner noen av endringene kan være like farlig som å ikke ha en endringslogg. Selv om mange av endringene ikke er relevante - for eksempel, fjerning av et enkelt mellomrom ikke trenger å registreres i alle tilfeller - bør alle sentrale endringer nevnes i endringsloggen. Ved inkonsistent oppførsel av endringer vil brukerne dine feilaktig tro at endringsloggen er den eneste kilden til sannhet. Den bør være det. Ved stor makt kommer stort ansvar - å ha en god endringslogg betyr å ha en konsistent oppdatert endringslogg.

Ofte Spurte Spørsmål

Er det et standard format for endringslogger?

Ikke egentlig. Det finnes GNUs stilguide for endringslogger, eller den to avsnitt lange GNU NEWS filen "retningslinjen". Begge er inadekvate eller utilstrekkelige.

Dette prosjektet søker å være en bedre konvensjon for endringslogger Dette kommer fra observasjon av beste praksis i miljøet for åpen kildekode og innsamling av de.

Sunn kritikk, diskusjon og forslag til forbedringer er velkomne.

Hvordan bør endringsloggfilen navngis?

Kall de CHANGELOG.md. Noen prosjekter bruker HISTORY, NEWS eller RELEASES.

Selv om det er enkelt å tenke at navnet på endringsloggfilen ikke betyr så mye, hvorfor gjøre det vanskeligere for sluttbrukerne å konsekvent finne sentrale endringer?

Hva med utgivelser på GitHub?

Det er et flott initiativ. Utgivelser kan brukes for å gjøre enkle taggede versjoner på git (for eksempel v1.0.0) om til fyldige utgivelsesnotater ved å manuelt legge de til, eller å hente annoterte notater fra taggede versjoner å gjøre de om til utgivelsesnotater.

Utgivelser på GitHub lager en ikke-portabel endringslogg som bare kan vises til brukerne innenfor konteksten GitHub. Det er mulig å gjøre de veldig lik formatet til Lag en Endringslogg, men det er vanligvis mer krevende.

Den nåværende versjonen av utgivelser på GitHub er antageligvis ikke veldig gjenfinnbar for sluttbrukere, i motsetning til de typiske filene med store bokstaver (README, CONTRIBUTING, osv.) Et annet, mindre, problem er at grensesnittet per nå ikke tilbyr lenker til handlingslogger mellom hver utgivelse.

Kan endringslogger automatisk tolkes?

Det er vanskelig, fordi folk følger svært forskjellige formater og filnavn.

Vandamme er en Ruby gem laget av Gemnasium-teamet for å tolke mange (men ikke alle) endringslogger for prosjekter med åpen kildekode.

Hva med tilbaketrukne utgivelser?

Tilbaketrukne utgivelser er versjoner som måtte trekkes tilbake på grunn av en alvorlig feil eller et sikkerhetsproblem. Vanligvis fremgår ikke disse versjonene i endringsloggen. Det bør det. Slik bør de vises frem:

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

Merkelappen [TILBAKETRUKKET] er bevisst uthevet. Det er for at folk skal legge merke til den. Siden den er omgitt av braketter er den også enklere å tolke programmatisk.

Bør du noensinne omskrive en endringslogg?

Selvfølgelig. Det er alltid gode grunner til å forbedre en endringslogg. Jeg lager regelmessig endringsforslag for å legge til manglende utgivelser i prosjekter med åpen kildekode som mangler vedlikeholdte endringslogger.

Det er også mulig at du oppdager at du glemte å addressere en sentral endring i notatene til en versjon. Det er selvfølgelig viktig at du oppdaterer endringsloggen i dette tilfellet.

Hvordan kan jeg bidra?

Dette dokumentet er ikke sannheten; det er min nøye vurderte mening, samt informasjon og eksempler jeg har samlet.

Dette fordi jeg vil at vårt miljø skal nå en enighet. Jeg tror at diskusjonen er like viktig som resultatet.

Så vær så snill, bidra.

Samtaler

Jeg deltok på The Changelog podcast for å snakke om hvorfor vedlikeholdere og bidragsytere burde bry seg om endringslogger, og også om motivasjonene bak dette prosjektet.

There is a newer version available: Nederlands 1.1.0

Houd een Changelog bij

Laat je vrienden geen git logs in changelogs dumpen.

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

## [Unreleased]

## [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

Wat is een changelog?

Een changelog is een bestand met een zorgvuldig samengestelde, chronologische lijst van noemenswaardige aanpassingen voor elke versie van een project.

Waarom een changelog bijhouden?

Om het makkelijker te maken voor gebruikers en programmeurs om precies te zien welke noemenswaardige aanpassingen er gedaan zijn tussen elke release (of versie) van het project.

Wie heeft een changelog nodig?

Mensen hebben het nodig. Of het nu consumenten of ontwikkelaars zijn, eindgebruikers van software zijn mensen die er om geven wat er in de software zit die ze gebruiken. Als de software verandert, wil men weten wat en hoe.

Hoe maak ik een goed changelog?

Richtlijnen

  • Changelogs zijn voor mensen, niet voor machines.
  • Er zou een vermelding moeten zijn voor elke versie.
  • Aanpassingen van het zelfde type moeten gegroepeerd worden.
  • Versies en secties zouden linkbaar moeten zijn.
  • De laatste versie staat bovenaan.
  • De release datum van elke versie word weergegeven.
  • Geef aan of je Semantic Versioning gebruikt.

Types of changes

  • Added voor nieuwe functionaliteit.
  • Changed voor aanpassingen aan bestaande functionaliteit.
  • Deprecated voor functionaliteit die binnenkort komt te vervallen.
  • Removed voor functionaliteit die vanaf nu vervallen is.
  • Fixed voor bug fixes.
  • Security voor aanpassingen met betrekking tot veiligheid.

Hoe kan ik, met zo min mogelijk moeite, een changelog bij houden?

Houd bovenin een Unreleased sectie bij met aanpassingen voor de komende release.

Dit heeft twee doelen:

  • Mensen kunnen zien wat te verwachten in de aankomende release.
  • Als je een release doet kan je eenvoudig de Unreleased sectie aanpassen naar een nieuwe release sectie.

Kan een changelog slecht zijn?

Ja. Hier een paar manieren waarop je een changelog behoorlijk onbruikbaar kan maken.

Commit log diffs

Commit log diffs gebruiken als een changelog is een slecht idee: ze staan vol met ruis. Denk bijvoorbeeld aan merge commits, commits met onduidelijke titels, documentatie aanpassingen etc.

Het doel van een commit bericht is om één enkele stap in de evolutie van de code te beschrijven.

Het doel van een changelog is om noemenswaardige aanpassingen te documenteren, vaak over meerdere commits, en om deze duidelijk naar de eindgebruiker te communiceren.

Deprecations negeren

Wanneer mensen upgraden van de ene naar de andere versie, moet het overduidelijk zijn als er iets niet meer zal werken. Het moet mogelijk zijn om te upgraden naar een versie met deprecations, vervolgens de deprecations weg te halen, en vervolgens de upgrade kunnen doen naar de versie waar de deprecations removals zijn geworden.

Geef altijd op zijn minst de deprecations, removals en changes met grote impact aan in je changelog.

Verwarrende datums

Datum notaties verschillen van land tot land, en het is vaak moeilijk om een notatie te vinden die makkelijk te lezen is en intuïtief is voor iedereen. Het voordeel van de notatie 2017-07-17 is dat het jaar, maand en dag op volgorde van grootte laat zien. Daarom, en het feit dat dit een ISO standaard is, is dit de aanbevolen datum notatie voor changelog releases.

Veel Gestelde Vragen

Is er een standaard changelog template?

Niet echt. Er is de GNU changelog style guide, en het twee paragrafen lange GNU NEWS bestand "richtlijnen". Beiden zijn niet volledig genoeg.

Dit project poogt een betere changelog standaard te creëren. Dit op basis van "good practices" uit de open source wereld.

Opbouwende kritiek, discussie en suggesties voor verbetering zijn welkom.

Wat zou de changelog bestandsnaam moeten zijn?

Noem het CHANGELOG.md. Sommige projecten gebruiken HISTORY, NEWS of RELEASES.

Je kan denken dat de bestandsnaam niet heel belangrijk is, maar waarom zou je het de eindgebruikers moeilijker maken om de changelog te vinden?

Wat denk je van GitHub Releases?

Het is een goed initiatief. Releases kan gebruikt worden om simpele git tags (bijvoorbeeld een tag met de naam v1.0.0) te veranderen in uitgebreide release notes door deze handmatig toe te voegen of door geannoteerde git tag berichten te gebruiken om release notes te genereren.

GitHub Releases maken changelog wat alleen getoond kan worden aan gebruikers binnen de context van GitHub. Het is mogelijk om deze dicht bij het format te krijgen wat wij hier promoten, maar er zal iets meer werk voor nodig zijn.

De huidige versie van GitHub releases is naar mijn mening niet echt goed vindbaar voor gebruikers, in tegenstelling tot de typische bestanden die in een naam in hoofdletters hebben (README, CONTRIBUTING, etc.). Een ander knelpunt is dat de interface geen links toestaat naar commit logs van elke release.

Kunnen changelogs automatisch geparsed worden?

Dat is lastig, mensen gebruiken immers veel verschillende formats en bestandsnamen.

Vandamme is een Ruby gem van het Gemnasium team wat de changelogs van veel (maar niet alle) open source projecten kan parsen.

Wat doen we met teruggetrokken (yanked) releases?

Teruggetrokken releases zijn versies die teruggetrokken zijn als gevolg van een serieuze bug of beveiligings probleem. Vaak zijn ze niet eens te zien in de changelogs. Dat zou wel moeten. Zo zou je een teruggetrokken release moeten tonen:

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

De [YANKED] tag is in hoofdletters voor een reden. Het is belangrijk dat mensen dit zien. Omdat het tussen blokhaken genoteerd is, is het ook makkelijker automatisch te parsen.

Mag je een changelog aanpassen/herschrijven?

Natuurlijk. Er zijn goede redenen om een changelog te verbeteren. Ik open regelmatig een pull request om missende releases toe te voegen aan open source projecten met een slecht onderhouden changelog.

Het kan ook zo zijn dat je ontdekt dat je een belangrijke aanpassing niet vermeld hebt in je changelog. Het is dan natuurlijk zaak om dit alsnog in je changelog te vermelden.

Hoe kan ik bijdragen?

Dit document is niet de waarheid; het is mijn weloverwogen mening, samen met wat informatie en voorbeelden die ik verzameld heb.

Dit heb ik gedaan omdat ik wil dat de programmeer gemeenschap een consensus bereikt. Ik denk dat de discussie net zo belangrijk is als het eindresultaat.

Dus alle hulp is welkom.

Conversaties

Ik was te gast bij The Changelog podcast om te praten over waarom een changelog belangrijk is programmeurs, en over mijn motivatie achter dit project.

There is a newer version available: Nederlands 1.1.0

Houd een Changelog bij

Laat je vrienden geen git logs in changelogs dumpen.

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

## [Unreleased]

## [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

Wat is een changelog?

Een changelog is een bestand met een zorgvuldig samengestelde, chronologische lijst van noemenswaardige aanpassingen voor elke versie van een project.

Waarom een changelog bijhouden?

Om het makkelijker te maken voor gebruikers en programmeurs om precies te zien welke noemenswaardige aanpassingen er gedaan zijn tussen elke release (of versie) van het project.

Wie heeft een changelog nodig?

Mensen hebben het nodig. Of het nu consumenten of ontwikkelaars zijn, eindgebruikers van software zijn mensen die er om geven wat er in de software zit die ze gebruiken. Als de software verandert, wil men weten wat en hoe.

Hoe maak ik een goed changelog?

Richtlijnen

  • Changelogs zijn voor mensen, niet voor machines.
  • Er zou een vermelding moeten zijn voor elke versie.
  • Aanpassingen van het zelfde type moeten gegroepeerd worden.
  • Versies en secties zouden linkbaar moeten zijn.
  • De laatste versie staat bovenaan.
  • De release datum van elke versie word weergegeven.
  • Geef aan of je Semantic Versioning gebruikt.

Types of changes

  • Added voor nieuwe functionaliteit.
  • Changed voor aanpassingen aan bestaande functionaliteit.
  • Deprecated voor functionaliteit die binnenkort komt te vervallen.
  • Removed voor functionaliteit die vanaf nu vervallen is.
  • Fixed voor bug fixes.
  • Security voor aanpassingen met betrekking tot veiligheid.

Hoe kan ik, met zo min mogelijk moeite, een changelog bij houden?

Houd bovenin een Unreleased sectie bij met aanpassingen voor de komende release.

Dit heeft twee doelen:

  • Mensen kunnen zien wat te verwachten in de aankomende release.
  • Als je een release doet kan je eenvoudig de Unreleased sectie aanpassen naar een nieuwe release sectie.

Kan een changelog slecht zijn?

Ja. Hier een paar manieren waarop je een changelog behoorlijk onbruikbaar kan maken.

Commit log diffs

Commit log diffs gebruiken als een changelog is een slecht idee: ze staan vol met ruis. Denk bijvoorbeeld aan merge commits, commits met onduidelijke titels, documentatie aanpassingen etc.

Het doel van een commit bericht is om één enkele stap in de evolutie van de code te beschrijven.

Het doel van een changelog is om noemenswaardige aanpassingen te documenteren, vaak over meerdere commits, en om deze duidelijk naar de eindgebruiker te communiceren.

Deprecations negeren

Wanneer mensen upgraden van de ene naar de andere versie, moet het overduidelijk zijn als er iets niet meer zal werken. Het moet mogelijk zijn om te upgraden naar een versie met deprecations, vervolgens de deprecations weg te halen, en vervolgens de upgrade kunnen doen naar de versie waar de deprecations removals zijn geworden.

Geef altijd op zijn minst de deprecations, removals en changes met grote impact aan in je changelog.

Verwarrende datums

Datum notaties verschillen van land tot land, en het is vaak moeilijk om een notatie te vinden die makkelijk te lezen is en intuïtief is voor iedereen. Het voordeel van de notatie 2017-07-17 is dat het jaar, maand en dag op volgorde van grootte laat zien. Daarom, en het feit dat dit een ISO standaard is, is dit de aanbevolen datum notatie voor changelog releases.

Veel Gestelde Vragen

Is er een standaard changelog template?

Niet echt. Er is de GNU changelog style guide, en het twee paragrafen lange GNU NEWS bestand "richtlijnen". Beiden zijn niet volledig genoeg.

Dit project poogt een betere changelog standaard te creëren. Dit op basis van "good practices" uit de open source wereld.

Opbouwende kritiek, discussie en suggesties voor verbetering zijn welkom.

Wat zou de changelog bestandsnaam moeten zijn?

Noem het CHANGELOG.md. Sommige projecten gebruiken HISTORY, NEWS of RELEASES.

Je kan denken dat de bestandsnaam niet heel belangrijk is, maar waarom zou je het de eindgebruikers moeilijker maken om de changelog te vinden?

Wat denk je van GitHub Releases?

Het is een goed initiatief. Releases kan gebruikt worden om simpele git tags (bijvoorbeeld een tag met de naam v1.0.0) te veranderen in uitgebreide release notes door deze handmatig toe te voegen of door geannoteerde git tag berichten te gebruiken om release notes te genereren.

GitHub Releases maken changelog wat alleen getoond kan worden aan gebruikers binnen de context van GitHub. Het is mogelijk om deze dicht bij het format te krijgen wat wij hier promoten, maar er zal iets meer werk voor nodig zijn.

De huidige versie van GitHub releases is naar mijn mening niet echt goed vindbaar voor gebruikers, in tegenstelling tot de typische bestanden die in een naam in hoofdletters hebben (README, CONTRIBUTING, etc.). Een ander knelpunt is dat de interface geen links toestaat naar commit logs van elke release.

Kunnen changelogs automatisch geparsed worden?

Dat is lastig, mensen gebruiken immers veel verschillende formats en bestandsnamen.

Vandamme is een Ruby gem van het Gemnasium team wat de changelogs van veel (maar niet alle) open source projecten kan parsen.

Wat doen we met teruggetrokken (yanked) releases?

Teruggetrokken releases zijn versies die teruggetrokken zijn als gevolg van een serieuze bug of beveiligings probleem. Vaak zijn ze niet eens te zien in de changelogs. Dat zou wel moeten. Zo zou je een teruggetrokken release moeten tonen:

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

De [YANKED] tag is in hoofdletters voor een reden. Het is belangrijk dat mensen dit zien. Omdat het tussen blokhaken genoteerd is, is het ook makkelijker automatisch te parsen.

Mag je een changelog aanpassen/herschrijven?

Natuurlijk. Er zijn goede redenen om een changelog te verbeteren. Ik open regelmatig een pull request om missende releases toe te voegen aan open source projecten met een slecht onderhouden changelog.

Het kan ook zo zijn dat je ontdekt dat je een belangrijke aanpassing niet vermeld hebt in je changelog. Het is dan natuurlijk zaak om dit alsnog in je changelog te vermelden.

Hoe kan ik bijdragen?

Dit document is niet de waarheid; het is mijn weloverwogen mening, samen met wat informatie en voorbeelden die ik verzameld heb.

Dit heb ik gedaan omdat ik wil dat de programmeer gemeenschap een consensus bereikt. Ik denk dat de discussie net zo belangrijk is als het eindresultaat.

Dus alle hulp is welkom.

Conversaties

Ik was te gast bij The Changelog podcast om te praten over waarom een changelog belangrijk is programmeurs, en over mijn motivatie achter dit project.

Houd een Changelog bij

Laat je vrienden geen git logs in changelogs dumpen.

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

## [Unreleased]

## [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

Wat is een changelog?

Een changelog is een bestand met een zorgvuldig samengestelde, chronologische lijst van noemenswaardige aanpassingen voor elke versie van een project.

Waarom een changelog bijhouden?

Om het makkelijker te maken voor gebruikers en programmeurs om precies te zien welke noemenswaardige aanpassingen er gedaan zijn tussen elke release (of versie) van het project.

Wie heeft een changelog nodig?

Mensen hebben het nodig. Of het nu consumenten of ontwikkelaars zijn, eindgebruikers van software zijn mensen die er om geven wat er in de software zit die ze gebruiken. Als de software verandert, wil men weten wat en hoe.

Hoe maak ik een goed changelog?

Richtlijnen

  • Changelogs zijn voor mensen, niet voor machines.
  • Er zou een vermelding moeten zijn voor elke versie.
  • Aanpassingen van het zelfde type moeten gegroepeerd worden.
  • Versies en secties zouden linkbaar moeten zijn.
  • De laatste versie staat bovenaan.
  • De release datum van elke versie word weergegeven.
  • Geef aan of je Semantic Versioning gebruikt.

Types of changes

  • Added voor nieuwe functionaliteit.
  • Changed voor aanpassingen aan bestaande functionaliteit.
  • Deprecated voor functionaliteit die binnenkort komt te vervallen.
  • Removed voor functionaliteit die vanaf nu vervallen is.
  • Fixed voor bug fixes.
  • Security voor aanpassingen met betrekking tot veiligheid.

Hoe kan ik, met zo min mogelijk moeite, een changelog bij houden?

Houd bovenin een Unreleased sectie bij met aanpassingen voor de komende release.

Dit heeft twee doelen:

  • Mensen kunnen zien wat te verwachten in de aankomende release.
  • Als je een release doet kan je eenvoudig de Unreleased sectie aanpassen naar een nieuwe release sectie.

Kan een changelog slecht zijn?

Ja. Hier een paar manieren waarop je een changelog behoorlijk onbruikbaar kan maken.

Commit log diffs

Commit log diffs gebruiken als een changelog is een slecht idee: ze staan vol met ruis. Denk bijvoorbeeld aan merge commits, commits met onduidelijke titels, documentatie aanpassingen etc.

Het doel van een commit bericht is om één enkele stap in de evolutie van de code te beschrijven.

Het doel van een changelog is om noemenswaardige aanpassingen te documenteren, vaak over meerdere commits, en om deze duidelijk naar de eindgebruiker te communiceren.

Deprecations negeren

Wanneer mensen upgraden van de ene naar de andere versie, moet het overduidelijk zijn als er iets niet meer zal werken. Het moet mogelijk zijn om te upgraden naar een versie met deprecations, vervolgens de deprecations weg te halen, en vervolgens de upgrade kunnen doen naar de versie waar de deprecations removals zijn geworden.

Geef altijd op zijn minst de deprecations, removals en changes met grote impact aan in je changelog.

Verwarrende datums

Datum notaties verschillen van land tot land, en het is vaak moeilijk om een notatie te vinden die makkelijk te lezen is en intuïtief is voor iedereen. Het voordeel van de notatie 2017-07-17 is dat het jaar, maand en dag op volgorde van grootte laat zien. Daarom, en het feit dat dit een ISO standaard is, is dit de aanbevolen datum notatie voor changelog releases.

Inconsistente Aanpassingen

Een changelog waar slechts een aantal van de aanpassingen in vermeld staat lan net zo gevaarlijk zijn als geen changelog hebben. Sommige aanpassingen zullen te irrelevant zijn - bijvoorbeeld, het weghalen van een overbodige spatie hieft niet altijd vermeld te worden - maar alle belanrijke aanpassingen souden in het changelog vermeld moeten worden. Door inconsistent te loggen kunnen gebruikers onterecht denken dat de changelog de de complete bron van waarheid is. Dit zou wel zo moeten zijn. "With great power comes great responsibility". Als je een changelog bij houd, zorg er dan voor dat deze continue bijgehouden word.

Veel Gestelde Vragen

Is er een standaard changelog template?

Niet echt. Er is de GNU changelog style guide, en het twee paragrafen lange GNU NEWS bestand "richtlijnen". Beiden zijn niet volledig genoeg.

Dit project poogt een betere changelog standaard te creëren. Dit op basis van "good practices" uit de open source wereld.

Opbouwende kritiek, discussie en suggesties voor verbetering zijn welkom.

Wat zou de changelog bestandsnaam moeten zijn?

Noem het CHANGELOG.md. Sommige projecten gebruiken HISTORY, NEWS of RELEASES.

Je kan denken dat de bestandsnaam niet heel belangrijk is, maar waarom zou je het de eindgebruikers moeilijker maken om de changelog te vinden?

Wat denk je van GitHub Releases?

Het is een goed initiatief. Releases kan gebruikt worden om simpele git tags (bijvoorbeeld een tag met de naam v1.0.0) te veranderen in uitgebreide release notes door deze handmatig toe te voegen of door geannoteerde git tag berichten te gebruiken om release notes te genereren.

GitHub Releases maken changelog wat alleen getoond kan worden aan gebruikers binnen de context van GitHub. Het is mogelijk om deze dicht bij het format te krijgen wat wij hier promoten, maar er zal iets meer werk voor nodig zijn.

De huidige versie van GitHub releases is naar mijn mening niet echt goed vindbaar voor gebruikers, in tegenstelling tot de typische bestanden die in een naam in hoofdletters hebben (README, CONTRIBUTING, etc.). Een ander knelpunt is dat de interface geen links toestaat naar commit logs van elke release.

Kunnen changelogs automatisch geparsed worden?

Dat is lastig, mensen gebruiken immers veel verschillende formats en bestandsnamen.

Vandamme is een Ruby gem van het Gemnasium team wat de changelogs van veel (maar niet alle) open source projecten kan parsen.

Wat doen we met teruggetrokken (yanked) releases?

Teruggetrokken releases zijn versies die teruggetrokken zijn als gevolg van een serieuze bug of beveiligings probleem. Vaak zijn ze niet eens te zien in de changelogs. Dat zou wel moeten. Zo zou je een teruggetrokken release moeten tonen:

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

De [YANKED] tag is in hoofdletters voor een reden. Het is belangrijk dat mensen dit zien. Omdat het tussen blokhaken genoteerd is, is het ook makkelijker automatisch te parsen.

Mag je een changelog aanpassen/herschrijven?

Natuurlijk. Er zijn goede redenen om een changelog te verbeteren. Ik open regelmatig een pull request om missende releases toe te voegen aan open source projecten met een slecht onderhouden changelog.

Het kan ook zo zijn dat je ontdekt dat je een belangrijke aanpassing niet vermeld hebt in je changelog. Het is dan natuurlijk zaak om dit alsnog in je changelog te vermelden.

Hoe kan ik bijdragen?

Dit document is niet de waarheid; het is mijn weloverwogen mening, samen met wat informatie en voorbeelden die ik verzameld heb.

Dit heb ik gedaan omdat ik wil dat de programmeer gemeenschap een consensus bereikt. Ik denk dat de discussie net zo belangrijk is als het eindresultaat.

Dus alle hulp is welkom.

Conversaties

Ik was te gast bij The Changelog podcast om te praten over waarom een changelog belangrijk is programmeurs, en over mijn motivatie achter dit project.

Houd een Changelog bij

Laat je vrienden geen git logs in changelogs dumpen.

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

## [Unreleased]

## [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

Wat is een changelog?

Een changelog is een bestand met een zorgvuldig samengestelde, chronologische lijst van noemenswaardige aanpassingen voor elke versie van een project.

Waarom een changelog bijhouden?

Om het makkelijker te maken voor gebruikers en programmeurs om precies te zien welke noemenswaardige aanpassingen er gedaan zijn tussen elke release (of versie) van het project.

Wie heeft een changelog nodig?

Mensen hebben het nodig. Of het nu consumenten of ontwikkelaars zijn, eindgebruikers van software zijn mensen die er om geven wat er in de software zit die ze gebruiken. Als de software verandert, wil men weten wat en hoe.

Hoe maak ik een goed changelog?

Richtlijnen

  • Changelogs zijn voor mensen, niet voor machines.
  • Er zou een vermelding moeten zijn voor elke versie.
  • Aanpassingen van het zelfde type moeten gegroepeerd worden.
  • Versies en secties zouden linkbaar moeten zijn.
  • De laatste versie staat bovenaan.
  • De release datum van elke versie word weergegeven.
  • Geef aan of je Semantic Versioning gebruikt.

Types of changes

  • Added voor nieuwe functionaliteit.
  • Changed voor aanpassingen aan bestaande functionaliteit.
  • Deprecated voor functionaliteit die binnenkort komt te vervallen.
  • Removed voor functionaliteit die vanaf nu vervallen is.
  • Fixed voor bug fixes.
  • Security voor aanpassingen met betrekking tot veiligheid.

Hoe kan ik, met zo min mogelijk moeite, een changelog bij houden?

Houd bovenin een Unreleased sectie bij met aanpassingen voor de komende release.

Dit heeft twee doelen:

  • Mensen kunnen zien wat te verwachten in de aankomende release.
  • Als je een release doet kan je eenvoudig de Unreleased sectie aanpassen naar een nieuwe release sectie.

Kan een changelog slecht zijn?

Ja. Hier een paar manieren waarop je een changelog behoorlijk onbruikbaar kan maken.

Commit log diffs

Commit log diffs gebruiken als een changelog is een slecht idee: ze staan vol met ruis. Denk bijvoorbeeld aan merge commits, commits met onduidelijke titels, documentatie aanpassingen etc.

Het doel van een commit bericht is om één enkele stap in de evolutie van de code te beschrijven.

Het doel van een changelog is om noemenswaardige aanpassingen te documenteren, vaak over meerdere commits, en om deze duidelijk naar de eindgebruiker te communiceren.

Deprecations negeren

Wanneer mensen upgraden van de ene naar de andere versie, moet het overduidelijk zijn als er iets niet meer zal werken. Het moet mogelijk zijn om te upgraden naar een versie met deprecations, vervolgens de deprecations weg te halen, en vervolgens de upgrade kunnen doen naar de versie waar de deprecations removals zijn geworden.

Geef altijd op zijn minst de deprecations, removals en changes met grote impact aan in je changelog.

Verwarrende datums

Datum notaties verschillen van land tot land, en het is vaak moeilijk om een notatie te vinden die makkelijk te lezen is en intuïtief is voor iedereen. Het voordeel van de notatie 2017-07-17 is dat het jaar, maand en dag op volgorde van grootte laat zien. Daarom, en het feit dat dit een ISO standaard is, is dit de aanbevolen datum notatie voor changelog releases.

Inconsistente Aanpassingen

Een changelog waar slechts een aantal van de aanpassingen in vermeld staat lan net zo gevaarlijk zijn als geen changelog hebben. Sommige aanpassingen zullen te irrelevant zijn - bijvoorbeeld, het weghalen van een overbodige spatie hieft niet altijd vermeld te worden - maar alle belanrijke aanpassingen souden in het changelog vermeld moeten worden. Door inconsistent te loggen kunnen gebruikers onterecht denken dat de changelog de de complete bron van waarheid is. Dit zou wel zo moeten zijn. "With great power comes great responsibility". Als je een changelog bij houd, zorg er dan voor dat deze continue bijgehouden word.

Veel Gestelde Vragen

Is er een standaard changelog template?

Niet echt. Er is de GNU changelog style guide, en het twee paragrafen lange GNU NEWS bestand "richtlijnen". Beiden zijn niet volledig genoeg.

Dit project poogt een betere changelog standaard te creëren. Dit op basis van "good practices" uit de open source wereld.

Opbouwende kritiek, discussie en suggesties voor verbetering zijn welkom.

Wat zou de changelog bestandsnaam moeten zijn?

Noem het CHANGELOG.md. Sommige projecten gebruiken HISTORY, NEWS of RELEASES.

Je kan denken dat de bestandsnaam niet heel belangrijk is, maar waarom zou je het de eindgebruikers moeilijker maken om de changelog te vinden?

Wat denk je van GitHub Releases?

Het is een goed initiatief. Releases kan gebruikt worden om simpele git tags (bijvoorbeeld een tag met de naam v1.0.0) te veranderen in uitgebreide release notes door deze handmatig toe te voegen of door geannoteerde git tag berichten te gebruiken om release notes te genereren.

GitHub Releases maken changelog wat alleen getoond kan worden aan gebruikers binnen de context van GitHub. Het is mogelijk om deze dicht bij het format te krijgen wat wij hier promoten, maar er zal iets meer werk voor nodig zijn.

De huidige versie van GitHub releases is naar mijn mening niet echt goed vindbaar voor gebruikers, in tegenstelling tot de typische bestanden die in een naam in hoofdletters hebben (README, CONTRIBUTING, etc.). Een ander knelpunt is dat de interface geen links toestaat naar commit logs van elke release.

Kunnen changelogs automatisch geparsed worden?

Dat is lastig, mensen gebruiken immers veel verschillende formats en bestandsnamen.

Vandamme is een Ruby gem van het Gemnasium team wat de changelogs van veel (maar niet alle) open source projecten kan parsen.

Wat doen we met teruggetrokken (yanked) releases?

Teruggetrokken releases zijn versies die teruggetrokken zijn als gevolg van een serieuze bug of beveiligings probleem. Vaak zijn ze niet eens te zien in de changelogs. Dat zou wel moeten. Zo zou je een teruggetrokken release moeten tonen:

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

De [YANKED] tag is in hoofdletters voor een reden. Het is belangrijk dat mensen dit zien. Omdat het tussen blokhaken genoteerd is, is het ook makkelijker automatisch te parsen.

Mag je een changelog aanpassen/herschrijven?

Natuurlijk. Er zijn goede redenen om een changelog te verbeteren. Ik open regelmatig een pull request om missende releases toe te voegen aan open source projecten met een slecht onderhouden changelog.

Het kan ook zo zijn dat je ontdekt dat je een belangrijke aanpassing niet vermeld hebt in je changelog. Het is dan natuurlijk zaak om dit alsnog in je changelog te vermelden.

Hoe kan ik bijdragen?

Dit document is niet de waarheid; het is mijn weloverwogen mening, samen met wat informatie en voorbeelden die ik verzameld heb.

Dit heb ik gedaan omdat ik wil dat de programmeer gemeenschap een consensus bereikt. Ik denk dat de discussie net zo belangrijk is als het eindresultaat.

Dus alle hulp is welkom.

Conversaties

Ik was te gast bij The Changelog podcast om te praten over waarom een changelog belangrijk is programmeurs, en over mijn motivatie achter dit project.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Prowadź CHANGELOG

Nie pozwól, by twoi znajomi wklejali logi gita do CHANGELOGów™

Wersja 0.3.0

Czym jest changelog?

Changelog, inaczej rejestr zmian lub historia zmian, to plik zawierający chronologicznie uporządkowaną listę istotnych zmian dla każdej wersji projektu.

# 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.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?".

Co jest celem prowadzenia changelogu?

Changelog pomaga użytkownikom zrozumieć, jakie znaczące zmiany zostały wprowadzone w każdej wersji projektu.

Dlaczego miałoby mi zależeć?

Ponieważ narzędzia informatyczne są dla ludzi. Jeśli ci nie zależy, dlaczego przyczyniasz się do powstawania otwartego oprogramowania (open source)?

Rozmawiałem na podcaście "The Changelog" z Adamem Stacoviakiem i Jerodem Santo (odpowiednia nazwa, prawda?) o tym, dlaczego osobom wspierającym otwarte programowanie powinno zależeć, oraz o celach samego projektu. Jeśli masz chwilę (1:06), zapraszam do posłuchania - warto.

Co składa się na dobry changelog?

Cieszę się, że zapytałeś.

Dobry changelog trzyma się następujących zasad:

Jak mogę zminimalizować wysiłek wkładany w prowadzenie changelogu?

Zawsze umieszczaj rozdział "Unreleased" na szczycie dokumentu, w celu śledzenia wszelkich zmian.

Ta praktyka ma dwa cele:

Co sprawia, że jednorożce płaczą?

Dobrze... zabierzmy się za to.

To jeszcze nie koniec. Pomóż mi zebrać wszystkie łzy jednorożców zgłaszając problem lub wprowadzając zmianę poprzez pull request.

Czy istnieje standardowy format changelogu?

Niestety nie, ale spokojnie. Wiem, że spieszysz wkleić link do tego przewodnika stylu changelogu GNU, czy do dwóch paragrafów "wytycznych" GNU NEWS. Przewodnik stylu GNU to dobry, ale niestety naiwny początek. Nie ma nic złego w byciu naiwnym, ale gdy ludzie potrzebują wytycznych, bycie naiwnym rzadko pomaga. Szczególnie, gdy istnieje wiele sytuacji i szczególnych przypadków z którymi trzeba się zmierzyć.

Mam nadzieję, że ten projekt zostanie uznany lepszym standardem pliku CHANGELOG.

Nie uważam, że status quo jest wystarczające i myślę, że jako społeczność, możemy stworzyć lepsze konwencje, jeśli spróbujemy zastosować dobre praktyki stosowane w prawdziwych projektach informatycznych. Proszę, zapoznaj się z projektem i pamiętaj, że dyskusja i sugestie są zawsze mile widziane!

Jak powinien być nazwany plik changelog?

Jeśli nie potrafisz wywnioskować z powyższego przykładu, CHANGELOG.md to do tej pory najlepsza konwencja.

Niektóre projekty również stosują HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, itd.

Straszny bałagan. Wszystkie te nazwy sprawiają, że jeszcze ciężej jest odnaleźć ten plik.

Dlaczego nie mielibyśmy po prostu stosować raportu git log?

Ponieważ logi typu diff są z natury zagmatwane. Nawet przy hipotetycznym projekcie stworzonym przez doskonałe istoty ludzkie, które nigdy nie popełniają literówek, nigdy nie zapominają o zsynchronizowaniu nowo dodanych plików czy nigdy niczego nie pomijają podczas refaktoryzacji kodu, logi diff nie mogłyby zastąpić changelogu. Celem git commit jest udokumentowanie jednego kroku w procesie, dzięki któremu kod ewoluuje z jednego stanu w kolejny. Celem changelogu jest udokumentowanie tych różnic pomiędzy stanami kodu, które są godne uwagi.

Różnica między changelogiem a logiem diff, tak samo jak różnica między dobrymi komentarzami a kodem, jest następująca: pierwsze opisuje dlaczego, drugie - jak.

Czy changelog może być generowany automatycznie?

To nie takie proste, ponieważ ludzie stosują bardzo różne formaty oraz nazwy plików.

Vandamme to gem Ruby stworzony przez ekipę Gemnasium, parsujący changelogi wielu (ale nie wszystkich) projektów open source.

Dlaczego czasem stosujesz pisownię "CHANGELOG", a czasem "changelog"?

"CHANGELOG" to nazwa samego pliku. Wygląda to dość głośno, ale taka jest historyczna konwencja przyjęta przez wiele projektów open source. Inne przykłady podobnych plików to README, LICENSE, oraz CONTRIBUTING.

Zapis wielkimi literami (dzięki któremu w starszych systemach operacyjnch pliki zostają umieszczone na szczycie listy) ma na celu zwrócenie na nie uwagi. Jako że są to ważne informacje dotyczące projektu, mogą być one użyteczne dla każdego, kto zamierza korzystać lub wnieść weń wkład. Ida ta zbliżona jest do odznaczeń przy projektach open source.

Gdy stosuję pisownię "changelog", mówię o samej funkcji tego pliku: rejestrowaniu zmian.

A co z błędnymi wersjami (yanked)?

Są to wersje opublikowane błędnie, czyli takie, które musiały zostać wycofane ze względu na poważny błąd lub lukę bezpieczeństwa. Często takie wersje projektu nie pojawiają się nawet w changelogu, a powinny. Oto jak taka wersja powinna wyglądać:

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

Tag [YANKED] jest celowo zapisany wielkimi literami. Ważne jest, by został on dostrzeżony. Dzięki temu, że jest ujęty w nawias, może być z łatwością generowany automatycznie.

Czy powinno się kiedykolwiek poprawiać changelog?

Oczywiście. Zawsze istnieją powody, by ulepszyć changelog. Często zdarza mi się edytować changelogi w projektach open source w których pominięto udokumentowanie istotnych zmian.

Może się również zdarzyć, że odkryjesz, iż podczas przygotowywania notatek dla wersji projektu, zapomniałeś udokumentować istotną zmianę, która ma wpływ na działanie aplikacji. Ważne jest, by zaktualizować changelog szczególnie jeśli jest to zmiana, która w istotny sposób wpływa na kompatybilność aplikacji.

Jak mogę wnieść wkład w projekt?

Ten dokument to nie jedna i jedyna prawda; to moja starannie sformułowana opinia wraz z informacją i przykładami które zebrałem. Pomimo tego, że prowadzę właściwy CHANGELOG na GitHubie, celowo nie stworzyłem poprawnego releasu czy jasno sprecyzowanych wytycznych (tak jak np. na SemVer.org).

Chcę, by nasza społeczność uzgodniła jak CHANGELOG ma wyglądać. Wierzę, że dyskusja jest niezbędna do osiągnięcia końcowego rezultatu.

Więc proszę, dołącz do projektu.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Prowadź CHANGELOG

Nie pozwól, by twoi znajomi wklejali logi gita do CHANGELOGów™

Wersja 0.3.0

Czym jest changelog?

Changelog, inaczej rejestr zmian lub historia zmian, to plik zawierający chronologicznie uporządkowaną listę istotnych zmian dla każdej wersji projektu.

# 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.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?".

Co jest celem prowadzenia changelogu?

Changelog pomaga użytkownikom zrozumieć, jakie znaczące zmiany zostały wprowadzone w każdej wersji projektu.

Dlaczego miałoby mi zależeć?

Ponieważ narzędzia informatyczne są dla ludzi. Jeśli ci nie zależy, dlaczego przyczyniasz się do powstawania otwartego oprogramowania (open source)?

Rozmawiałem na podcaście "The Changelog" z Adamem Stacoviakiem i Jerodem Santo (odpowiednia nazwa, prawda?) o tym, dlaczego osobom wspierającym otwarte programowanie powinno zależeć, oraz o celach samego projektu. Jeśli masz chwilę (1:06), zapraszam do posłuchania - warto.

Co składa się na dobry changelog?

Cieszę się, że zapytałeś.

Dobry changelog trzyma się następujących zasad:

Jak mogę zminimalizować wysiłek wkładany w prowadzenie changelogu?

Zawsze umieszczaj rozdział "Unreleased" na szczycie dokumentu, w celu śledzenia wszelkich zmian.

Ta praktyka ma dwa cele:

Co sprawia, że jednorożce płaczą?

Dobrze... zabierzmy się za to.

To jeszcze nie koniec. Pomóż mi zebrać wszystkie łzy jednorożców zgłaszając problem lub wprowadzając zmianę poprzez pull request.

Czy istnieje standardowy format changelogu?

Niestety nie, ale spokojnie. Wiem, że spieszysz wkleić link do tego przewodnika stylu changelogu GNU, czy do dwóch paragrafów "wytycznych" GNU NEWS. Przewodnik stylu GNU to dobry, ale niestety naiwny początek. Nie ma nic złego w byciu naiwnym, ale gdy ludzie potrzebują wytycznych, bycie naiwnym rzadko pomaga. Szczególnie, gdy istnieje wiele sytuacji i szczególnych przypadków z którymi trzeba się zmierzyć.

Mam nadzieję, że ten projekt zostanie uznany lepszym standardem pliku CHANGELOG.

Nie uważam, że status quo jest wystarczające i myślę, że jako społeczność, możemy stworzyć lepsze konwencje, jeśli spróbujemy zastosować dobre praktyki stosowane w prawdziwych projektach informatycznych. Proszę, zapoznaj się z projektem i pamiętaj, że dyskusja i sugestie są zawsze mile widziane!

Jak powinien być nazwany plik changelog?

Jeśli nie potrafisz wywnioskować z powyższego przykładu, CHANGELOG.md to do tej pory najlepsza konwencja.

Niektóre projekty również stosują HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, itd.

Straszny bałagan. Wszystkie te nazwy sprawiają, że jeszcze ciężej jest odnaleźć ten plik.

Dlaczego nie mielibyśmy po prostu stosować raportu git log?

Ponieważ logi typu diff są z natury zagmatwane. Nawet przy hipotetycznym projekcie stworzonym przez doskonałe istoty ludzkie, które nigdy nie popełniają literówek, nigdy nie zapominają o zsynchronizowaniu nowo dodanych plików czy nigdy niczego nie pomijają podczas refaktoryzacji kodu, logi diff nie mogłyby zastąpić changelogu. Celem git commit jest udokumentowanie jednego kroku w procesie, dzięki któremu kod ewoluuje z jednego stanu w kolejny. Celem changelogu jest udokumentowanie tych różnic pomiędzy stanami kodu, które są godne uwagi.

Różnica między changelogiem a logiem diff, tak samo jak różnica między dobrymi komentarzami a kodem, jest następująca: pierwsze opisuje dlaczego, drugie - jak.

Czy changelog może być generowany automatycznie?

To nie takie proste, ponieważ ludzie stosują bardzo różne formaty oraz nazwy plików.

Vandamme to gem Ruby stworzony przez ekipę Gemnasium, parsujący changelogi wielu (ale nie wszystkich) projektów open source.

Dlaczego czasem stosujesz pisownię "CHANGELOG", a czasem "changelog"?

"CHANGELOG" to nazwa samego pliku. Wygląda to dość głośno, ale taka jest historyczna konwencja przyjęta przez wiele projektów open source. Inne przykłady podobnych plików to README, LICENSE, oraz CONTRIBUTING.

Zapis wielkimi literami (dzięki któremu w starszych systemach operacyjnch pliki zostają umieszczone na szczycie listy) ma na celu zwrócenie na nie uwagi. Jako że są to ważne informacje dotyczące projektu, mogą być one użyteczne dla każdego, kto zamierza korzystać lub wnieść weń wkład. Ida ta zbliżona jest do odznaczeń przy projektach open source.

Gdy stosuję pisownię "changelog", mówię o samej funkcji tego pliku: rejestrowaniu zmian.

A co z błędnymi wersjami (yanked)?

Są to wersje opublikowane błędnie, czyli takie, które musiały zostać wycofane ze względu na poważny błąd lub lukę bezpieczeństwa. Często takie wersje projektu nie pojawiają się nawet w changelogu, a powinny. Oto jak taka wersja powinna wyglądać:

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

Tag [YANKED] jest celowo zapisany wielkimi literami. Ważne jest, by został on dostrzeżony. Dzięki temu, że jest ujęty w nawias, może być z łatwością generowany automatycznie.

Czy powinno się kiedykolwiek poprawiać changelog?

Oczywiście. Zawsze istnieją powody, by ulepszyć changelog. Często zdarza mi się edytować changelogi w projektach open source w których pominięto udokumentowanie istotnych zmian.

Może się również zdarzyć, że odkryjesz, iż podczas przygotowywania notatek dla wersji projektu, zapomniałeś udokumentować istotną zmianę, która ma wpływ na działanie aplikacji. Ważne jest, by zaktualizować changelog szczególnie jeśli jest to zmiana, która w istotny sposób wpływa na kompatybilność aplikacji.

Jak mogę wnieść wkład w projekt?

Ten dokument to nie jedna i jedyna prawda; to moja starannie sformułowana opinia wraz z informacją i przykładami które zebrałem. Pomimo tego, że prowadzę właściwy CHANGELOG na GitHubie, celowo nie stworzyłem poprawnego releasu czy jasno sprecyzowanych wytycznych (tak jak np. na SemVer.org).

Chcę, by nasza społeczność uzgodniła jak CHANGELOG ma wyglądać. Wierzę, że dyskusja jest niezbędna do osiągnięcia końcowego rezultatu.

Więc proszę, dołącz do projektu.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Prowadź Changelog

Nie pozwól swoim znajomym wklejać logów Gita do changelogów.

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

## [Unreleased]

## [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

Czym jest changelog?

Changelog, inaczej rejestr zmian, to plik zawierający utrzymywaną, uporządkowaną chronologicznie, listę istotnych zmian dla każdej wersji projektu.

Po co prowadzić changelog?

Aby użytkownikom i deweloperom łatwiej było dokładnie zobaczyć, jakie znaczące zmiany zostały wprowadzane w każdym wydaniu (lub wersji) projektu.

Komu potrzebny jest changelog?

Ludziom. Czy to klienci czy deweloperzy, końcowi użytkownicy oprogramowania są istotami ludzkimi, którym nie jest obojętne, co jest w oprogramowaniu. Kiedy oprogramowanie się zmienia, ludzie chcą wiedzieć dlaczego i jak.

Jak zrobić dobry changelog?

Zasady przewodnie

  • Changelogi są dla ludzi, nie maszyn.
  • Każda wersja powinna mieć swój wpis.
  • Jednakowe typy zmian powinny być zgrupowane.
  • Wersje i sekcje powinny być linkowalne.
  • Najnowsza wersja na pierwszym miejscu.
  • Wyszczególniona data wydania każdej wersji.
  • Wzmianka, czy przestrzegacie wersjonowania semantycznego.

Typy zmian

  • Dodane dla nowych funkcjonalności.
  • Zmienione dla zmian w istniejących funkcjonalnościach.
  • Zdezaprobowane dla funkcjonalności wkrótce do usunięcia.
  • Usunięte dla teraz usuwanych funkcjonalności.
  • Naprawione dla jakichkolwiek poprawek błędów.
  • Bezpieczeństwo w przypadku luk w zabezpieczeniach.

Jak mogę zminimalizować wysiłek wkładany w prowadzenie changelogu?

Prowadź sekcję Niewydane na szczycie dokumentu, aby śledzić nadchodzące zmiany.

Ta praktyka ma dwa cele:

  • Ludzie widzą, jakich zmian mogą się spodziewać w nadchodzących wydaniach.
  • W momencie wydania możesz przenieść zmiany z sekcji Niewydane do sekcji nowego wydania.

Czy changelogi mogą być złe?

Tak. Oto kilka sposobów, w jakie mogą być mniej niż użyteczne.

Zmiany w commit logu

Używanie zmian w commit logach jako changelogów jest złym pomysłem: commit logi są pełne szumu: rzeczy takich jak merge commity, commity z niejasnymi tytułami, zmiany w dokumentacji itp.

Zadaniem commita jest udokumentowanie kroku w ewolucji kodu źródłowego. Niektóre projekty porządkują commity, niektóre nie.

Zadaniem wpisu w changelogu jest udokumentowanie zmian godnych odnotowania, często składających się z wielu commitów, aby przedstawić je jasno użytkownikom końcowym.

Ignorowanie dezaprobowań

Gdy ludzie robią upgrade z jednej wersji do drugiej, powinno być bezboleśnie jasne kiedy coś się może zepsuć. Powinno być możliwe upgrade'owanie się do wersji, która wypisuje zdezaprobowania, usunięcie tego, co jest zdezaprobowane, następnie upgrade'owanie się do wersji, w której dezaprobowane funkcjonalności są usuwane.

Jeśli nie robisz nic innego, wypisz w swoim changelogu zdezaprobowania, usunięcia i jakiekolwiek zmiany łamiące zgodność wstecz.

Mylące daty

Regionalne formaty dat różnią się na świecie i często trudno jest znaleźć przyjazny człowiekowi format daty, który wydaje się intuicyjny wszystkim. Zaletą dat sformatowanych tak jak 2017-07-17 jest to, że są one uporządkowane od największych do najmniejszych jednostek: roku, miesiąca i dnia. Ten format również nie nachodzi w niejednoznaczny sposób na inne formaty dat, w przeciwieństwie do niektórych regionalnych formatów, które zamieniają miejsce numerów miesiąca i dnia. Z tych powodów i faktu, że ten format daty jest standardem ISO, wynika rekomendacja tego formatu daty do wpisów w changelogu.

Często zadawane pytania

Czy istnieje standardowy format changelogu?

Niezupełnie. Jest przewodnik stylu changelogu GNU, czy dwuparagrafowe „wytyczne” GNU NEWS. Oba dokumenty są nieadekwatne lub niewystarczające.

Ten projekt pretenduje do bycia lepszą konwencją changelogu. Pochodzi z obserwowania i zebrania dobrych praktyk w społeczności open source.

Zdrowa krytyka, dyskusja i sugestie poprawek są mile widziane.

Jak powinien się nazywać plik z changelogiem?

Nazwij go CHANGELOG.md. Niektóre projekty używają HISTORY, NEWS lub RELEASES.

Łatwo jest uznać, że nazwa pliku z changelogiem nie ma większego znaczenia, lecz po co utrudniać swoim użytkownikom końcowym odnajdowanie w sposób konsekwentny istotnych zmian?

Co z GitHub Releases?

To wspaniała inicjatywa. Releases mogą być używane do zmiany prostych tagów Gita (na przykład taga nazwanego v1.0.0) w bogate informacje o wydaniach przez ręczne dodanie informacji lub mogą wyciągać oznaczone message tagów i przekształcać je w informacje.

GitHub Releases tworzą nieprzenośny changelog, który może być prezentowany użytkownikom tylko w kontekście GitHuba. Można go bardzo upodobnić do formatu Prowadź changelog, ale będzie to dość skomplikowane.

Bieżąca wersja wydań GitHub jest też prawdopodobnie nienajłatwiejsza do odnalezienia dla użytkowników końcowych, w przeciwieństwie do plików o nazwach z wielkimi literami (README, CONTRIBUTING itp.). Innym mniejszym brakiem jest to, że interfejs obecnie nie posiada linków do logów commitów pomiędzy każdymi wydaniami.

Czy changelogi mogą być parsowane automatycznie?

To trudne, ponieważ ludzie stosują bardzo różne formaty i nazwy plików.

Vandamme jest gemem Ruby stworzonym przez zespół Gemnasium i który parsuje wiele (ale nie wszystkie) changelogów projektów open source.

Co z wycofanymi wydaniami?

Wydania typu yanked to wersje, które musiały zostać usunięte z powodu poważnego błędu lub problemów z bezpieczeństwem. Często te wersje nie pojawiają się w dziennikach zmian. Powinny. Tak powinieneś je wyświetlać:

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

Etykieta [WYCOFANA] jest celowo zapisana wielkimi literami. Ważne jest, by zwracano na nią uwagę. Jest otoczona nawiasami, więc jest również prostsza do sparsowania przez skrypt.

Czy powinno się kiedykolwiek przerabiać changelog?

Pewnie. Zawsze istnieją dobre powody, by ulepszyć changelog. Regularnie otwieram pull requesty dodające brakujące wydania do open-source'owych projektów z nieutrzymywanymi changelogami.

Może się również zdarzyć, że odkryjesz, iż zapomniałeś udokumentować zmianę zrywającą zgodność wsteczną w notatkach dla wersji. Oczywiście ważne jest, abyś zaktualizował swój changelog w tym przypadku.

Jak mogę wnieść swój wkład?

Ten dokument nie jest obiektywną prawdą; jest moją starannie przemyślaną opinią, z informacjami i przykładami, które zebrałem.

To dlatego, że chcę, aby nasza społeczność osiągnęła konsensus. Wierzę, że dyskusja jest tak samo istotna jak efekt końcowy.

Więc proszę, wtrąć się.

Rozmowy

Byłem na podcaście Changelog, aby porozmawiać dlaczego opiekunowie i kontrybutorzy powinni dbać o changelogi, a także o motywacjach stojących za tym projektem.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Prowadź Changelog

Nie pozwól swoim znajomym wklejać logów Gita do changelogów.

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

## [Unreleased]

## [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

Czym jest changelog?

Changelog, inaczej rejestr zmian, to plik zawierający utrzymywaną, uporządkowaną chronologicznie, listę istotnych zmian dla każdej wersji projektu.

Po co prowadzić changelog?

Aby użytkownikom i deweloperom łatwiej było dokładnie zobaczyć, jakie znaczące zmiany zostały wprowadzane w każdym wydaniu (lub wersji) projektu.

Komu potrzebny jest changelog?

Ludziom. Czy to klienci czy deweloperzy, końcowi użytkownicy oprogramowania są istotami ludzkimi, którym nie jest obojętne, co jest w oprogramowaniu. Kiedy oprogramowanie się zmienia, ludzie chcą wiedzieć dlaczego i jak.

Jak zrobić dobry changelog?

Zasady przewodnie

  • Changelogi są dla ludzi, nie maszyn.
  • Każda wersja powinna mieć swój wpis.
  • Jednakowe typy zmian powinny być zgrupowane.
  • Wersje i sekcje powinny być linkowalne.
  • Najnowsza wersja na pierwszym miejscu.
  • Wyszczególniona data wydania każdej wersji.
  • Wzmianka, czy przestrzegacie wersjonowania semantycznego.

Typy zmian

  • Dodane dla nowych funkcjonalności.
  • Zmienione dla zmian w istniejących funkcjonalnościach.
  • Zdezaprobowane dla funkcjonalności wkrótce do usunięcia.
  • Usunięte dla teraz usuwanych funkcjonalności.
  • Naprawione dla jakichkolwiek poprawek błędów.
  • Bezpieczeństwo w przypadku luk w zabezpieczeniach.

Jak mogę zminimalizować wysiłek wkładany w prowadzenie changelogu?

Prowadź sekcję Niewydane na szczycie dokumentu, aby śledzić nadchodzące zmiany.

Ta praktyka ma dwa cele:

  • Ludzie widzą, jakich zmian mogą się spodziewać w nadchodzących wydaniach.
  • W momencie wydania możesz przenieść zmiany z sekcji Niewydane do sekcji nowego wydania.

Czy changelogi mogą być złe?

Tak. Oto kilka sposobów, w jakie mogą być mniej niż użyteczne.

Zmiany w commit logu

Używanie zmian w commit logach jako changelogów jest złym pomysłem: commit logi są pełne szumu: rzeczy takich jak merge commity, commity z niejasnymi tytułami, zmiany w dokumentacji itp.

Zadaniem commita jest udokumentowanie kroku w ewolucji kodu źródłowego. Niektóre projekty porządkują commity, niektóre nie.

Zadaniem wpisu w changelogu jest udokumentowanie zmian godnych odnotowania, często składających się z wielu commitów, aby przedstawić je jasno użytkownikom końcowym.

Ignorowanie dezaprobowań

Gdy ludzie robią upgrade z jednej wersji do drugiej, powinno być bezboleśnie jasne kiedy coś się może zepsuć. Powinno być możliwe upgrade'owanie się do wersji, która wypisuje zdezaprobowania, usunięcie tego, co jest zdezaprobowane, następnie upgrade'owanie się do wersji, w której dezaprobowane funkcjonalności są usuwane.

Jeśli nie robisz nic innego, wypisz w swoim changelogu zdezaprobowania, usunięcia i jakiekolwiek zmiany łamiące zgodność wstecz.

Mylące daty

Regionalne formaty dat różnią się na świecie i często trudno jest znaleźć przyjazny człowiekowi format daty, który wydaje się intuicyjny wszystkim. Zaletą dat sformatowanych tak jak 2017-07-17 jest to, że są one uporządkowane od największych do najmniejszych jednostek: roku, miesiąca i dnia. Ten format również nie nachodzi w niejednoznaczny sposób na inne formaty dat, w przeciwieństwie do niektórych regionalnych formatów, które zamieniają miejsce numerów miesiąca i dnia. Z tych powodów i faktu, że ten format daty jest standardem ISO, wynika rekomendacja tego formatu daty do wpisów w changelogu.

Często zadawane pytania

Czy istnieje standardowy format changelogu?

Niezupełnie. Jest przewodnik stylu changelogu GNU, czy dwuparagrafowe „wytyczne” GNU NEWS. Oba dokumenty są nieadekwatne lub niewystarczające.

Ten projekt pretenduje do bycia lepszą konwencją changelogu. Pochodzi z obserwowania i zebrania dobrych praktyk w społeczności open source.

Zdrowa krytyka, dyskusja i sugestie poprawek są mile widziane.

Jak powinien się nazywać plik z changelogiem?

Nazwij go CHANGELOG.md. Niektóre projekty używają HISTORY, NEWS lub RELEASES.

Łatwo jest uznać, że nazwa pliku z changelogiem nie ma większego znaczenia, lecz po co utrudniać swoim użytkownikom końcowym odnajdowanie w sposób konsekwentny istotnych zmian?

Co z GitHub Releases?

To wspaniała inicjatywa. Releases mogą być używane do zmiany prostych tagów Gita (na przykład taga nazwanego v1.0.0) w bogate informacje o wydaniach przez ręczne dodanie informacji lub mogą wyciągać oznaczone message tagów i przekształcać je w informacje.

GitHub Releases tworzą nieprzenośny changelog, który może być prezentowany użytkownikom tylko w kontekście GitHuba. Można go bardzo upodobnić do formatu Prowadź changelog, ale będzie to dość skomplikowane.

Bieżąca wersja wydań GitHub jest też prawdopodobnie nienajłatwiejsza do odnalezienia dla użytkowników końcowych, w przeciwieństwie do plików o nazwach z wielkimi literami (README, CONTRIBUTING itp.). Innym mniejszym brakiem jest to, że interfejs obecnie nie posiada linków do logów commitów pomiędzy każdymi wydaniami.

Czy changelogi mogą być parsowane automatycznie?

To trudne, ponieważ ludzie stosują bardzo różne formaty i nazwy plików.

Vandamme jest gemem Ruby stworzonym przez zespół Gemnasium i który parsuje wiele (ale nie wszystkie) changelogów projektów open source.

Co z wycofanymi wydaniami?

Wydania typu yanked to wersje, które musiały zostać usunięte z powodu poważnego błędu lub problemów z bezpieczeństwem. Często te wersje nie pojawiają się w dziennikach zmian. Powinny. Tak powinieneś je wyświetlać:

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

Etykieta [WYCOFANA] jest celowo zapisana wielkimi literami. Ważne jest, by zwracano na nią uwagę. Jest otoczona nawiasami, więc jest również prostsza do sparsowania przez skrypt.

Czy powinno się kiedykolwiek przerabiać changelog?

Pewnie. Zawsze istnieją dobre powody, by ulepszyć changelog. Regularnie otwieram pull requesty dodające brakujące wydania do open-source'owych projektów z nieutrzymywanymi changelogami.

Może się również zdarzyć, że odkryjesz, iż zapomniałeś udokumentować zmianę zrywającą zgodność wsteczną w notatkach dla wersji. Oczywiście ważne jest, abyś zaktualizował swój changelog w tym przypadku.

Jak mogę wnieść swój wkład?

Ten dokument nie jest obiektywną prawdą; jest moją starannie przemyślaną opinią, z informacjami i przykładami, które zebrałem.

To dlatego, że chcę, aby nasza społeczność osiągnęła konsensus. Wierzę, że dyskusja jest tak samo istotna jak efekt końcowy.

Więc proszę, wtrąć się.

Rozmowy

Byłem na podcaście Changelog, aby porozmawiać dlaczego opiekunowie i kontrybutorzy powinni dbać o changelogi, a także o motywacjach stojących za tym projektem.

A última versão (1.1.0) ainda não está disponível em Português mas nesse momento você pode lê-la em inglês e ajudar em sua tradução.

Mantenha um CHANGELOG

Não deixe seus amigos despejarem logs de commits em CHANGELOGs™

Version 0.3.0

O que é um changelog?

Um changelog é um arquivo que contém uma lista selecionada, ordenada cronologicamente, de mudanças significativas para cada versão de um projeto open source.

# 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.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?".

Para que serve um changelog?

Para facilitar que usuários e contribuidores vejam precisamente quais mudanças significativas foram realizadas entre cada versão publicada.

Por que eu deveria me importar?

Porque softwares são feitos para pessoas. Se você não liga, por que está contribuindo com projetos open source? Certamente deve haver um fundo de carinho em algum lugar desse seu amável cerebrinho.

Eu conversei com Adam Stacoviak e Jerod Santo no podcast do The Changelog (faz sentido, hein?) sobre por que mantenedores e contribuidores open source devem se importar e as motivações por trás desse projeto. Se você tem tempo (1:06), é um bom programa.

O que faz um changelog ser bom?

Que bom que perguntou.

Um bom changelog se atém a esses princípios:

Como eu posso minimizar o esforço exigido?

Mantenha sempre uma seção "Unreleased"`"A publicar"` no topo para manter o controle de quaisquer mudanças.

Isso serve a dois propósitos:

O que faz os unicórnios chorarem?

Tudo bem... vamos lá.

Tem mais. Ajude-me a coletar essas lágrimas de unicórnio abrindo uma issue ou um pull request.

Existe um padrão de formato de changelog?

Infelizmente, não. Calma. Eu sei que você está buscando furiosamente aquele link do guia GNU de estilo de changelog, ou o arquivo "guideline" de dois paragráfos do GNU NEWS. O estilo GNU é um bom começo mas, infelizmente, é ingênuo. Não há nada de errado em ser ingênuo mas, quando as pessoas precisam de orientação, raramente ajuda. Especialmente quando existem muitas situações excepcionais para lidar.

Este projeto contém o que eu espero se tornar um melhor padrão de arquivo CHANGELOG para todos os projetos open source. Eu não acredito que o status quo seja bom o suficiente, e acho que, como uma comunidade, nós podemos encontrar novas convenções se tentarmos extrair boas práticas de projetos de software reais. Por favor, dê uma olhada e lembre-se de que discussões e sugestões de melhorias são bem-vindas!

Qual deve ser o nome do arquivo changelog?

Bom, se você não notou no exemplo acima, CHANGELOG.md é a melhor convenção até agora.

Alguns outros projetos também utilizam HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.

É uma bagunça. Todos esses nomes só dificultam encontrar o changelog.

Por que as pessoas não podem simplesmente utilizar git log?

Porque os logs do Git são cheios de ruído — por natureza. Eles não serviriam como um changelog adequado mesmo em um projeto hipotético executado por humanos perfeitos, que nunca erram uma letra, nunca esquecem de commitar arquivos, nunca cometem deslizes em uma refatoração. O propósito de um commit é documentar um passo atômico no processo pelo qual o código evolui de um estado a outro. O propósito de um changelog é documentar as diferenças relevantes entre esses estados.

A mesma diferença que existe entre bons comentários e o código em si existe entre o changelog e o commit log: um descreve o porquê, o outro descreve o como.

Podem os changelogs ser automaticamente interpretados?

É difícil, porque as pessoas seguem formatos e nomes de arquivos radicalmente diferentes.

Vandamme é uma gem criada pelo time Gemnasium que interpreta muitos (mas não todos) changelogs de projetos open source.

Por que você alterna entre as grafias "CHANGELOG" e "changelog"?

"CHANGELOG" é o nome do arquivo em si. É um pouco chamativo mas é uma convenção histórica seguida por muitos projetos open source. Outros exemplos similares de arquivo incluem README, LICENSE, e CONTRIBUTING.

O nome em letras maiúsculas (o que em sistemas operacionais antigos faziam estes arquivos ficarem no topo da lista) é utilizado para chamar atenção. Por conterem importantes metadados do projeto, changelogs são úteis a qualquer um que pretenda utilizar ou contribuir com o projeto, da maneira equivalente às badges de projetos open source.

Quando eu me refiro a "changelog", eu estou falando sobre a função desse arquivo: listar mudanças.

E sobre as publicações removidas?

Publicações removidas são versões que tiveram que ser removidas devido a um sério bug ou problema de segurança. Com frequência essas versões sequer aparecem em changelogs. Deveriam. É assim que você deve exibi-las:

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

A tag [YANKED]/[REMOVIDA] é chamativa por uma razão. É importante que as pessoas a notem. Além disso, já que é cercada por colchetes, é mais fácil detectá-la programaticamente.

Devemos alterar o changelog em alguma circunstância?

Claro. Sempre existem bons motivos para melhorar um changelog. Eu regularmente abro pull requests para adicionar versões faltantes em projetos open source com changelogs abandonados.

Também é possível que você perceba que se esqueceu de registrar mudanças importantes nas notas de uma versão. É obviamente importante que você atualize seu changelog nesse caso.

Como eu posso contribuir?

Este documento não é a verdade; é minha cuidadosa opinião, junto com as informações e exemplos que reuni. Embora eu tenha providenciado um CHANGELOG no repositório no GitHub, eu não criei de propósito uma lista clara de regras a serem seguidas (como o SemVer.org faz, por exemplo).

Fiz isso porque eu gostaria que nossa comunidade chegasse a um consenso. Eu acredito que a discussão é tão importante quanto o resultado final.

Então, por favor, entre em campo.

A última versão (1.1.0) ainda não está disponível em Português mas nesse momento você pode lê-la em inglês e ajudar em sua tradução.

Mantenha um CHANGELOG

Não deixe seus amigos despejarem logs de commits em CHANGELOGs™

Version 0.3.0

O que é um changelog?

Um changelog é um arquivo que contém uma lista selecionada, ordenada cronologicamente, de mudanças significativas para cada versão de um projeto open source.

# 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.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?".

Para que serve um changelog?

Para facilitar que usuários e contribuidores vejam precisamente quais mudanças significativas foram realizadas entre cada versão publicada.

Por que eu deveria me importar?

Porque softwares são feitos para pessoas. Se você não liga, por que está contribuindo com projetos open source? Certamente deve haver um fundo de carinho em algum lugar desse seu amável cerebrinho.

Eu conversei com Adam Stacoviak e Jerod Santo no podcast do The Changelog (faz sentido, hein?) sobre por que mantenedores e contribuidores open source devem se importar e as motivações por trás desse projeto. Se você tem tempo (1:06), é um bom programa.

O que faz um changelog ser bom?

Que bom que perguntou.

Um bom changelog se atém a esses princípios:

Como eu posso minimizar o esforço exigido?

Mantenha sempre uma seção "Unreleased"`"A publicar"` no topo para manter o controle de quaisquer mudanças.

Isso serve a dois propósitos:

O que faz os unicórnios chorarem?

Tudo bem... vamos lá.

Tem mais. Ajude-me a coletar essas lágrimas de unicórnio abrindo uma issue ou um pull request.

Existe um padrão de formato de changelog?

Infelizmente, não. Calma. Eu sei que você está buscando furiosamente aquele link do guia GNU de estilo de changelog, ou o arquivo "guideline" de dois paragráfos do GNU NEWS. O estilo GNU é um bom começo mas, infelizmente, é ingênuo. Não há nada de errado em ser ingênuo mas, quando as pessoas precisam de orientação, raramente ajuda. Especialmente quando existem muitas situações excepcionais para lidar.

Este projeto contém o que eu espero se tornar um melhor padrão de arquivo CHANGELOG para todos os projetos open source. Eu não acredito que o status quo seja bom o suficiente, e acho que, como uma comunidade, nós podemos encontrar novas convenções se tentarmos extrair boas práticas de projetos de software reais. Por favor, dê uma olhada e lembre-se de que discussões e sugestões de melhorias são bem-vindas!

Qual deve ser o nome do arquivo changelog?

Bom, se você não notou no exemplo acima, CHANGELOG.md é a melhor convenção até agora.

Alguns outros projetos também utilizam HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.

É uma bagunça. Todos esses nomes só dificultam encontrar o changelog.

Por que as pessoas não podem simplesmente utilizar git log?

Porque os logs do Git são cheios de ruído — por natureza. Eles não serviriam como um changelog adequado mesmo em um projeto hipotético executado por humanos perfeitos, que nunca erram uma letra, nunca esquecem de commitar arquivos, nunca cometem deslizes em uma refatoração. O propósito de um commit é documentar um passo atômico no processo pelo qual o código evolui de um estado a outro. O propósito de um changelog é documentar as diferenças relevantes entre esses estados.

A mesma diferença que existe entre bons comentários e o código em si existe entre o changelog e o commit log: um descreve o porquê, o outro descreve o como.

Podem os changelogs ser automaticamente interpretados?

É difícil, porque as pessoas seguem formatos e nomes de arquivos radicalmente diferentes.

Vandamme é uma gem criada pelo time Gemnasium que interpreta muitos (mas não todos) changelogs de projetos open source.

Por que você alterna entre as grafias "CHANGELOG" e "changelog"?

"CHANGELOG" é o nome do arquivo em si. É um pouco chamativo mas é uma convenção histórica seguida por muitos projetos open source. Outros exemplos similares de arquivo incluem README, LICENSE, e CONTRIBUTING.

O nome em letras maiúsculas (o que em sistemas operacionais antigos faziam estes arquivos ficarem no topo da lista) é utilizado para chamar atenção. Por conterem importantes metadados do projeto, changelogs são úteis a qualquer um que pretenda utilizar ou contribuir com o projeto, da maneira equivalente às badges de projetos open source.

Quando eu me refiro a "changelog", eu estou falando sobre a função desse arquivo: listar mudanças.

E sobre as publicações removidas?

Publicações removidas são versões que tiveram que ser removidas devido a um sério bug ou problema de segurança. Com frequência essas versões sequer aparecem em changelogs. Deveriam. É assim que você deve exibi-las:

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

A tag [YANKED]/[REMOVIDA] é chamativa por uma razão. É importante que as pessoas a notem. Além disso, já que é cercada por colchetes, é mais fácil detectá-la programaticamente.

Devemos alterar o changelog em alguma circunstância?

Claro. Sempre existem bons motivos para melhorar um changelog. Eu regularmente abro pull requests para adicionar versões faltantes em projetos open source com changelogs abandonados.

Também é possível que você perceba que se esqueceu de registrar mudanças importantes nas notas de uma versão. É obviamente importante que você atualize seu changelog nesse caso.

Como eu posso contribuir?

Este documento não é a verdade; é minha cuidadosa opinião, junto com as informações e exemplos que reuni. Embora eu tenha providenciado um CHANGELOG no repositório no GitHub, eu não criei de propósito uma lista clara de regras a serem seguidas (como o SemVer.org faz, por exemplo).

Fiz isso porque eu gostaria que nossa comunidade chegasse a um consenso. Eu acredito que a discussão é tão importante quanto o resultado final.

Então, por favor, entre em campo.

A última versão (1.1.0) ainda não está disponível em Português mas nesse momento você pode lê-la em inglês e ajudar em sua tradução.

Mantenha um Changelog

Não deixe seus amigos despejarem logs de commits no Changelog

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

## [Unreleased]

## [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

O que é um changelog?

Um changelog é um arquivo que contém uma lista selecionada, ordenada cronologicamente, de mudanças significativas para cada versão de um projeto.

Por que manter um changelog?

Para facilitar que usuários e contribuidores vejam precisamente quais mudanças significativas foram realizadas entre cada versão publicada de um projeto.

Quem precisa de um changelog?

Pessoas precisam. Seja consumidores ou desenvolvedores, os usuários finais de softwares são seres humanos que se preocupam com o que está no software. Quando o software muda, as pessoas querem saber por que e como.

Como fazer um bom changelog?

Princípios fundamentais

  • Changelogs são para humanos, não máquinas.
  • Deve haver uma entrada para cada versão.
  • Alterações do mesmo tipo devem ser agrupadas.
  • Versões e seções devem ser vinculáveis (com links).
  • A versão mais recente vem em primeiro lugar.
  • A data de lançamento de cada versão é exibida.
  • Mencione se você segue o versionamento semântico.

Tipos de mudanças

  • Added/Adicionado para novos recursos.
  • Changed/Modificado para alterações em recursos existentes.
  • Deprecated/Obsoleto para recursos que serão removidos nas próximas versões.
  • Removed/Removido para recursos removidos nesta versão.
  • Fixed/Corrigido para qualquer correção de bug.
  • Security/Segurança em caso de vulnerabilidades.

Como eu posso minimizar o esforço exigido para manter um changelog?

Mantenha sempre uma seção Unreleased/Não publicado no topo para manter o controle das novas mudanças.

Isso serve a dois propósitos:

  • As pessoas podem ver quais mudanças elas podem esperar em publicações futuras.
  • No momento da publicação, você apenas tem de mudar a seção Unreleased/Não publicado para o número de versão e adicionar uma nova seção Unreleased/Não publicado no topo.

Os changelogs podem ser ruins?

Sim. Aqui estão algumas maneiras pelas quais eles podem ser inúteis.

Usar um registro de alterações automático

Usar um registro de alterações automático é uma má ideia: eles estão cheios de bagunça. Coisas como solicitação de mesclagem, envio com títulos estranhos, alterações de documentação, etc.

O propósito de um commit é documentar a etapa na evolução do código fonte. Alguns projetos limpam os commits, outros não.

O propósito de uma entrada de changelog é documentar as diferenças notáveis, muitas vezes de múltiplos commits, para comunicar de forma clara os usuários.

Ignorando depreciações

Quando pessoas atualizam de uma versão para outra, deve ficar muitíssimo claro quando algo vai quebrar. Deve ser possível atualizar para uma versão com depreciações listadas, remova o que é obsoleto, depois atualize para a versão onde as depreciações se tornam remoções.

Se você não fizer mais nada, liste no seu changelog as depreciações, remoções e quaisquer mudanças que gerem falhas.

Datas confusas

Os formatos regionais de data variam em todo o mundo e muitas vezes é difícil encontrar um formato de data amigável que seja intuitivo para todos. A vantagem das datas formatadas como 2017-07-17 é que elas seguem a ordem da maior para a menor unidade de tempo: ano, mês e dia. Este formato também não se confunde de maneira ambígua com outros formatos de data, ao contrário de alguns formatos regionais que alteram a posição dos números do mês e dia. Esses motivos, e o fato de ser um formato de data suportado pela norma ISO são as razões para ele ser o formato de data recomendado para as entradas do changelog.

Perguntas frequentes

Existe um padrão para o formato do changelog?

Na verdade não. Existe o guia de estilo de changelog do GNU ou o "guia" de dois parágrafos do GNU NEWS. Ambos são inadequados ou insuficientes.

Este projeto pretende ser uma convenção de changelog melhor. Ele vem de observar e coletar as boas práticas em código aberto da comunidade.

Críticas saudáveis, discussões e sugestões de melhorias são bem-vindas.

Qual nome o arquivo changelog deve ter?

Chame-o CHANGELOG.md. Alguns projetos usam HISTORY, NEWS ou RELEASES.

Embora seja fácil pensar que o nome do seu arquivo changelog não importa muito, por que tornar mais difícil para seus usuários finais encontrarem consistentemente mudanças notáveis?

E sobre o GitHub Releases?

É uma grande iniciativa. Lançamentos podem ser usados para converter simples marcadores do git (por exemplo, um marcador chamado v1.0.0) em notas de versão ricas, adicionando manualmente notas de versão ou pode puxar as mensagens anotadas no marcador do git e transformá-las em notas.

GitHub Releases cria um changelog não portátil que só pode ser exibido para usuários no contexto do GitHub. É possível fazê-los parecer muito como o formato Keep a Changelog, mas tende a ser um pouco mais complicado.

A versão atual do GitHub Releases não é facilmente descoberta por usuários finais, ao contrário dos arquivos maiúsculos típicos (README, CONTRIBUTING, etc.). Outro problema de menor magnitude é que a interface atualmente não oferece links para confirmar alterações entre cada lançamento.

Os changelogs podem ser criados automaticamente?

É difícil, porque as pessoas seguem formatos e nomes de arquivos totalmente diferentes.

Vandamme é um gem Ruby criado pelo time Gemnasium e que analisa muitas (mas não todas) alterações de projetos de código aberto.

E o lançamentos removidos?

Lançamentos removidos são versões que foram retiradas por causa de problemas sérios ou falhas de segurança. Muitas vezes essas versões nem aparecem no histórico de alterações. Eles deviam. É assim que você deve exibi-los:

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

O marcador [REMOVIDO] está em caixa alta por uma razão. É importante que as pessoas o percebam. Já que está entre colchetes, também fica mais fácil de ser analisado programaticamente.

Você deve reescrever um changelog?

Claro. Sempre existe razão para melhorar um changelog. Eu regularmente solicito alterações em projetos de código livre que possuem changelogs não mantidos para adicionar lançamentos que não estão presentes nestes.

Também é possível que você descubra que você esqueceu de abordar uma mudança abrupta nas notas para uma versão. Obviamente é importante que você atualize seu changelog neste caso.

Como eu posso ajudar?

Esse documento não é uma verdade absoluta; É minha opinião cuidadosamente considerada, juntamente com informações e exemplos que eu reuni.

Isso porque o que eu quero é que nossa comunidade chegue a um consenso. Eu acredito que a discussão é tão importante quanto o resultado final.

Então, por favor contribua.

Discussões

Eu fui no The Changelog podcast para falar sobre por que os mantenedores e contribuidores devem se preocupar com os changelogs, e também sobre as motivações por trás desse projeto.

A última versão (1.1.0) ainda não está disponível em Português mas nesse momento você pode lê-la em inglês e ajudar em sua tradução.

Mantenha um Changelog

Não deixe seus amigos despejarem logs de commits no Changelog

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

## [Unreleased]

## [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

O que é um changelog?

Um changelog é um arquivo que contém uma lista selecionada, ordenada cronologicamente, de mudanças significativas para cada versão de um projeto.

Por que manter um changelog?

Para facilitar que usuários e contribuidores vejam precisamente quais mudanças significativas foram realizadas entre cada versão publicada de um projeto.

Quem precisa de um changelog?

Pessoas precisam. Seja consumidores ou desenvolvedores, os usuários finais de softwares são seres humanos que se preocupam com o que está no software. Quando o software muda, as pessoas querem saber por que e como.

Como fazer um bom changelog?

Princípios fundamentais

  • Changelogs são para humanos, não máquinas.
  • Deve haver uma entrada para cada versão.
  • Alterações do mesmo tipo devem ser agrupadas.
  • Versões e seções devem ser vinculáveis (com links).
  • A versão mais recente vem em primeiro lugar.
  • A data de lançamento de cada versão é exibida.
  • Mencione se você segue o versionamento semântico.

Tipos de mudanças

  • Added/Adicionado para novos recursos.
  • Changed/Modificado para alterações em recursos existentes.
  • Deprecated/Obsoleto para recursos que serão removidos nas próximas versões.
  • Removed/Removido para recursos removidos nesta versão.
  • Fixed/Corrigido para qualquer correção de bug.
  • Security/Segurança em caso de vulnerabilidades.

Como eu posso minimizar o esforço exigido para manter um changelog?

Mantenha sempre uma seção Unreleased/Não publicado no topo para manter o controle das novas mudanças.

Isso serve a dois propósitos:

  • As pessoas podem ver quais mudanças elas podem esperar em publicações futuras.
  • No momento da publicação, você apenas tem de mudar a seção Unreleased/Não publicado para o número de versão e adicionar uma nova seção Unreleased/Não publicado no topo.

Os changelogs podem ser ruins?

Sim. Aqui estão algumas maneiras pelas quais eles podem ser inúteis.

Usar um registro de alterações automático

Usar um registro de alterações automático é uma má ideia: eles estão cheios de bagunça. Coisas como solicitação de mesclagem, envio com títulos estranhos, alterações de documentação, etc.

O propósito de um commit é documentar a etapa na evolução do código fonte. Alguns projetos limpam os commits, outros não.

O propósito de uma entrada de changelog é documentar as diferenças notáveis, muitas vezes de múltiplos commits, para comunicar de forma clara os usuários.

Ignorando depreciações

Quando pessoas atualizam de uma versão para outra, deve ficar muitíssimo claro quando algo vai quebrar. Deve ser possível atualizar para uma versão com depreciações listadas, remova o que é obsoleto, depois atualize para a versão onde as depreciações se tornam remoções.

Se você não fizer mais nada, liste no seu changelog as depreciações, remoções e quaisquer mudanças que gerem falhas.

Datas confusas

Os formatos regionais de data variam em todo o mundo e muitas vezes é difícil encontrar um formato de data amigável que seja intuitivo para todos. A vantagem das datas formatadas como 2017-07-17 é que elas seguem a ordem da maior para a menor unidade de tempo: ano, mês e dia. Este formato também não se confunde de maneira ambígua com outros formatos de data, ao contrário de alguns formatos regionais que alteram a posição dos números do mês e dia. Esses motivos, e o fato de ser um formato de data suportado pela norma ISO são as razões para ele ser o formato de data recomendado para as entradas do changelog.

Perguntas frequentes

Existe um padrão para o formato do changelog?

Na verdade não. Existe o guia de estilo de changelog do GNU ou o "guia" de dois parágrafos do GNU NEWS. Ambos são inadequados ou insuficientes.

Este projeto pretende ser uma convenção de changelog melhor. Ele vem de observar e coletar as boas práticas em código aberto da comunidade.

Críticas saudáveis, discussões e sugestões de melhorias são bem-vindas.

Qual nome o arquivo changelog deve ter?

Chame-o CHANGELOG.md. Alguns projetos usam HISTORY, NEWS ou RELEASES.

Embora seja fácil pensar que o nome do seu arquivo changelog não importa muito, por que tornar mais difícil para seus usuários finais encontrarem consistentemente mudanças notáveis?

E sobre o GitHub Releases?

É uma grande iniciativa. Lançamentos podem ser usados para converter simples marcadores do git (por exemplo, um marcador chamado v1.0.0) em notas de versão ricas, adicionando manualmente notas de versão ou pode puxar as mensagens anotadas no marcador do git e transformá-las em notas.

GitHub Releases cria um changelog não portátil que só pode ser exibido para usuários no contexto do GitHub. É possível fazê-los parecer muito como o formato Keep a Changelog, mas tende a ser um pouco mais complicado.

A versão atual do GitHub Releases não é facilmente descoberta por usuários finais, ao contrário dos arquivos maiúsculos típicos (README, CONTRIBUTING, etc.). Outro problema de menor magnitude é que a interface atualmente não oferece links para confirmar alterações entre cada lançamento.

Os changelogs podem ser criados automaticamente?

É difícil, porque as pessoas seguem formatos e nomes de arquivos totalmente diferentes.

Vandamme é um gem Ruby criado pelo time Gemnasium e que analisa muitas (mas não todas) alterações de projetos de código aberto.

E o lançamentos removidos?

Lançamentos removidos são versões que foram retiradas por causa de problemas sérios ou falhas de segurança. Muitas vezes essas versões nem aparecem no histórico de alterações. Eles deviam. É assim que você deve exibi-los:

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

O marcador [REMOVIDO] está em caixa alta por uma razão. É importante que as pessoas o percebam. Já que está entre colchetes, também fica mais fácil de ser analisado programaticamente.

Você deve reescrever um changelog?

Claro. Sempre existe razão para melhorar um changelog. Eu regularmente solicito alterações em projetos de código livre que possuem changelogs não mantidos para adicionar lançamentos que não estão presentes nestes.

Também é possível que você descubra que você esqueceu de abordar uma mudança abrupta nas notas para uma versão. Obviamente é importante que você atualize seu changelog neste caso.

Como eu posso ajudar?

Esse documento não é uma verdade absoluta; É minha opinião cuidadosamente considerada, juntamente com informações e exemplos que eu reuni.

Isso porque o que eu quero é que nossa comunidade chegue a um consenso. Eu acredito que a discussão é tão importante quanto o resultado final.

Então, por favor contribua.

Discussões

Eu fui no The Changelog podcast para falar sobre por que os mantenedores e contribuidores devem se preocupar com os changelogs, e também sobre as motivações por trás desse projeto.

There is a newer version available: Pyccкий 1.1.0

Ведите CHANGELOG

Не позволяйте друзьям сливать логи гита в CHANGELOG™

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

## [Unreleased]

## [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?".

Для чего нужен лог изменений?

Чтобы пользователи и контрибьюторы могли с меньшими усилиями точно определить, какие значимые изменения были сделаны в каждом релизе (или версии) проекта.

Почему я вообще должен думать об этом?

Потому, что инструменты программирования делаются для людей. Если вам пофигу, зачем вы вообще занимаетесь программным обеспечением с открытым исходным кодом? У вас обязательно в голове должен быть центр «не пофигу» :)

Я беседовал с Адамом Стаковиаком и с Джеродом Санто в подкасте The Changelog (в тему название, правда?) о том почему авторам программного обеспечения с открытым исходным кодом и их коллегам должно быть не пофигу, и о моих мотивах в создании этого проекта. Послушайте, если у вас есть время (1:06).

Что должно быть в хорошем логе изменений?

Я рад, что вы спросили.

Хороший лог изменений придерживается этих приниципов:

Как минимизировать время, необходимое для ведения лога изменений?

Всегда ведите секцию Unreleased в начале файла, чтобы держать в ней не выпущенные изменения.

Это нужно для двух вещей:

Что заставляет плакать единорогов?

Хорошо… давайте разберёмся.

Существуют и другие. Помогите мне собрать слёзы единорогов, открыв тикет или пулл-реквест.

Существует стандарт формата лога изменений?

К сожалению, нет. Спокойней. Я знаю, что вы яростно бросились на поиски ссылки на GNU-руководства по стилю лога изменений, или на поиски файла «guideline» с парой параграфов в GNU NEWS. GNU-руководство по стилю неплохо для начала, но оно наивно. В наивности нет ничего плохого, но когда людям нужно руководство, она редко бывает полезна. Особенно, когда приходиться сталкиваться со множеством краевых случаев.

Этот проект содержит информацию, которая, я надеюсь, станет соглашением получше о ведении файлов CHANGELOG для всех проектов с открытым исходным кодом. Может ли сообщество учиться на своих ошибках, а не просто действовать согласно десяти записям, которые были написаны много лет назал, и, якобы, без одной ошибки? Хорошо. Поэтому, пожалуйста, посмотрите вокруг, и помните, что обсуждения и предложения по улучшению приветствуются!

Как можно назвать файл лога изменений?

Ну, если вы не не можете ответить на этот вопрос, глядя на пример выше, CHANGELOG.md пока наилучший вариант.

Некоторые проекты используют HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, и так далее.

Это непорядок. Все эти имена только усложняют поиск нужного файла.

Почему люди не могут использовать просто дифф команды git log?

Потому, что диффы логов по своей природе содержат слишком много «шума». С их помощью невозможно сделать подходящий лог изменений даже в гипотетическом проекте, который делается идеальными программистами, которые никогда не делают опечаток, никогда не забывают коммитить новые файлы, никогда не пропускают ни одну часть рефакторинга. Назначение коммита в том, чтобы задокументировать один атомарный шаг в процессе развития кода от одного состояния к другому. Назначение лога изменений – документировать значимые различия между этими состояниями.

Как отличаются хорошие комментарии к коду и сам код, также отличаются друг от друга и лог изменений с логом коммитов: первые отвечают на вопрос почему, а вторые на вопрос как.

Могут ли логи изменений быть автоматически распарсены?

Это сложно из-за того, что люди следуют сильно отличающимся форматам и соглашениям о именах файлов.

Гем для Руби Vandamme, который создали в команде Gemnasium, парсит многие (но не все) логи изменений проектов с открытым исходным кодом.

Почему вы пишите то «CHANGELOG», то «лог изменений»?

«CHANGELOG» – это имя файла. Оно несколько крикливо, но это историческое соглашение, которому следуют многие проекты с открытым исходным кодом. В качестве примеров подобных файлов можно привести README, LICENSE, и CONTRIBUTING.

Верхний регистр в имени файла (который в старых операционных системах заставляет эти файлы находиться наверху списков) используется для привлечения внимания. Так как в этих файлах содержится важная метаинформация о проекте, они могут быть полезны любому использующему или дорабатывющему проект, также как бейджи проектов с открытым исходным кодом.

Когда я упоминаю «лог изменений», я говорою о назначении этого файла: об учёте изменений.

Как насчёт yanked-релизов?

Yanked-релизы – это версии, которые изымаются из обращения из-за серьёзного бага или проблемы безопасности в них. Часто такие версии даже не упоминаются в логах изменений. А должны. И вот как вам следует их упоминать:

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

Тег [YANKED] такой «громкий» не просто так. Очень важно, чтобы люди его заметили. А из-за того, что он окружён скобками, его легче определить программно.

Стоит ли переписывать лог изменений?

Конечно. Всегда есть причины для улучшения лога изменений. Я регулярно открываю пулл-реквесты в проекты с открытым исходным кодом с неподдерживаемыми логами изменений для добавления недостающих релизов.

Также вы можете обнаружить что вы забыли адресовать критичное изменение в описании версии. В этом случае очевидно, что нужно обновить лог изменений.

Как я могу помочь?

Этот документ не истина в последней инстанции; это моё тщательно сформулированное мнение вместе с информацией и примерами, которые я собрал. Хотя я предоставил настоящий CHANGELOG из GitHub-репозитария, я специально избегал цели создать стандарт или чёткий список правил (как это делает, например, SemVer.org).

Я сделал это потому, что хочу, чтобы наше сообщество достигло консенсуса. Я верю, что дискуссия также важна, как и её результат.

Так что, пожалуйста, участвуйте.

There is a newer version available: Pyccкий 1.1.0

Ведите CHANGELOG

Не позволяйте друзьям сливать логи гита в CHANGELOG™

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

## [Unreleased]

## [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?".

Для чего нужен лог изменений?

Чтобы пользователи и контрибьюторы могли с меньшими усилиями точно определить, какие значимые изменения были сделаны в каждом релизе (или версии) проекта.

Почему я вообще должен думать об этом?

Потому, что инструменты программирования делаются для людей. Если вам пофигу, зачем вы вообще занимаетесь программным обеспечением с открытым исходным кодом? У вас обязательно в голове должен быть центр «не пофигу» :)

Я беседовал с Адамом Стаковиаком и с Джеродом Санто в подкасте The Changelog (в тему название, правда?) о том почему авторам программного обеспечения с открытым исходным кодом и их коллегам должно быть не пофигу, и о моих мотивах в создании этого проекта. Послушайте, если у вас есть время (1:06).

Что должно быть в хорошем логе изменений?

Я рад, что вы спросили.

Хороший лог изменений придерживается этих приниципов:

Как минимизировать время, необходимое для ведения лога изменений?

Всегда ведите секцию Unreleased в начале файла, чтобы держать в ней не выпущенные изменения.

Это нужно для двух вещей:

Что заставляет плакать единорогов?

Хорошо… давайте разберёмся.

Существуют и другие. Помогите мне собрать слёзы единорогов, открыв тикет или пулл-реквест.

Существует стандарт формата лога изменений?

К сожалению, нет. Спокойней. Я знаю, что вы яростно бросились на поиски ссылки на GNU-руководства по стилю лога изменений, или на поиски файла «guideline» с парой параграфов в GNU NEWS. GNU-руководство по стилю неплохо для начала, но оно наивно. В наивности нет ничего плохого, но когда людям нужно руководство, она редко бывает полезна. Особенно, когда приходиться сталкиваться со множеством краевых случаев.

Этот проект содержит информацию, которая, я надеюсь, станет соглашением получше о ведении файлов CHANGELOG для всех проектов с открытым исходным кодом. Может ли сообщество учиться на своих ошибках, а не просто действовать согласно десяти записям, которые были написаны много лет назал, и, якобы, без одной ошибки? Хорошо. Поэтому, пожалуйста, посмотрите вокруг, и помните, что обсуждения и предложения по улучшению приветствуются!

Как можно назвать файл лога изменений?

Ну, если вы не не можете ответить на этот вопрос, глядя на пример выше, CHANGELOG.md пока наилучший вариант.

Некоторые проекты используют HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, и так далее.

Это непорядок. Все эти имена только усложняют поиск нужного файла.

Почему люди не могут использовать просто дифф команды git log?

Потому, что диффы логов по своей природе содержат слишком много «шума». С их помощью невозможно сделать подходящий лог изменений даже в гипотетическом проекте, который делается идеальными программистами, которые никогда не делают опечаток, никогда не забывают коммитить новые файлы, никогда не пропускают ни одну часть рефакторинга. Назначение коммита в том, чтобы задокументировать один атомарный шаг в процессе развития кода от одного состояния к другому. Назначение лога изменений – документировать значимые различия между этими состояниями.

Как отличаются хорошие комментарии к коду и сам код, также отличаются друг от друга и лог изменений с логом коммитов: первые отвечают на вопрос почему, а вторые на вопрос как.

Могут ли логи изменений быть автоматически распарсены?

Это сложно из-за того, что люди следуют сильно отличающимся форматам и соглашениям о именах файлов.

Гем для Руби Vandamme, который создали в команде Gemnasium, парсит многие (но не все) логи изменений проектов с открытым исходным кодом.

Почему вы пишите то «CHANGELOG», то «лог изменений»?

«CHANGELOG» – это имя файла. Оно несколько крикливо, но это историческое соглашение, которому следуют многие проекты с открытым исходным кодом. В качестве примеров подобных файлов можно привести README, LICENSE, и CONTRIBUTING.

Верхний регистр в имени файла (который в старых операционных системах заставляет эти файлы находиться наверху списков) используется для привлечения внимания. Так как в этих файлах содержится важная метаинформация о проекте, они могут быть полезны любому использующему или дорабатывющему проект, также как бейджи проектов с открытым исходным кодом.

Когда я упоминаю «лог изменений», я говорою о назначении этого файла: об учёте изменений.

Как насчёт yanked-релизов?

Yanked-релизы – это версии, которые изымаются из обращения из-за серьёзного бага или проблемы безопасности в них. Часто такие версии даже не упоминаются в логах изменений. А должны. И вот как вам следует их упоминать:

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

Тег [YANKED] такой «громкий» не просто так. Очень важно, чтобы люди его заметили. А из-за того, что он окружён скобками, его легче определить программно.

Стоит ли переписывать лог изменений?

Конечно. Всегда есть причины для улучшения лога изменений. Я регулярно открываю пулл-реквесты в проекты с открытым исходным кодом с неподдерживаемыми логами изменений для добавления недостающих релизов.

Также вы можете обнаружить что вы забыли адресовать критичное изменение в описании версии. В этом случае очевидно, что нужно обновить лог изменений.

Как я могу помочь?

Этот документ не истина в последней инстанции; это моё тщательно сформулированное мнение вместе с информацией и примерами, которые я собрал. Хотя я предоставил настоящий CHANGELOG из GitHub-репозитария, я специально избегал цели создать стандарт или чёткий список правил (как это делает, например, SemVer.org).

Я сделал это потому, что хочу, чтобы наше сообщество достигло консенсуса. Я верю, что дискуссия также важна, как и её результат.

Так что, пожалуйста, участвуйте.

There is a newer version available: Pyccкий 1.1.0

Ведите changelog

Не позволяйте своим друзьям сливать логи Git в changelog’и.

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

## [Unreleased]

## [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

Что такое лог изменений?

Лог изменений — это файл, который содержит поддерживаемый, хронологически упорядоченный список значимых изменений для каждой версии проекта.

Зачем вести лог изменений?

Чтобы пользователям и контрибуторам было проще в точности понять, какие значимые изменения были внесены в каждый выпуск (или версию) проекта.

Кому нужен лог изменений?

Людям. Конечные пользователи программного обеспечения, будь то клиенты или разработчики, — это человеческие существа, которым небезразлично, с чем они работают. Когда программное обеспечение изменяется, люди хотят знать, что и почему изменилось.

Как мне сделать хороший лог изменений?

Руководящие принципы

  • Лог изменений — для людей, а не для машин.
  • Для каждой версии без исключения следует создать отдельный раздел.
  • Однотипные изменения следует группировать.
  • Следует предусмотреть возможность поставить ссылку на любую версию или раздел.
  • Последняя версия должна идти в начале файла.
  • Указаны даты выпуска каждой версии.
  • Уточните, следуете ли вы принципам семантического версионирования.

Типы изменений

  • Добавлено — для новых функций.
  • Изменено — для изменений в существующей функциональности.
  • Устарело — для функций, которые скоро будут удалены.
  • Удалено — для удалённых на данный момент функций.
  • Исправлено — для любых исправлений багов.
  • Безопасность — на случай уязвимостей.

Как мне тратить меньше усилий на ведение лога изменений?

Держите в начале файла раздел Новое, позволяющий отслеживать предстоящие изменения.

Это служит достижению двух целей:

  • люди смогут видеть, каких изменений им можно ожидать в предстоящих выпусках;
  • в момент релиза вы можете переместить изменения из раздела Новое в раздел нового выпуска.

Бывают ли плохие логи изменений?

Да. Вот несколько причин, по которым они могут оказаться совершенно бесполезными.

Diff’ы лога коммитов

Использование diff’ов лога коммитов в качестве лога изменений — это плохая идея: они полны информационного шума от слияния коммитов, от коммитов с непонятными заглавиями, от изменений, вносимых в документацию, и т. п.

Назначение коммита в том, чтобы задокументировать шаг в эволюции исходного кода. В некоторых проектах следят за историей коммитов, в некоторых — нет.

Назначение же раздела в логе изменений — задокументировать заслуживающие внимания различия (зачастую привнесённые несколькими коммитами), чтобы внятно сообщить конечным пользователям об этих различиях.

Игнорирование устаревших функций

Когда люди переходят с одной версии продукта на другую, им должно быть до боли ясно, в какой именно момент что-то сломается. Следует предусмотреть возможность перейти к версии, в которой перечислены устаревшие функции, удалить то, что устарело, а затем перейти к версии, из которой эти устаревшие функции удалены.

Перечисляйте в логе изменений устаревшие и удалённые функции, а также любые критические изменения, даже если не перечисляете ничего другого.

Даты, сбивающие с толку

Региональные форматы дат различаются по всему миру, и зачастую трудно найти удобный для человека формат, который был бы интуитивно понятен каждому. Преимущество дат в форматах наподобие 2017-07-17 заключается в том, что элементы в них следуют в порядке от более крупной единицы измерения к более мелкой: год, месяц и день. К тому же, в отличие от некоторых региональных форматов, в которых изменено положение чисел, обозначающих день и месяц, этот формат не пересекается с другим и не вызывает неоднозначных толкований. Исходя из этих причин и того факта, что этот формат соответствует стандарту ISO, именно он рекомендован для записей в логе изменений.

Часто задаваемые вопросы

Существует ли стандартный формат для логов изменений?

На самом деле, нет. Есть стилистический путеводитель по логам изменений от GNU, есть «руководство» длиной в два абзаца по файлам GNU NEWS. Оба или неадекватны, или недостаточно полны.

Этот проект нацелен на то, чтобы стать улучшенной версией соглашения о формате логов изменений. Проект опирается на отслеживание и накопление передового опыта сообщества пользователей открытого исходного кода.

Здоровая критика, дискуссии и предложения по улучшению приветствуются.

Как назвать файл лога изменений?

Назовите его CHANGELOG.md. Некоторые проекты используют HISTORY, NEWS или RELEASES.

Хотя легко подумать, что имя файла лога изменений не имеет большого значения, зачем усложнять вашим конечным пользователям поиск места, в котором описаны все значимые изменения?

Что насчёт функции «Релизы» на GitHub’е?

Это отличная инициатива. Релизы можно использовать для превращения простых тегов Git (например, тега, названного v1.0.0) в подробные примечания к выпускам, вручную добавляя эти примечания, или же можно извлечь сообщения из аннотированных тегов Git и превратить их в примечания.

Релизы на GitHub’е создают непортируемый лог изменений, который может быть показан пользователям только на самом GitHub’е. Имеется возможность вести такой лог в формате, очень похожем на формат проекта Keep a Changelog, но это, как правило, требует большей вовлечённости в процесс.

Также возможно, что конечным пользователям не всегда легко обнаружить текущую версию GitHub Releases, в отличие от обычных файлов с именами в верхнем регистре (README, CONTRIBUTING и т. д.). Другая небольшая проблема заключается в том, что в настоящее время интерфейс не предлагает ссылок на логи коммитов, выполненных между релизами.

Могут ли логи изменений быть автоматически распарсены?

Это сложно, потому что люди соблюдают сильно различающиеся форматы и используют разные имена файлов.

Vandamme — это gem для Ruby, созданный командой Gemnasium и способный парсить логи изменений во многих (но не всех) проектах с открытым исходным кодом.

Что насчёт yanked-выпусков?

Yanked-выпуски — это версии, которые пришлось изъять из обращения из-за серьёзного бага или проблем с безопасностью. Часто такие версии даже не обозначают в логах изменений. А следовало бы. И вот как вам следует их обозначать:

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

Тег [YANKED] так бросается в глаза неспроста. Очень важно, чтобы люди его заметили. Поскольку он заключён в квадратные скобки, его также проще распарсить программно.

Следует ли вам когда-либо переписывать лог изменений?

Конечно. Всегда есть веские причины для усовершенствования лога изменений. Я регулярно подаю pull request’ы на добавление недостающих выпусков в проекты с открытым исходным кодом, которые оставили свои логи изменений без сопровождения.

К тому же, возможно, вы обнаружите, что в примечании к версии забыли рассмотреть одно из критичных изменений. Важность того, что в этом случае вы обновите ваш лог изменений, очевидна.

Как я могу помочь вашему проекту?

Этот документ — не истина в последней инстанции; это моё тщательно обдуманное мнение наряду с информацией и примерами, которые я собрал.

Дело в том, что я хочу, чтобы наше сообщество пришло к согласованному мнению. Я верю, что дискуссия так же важна, как и конечный результат.

Так что, пожалуйста, участвуйте.

Обсуждения

Я приходил на подкаст The Changelog, чтобы поговорить о том, почему maintainer’ам (персоналу сопровождения) и контрибуторам следует озаботиться ведением логов изменений, а также о мотивах, стоящих за этим проектом.

There is a newer version available: Pyccкий 1.1.0

Ведите changelog

Не позволяйте своим друзьям сливать логи Git в changelog’и.

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

## [Unreleased]

## [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

Что такое лог изменений?

Лог изменений — это файл, который содержит поддерживаемый, хронологически упорядоченный список значимых изменений для каждой версии проекта.

Зачем вести лог изменений?

Чтобы пользователям и контрибуторам было проще в точности понять, какие значимые изменения были внесены в каждый выпуск (или версию) проекта.

Кому нужен лог изменений?

Людям. Конечные пользователи программного обеспечения, будь то клиенты или разработчики, — это человеческие существа, которым небезразлично, с чем они работают. Когда программное обеспечение изменяется, люди хотят знать, что и почему изменилось.

Как мне сделать хороший лог изменений?

Руководящие принципы

  • Лог изменений — для людей, а не для машин.
  • Для каждой версии без исключения следует создать отдельный раздел.
  • Однотипные изменения следует группировать.
  • Следует предусмотреть возможность поставить ссылку на любую версию или раздел.
  • Последняя версия должна идти в начале файла.
  • Указаны даты выпуска каждой версии.
  • Уточните, следуете ли вы принципам семантического версионирования.

Типы изменений

  • Добавлено — для новых функций.
  • Изменено — для изменений в существующей функциональности.
  • Устарело — для функций, которые скоро будут удалены.
  • Удалено — для удалённых на данный момент функций.
  • Исправлено — для любых исправлений багов.
  • Безопасность — на случай уязвимостей.

Как мне тратить меньше усилий на ведение лога изменений?

Держите в начале файла раздел Новое, позволяющий отслеживать предстоящие изменения.

Это служит достижению двух целей:

  • люди смогут видеть, каких изменений им можно ожидать в предстоящих выпусках;
  • в момент релиза вы можете переместить изменения из раздела Новое в раздел нового выпуска.

Бывают ли плохие логи изменений?

Да. Вот несколько причин, по которым они могут оказаться совершенно бесполезными.

Diff’ы лога коммитов

Использование diff’ов лога коммитов в качестве лога изменений — это плохая идея: они полны информационного шума от слияния коммитов, от коммитов с непонятными заглавиями, от изменений, вносимых в документацию, и т. п.

Назначение коммита в том, чтобы задокументировать шаг в эволюции исходного кода. В некоторых проектах следят за историей коммитов, в некоторых — нет.

Назначение же раздела в логе изменений — задокументировать заслуживающие внимания различия (зачастую привнесённые несколькими коммитами), чтобы внятно сообщить конечным пользователям об этих различиях.

Игнорирование устаревших функций

Когда люди переходят с одной версии продукта на другую, им должно быть до боли ясно, в какой именно момент что-то сломается. Следует предусмотреть возможность перейти к версии, в которой перечислены устаревшие функции, удалить то, что устарело, а затем перейти к версии, из которой эти устаревшие функции удалены.

Перечисляйте в логе изменений устаревшие и удалённые функции, а также любые критические изменения, даже если не перечисляете ничего другого.

Даты, сбивающие с толку

Региональные форматы дат различаются по всему миру, и зачастую трудно найти удобный для человека формат, который был бы интуитивно понятен каждому. Преимущество дат в форматах наподобие 2017-07-17 заключается в том, что элементы в них следуют в порядке от более крупной единицы измерения к более мелкой: год, месяц и день. К тому же, в отличие от некоторых региональных форматов, в которых изменено положение чисел, обозначающих день и месяц, этот формат не пересекается с другим и не вызывает неоднозначных толкований. Исходя из этих причин и того факта, что этот формат соответствует стандарту ISO, именно он рекомендован для записей в логе изменений.

Часто задаваемые вопросы

Существует ли стандартный формат для логов изменений?

На самом деле, нет. Есть стилистический путеводитель по логам изменений от GNU, есть «руководство» длиной в два абзаца по файлам GNU NEWS. Оба или неадекватны, или недостаточно полны.

Этот проект нацелен на то, чтобы стать улучшенной версией соглашения о формате логов изменений. Проект опирается на отслеживание и накопление передового опыта сообщества пользователей открытого исходного кода.

Здоровая критика, дискуссии и предложения по улучшению приветствуются.

Как назвать файл лога изменений?

Назовите его CHANGELOG.md. Некоторые проекты используют HISTORY, NEWS или RELEASES.

Хотя легко подумать, что имя файла лога изменений не имеет большого значения, зачем усложнять вашим конечным пользователям поиск места, в котором описаны все значимые изменения?

Что насчёт функции «Релизы» на GitHub’е?

Это отличная инициатива. Релизы можно использовать для превращения простых тегов Git (например, тега, названного v1.0.0) в подробные примечания к выпускам, вручную добавляя эти примечания, или же можно извлечь сообщения из аннотированных тегов Git и превратить их в примечания.

Релизы на GitHub’е создают непортируемый лог изменений, который может быть показан пользователям только на самом GitHub’е. Имеется возможность вести такой лог в формате, очень похожем на формат проекта Keep a Changelog, но это, как правило, требует большей вовлечённости в процесс.

Также возможно, что конечным пользователям не всегда легко обнаружить текущую версию GitHub Releases, в отличие от обычных файлов с именами в верхнем регистре (README, CONTRIBUTING и т. д.). Другая небольшая проблема заключается в том, что в настоящее время интерфейс не предлагает ссылок на логи коммитов, выполненных между релизами.

Могут ли логи изменений быть автоматически распарсены?

Это сложно, потому что люди соблюдают сильно различающиеся форматы и используют разные имена файлов.

Vandamme — это gem для Ruby, созданный командой Gemnasium и способный парсить логи изменений во многих (но не всех) проектах с открытым исходным кодом.

Что насчёт yanked-выпусков?

Yanked-выпуски — это версии, которые пришлось изъять из обращения из-за серьёзного бага или проблем с безопасностью. Часто такие версии даже не обозначают в логах изменений. А следовало бы. И вот как вам следует их обозначать:

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

Тег [YANKED] так бросается в глаза неспроста. Очень важно, чтобы люди его заметили. Поскольку он заключён в квадратные скобки, его также проще распарсить программно.

Следует ли вам когда-либо переписывать лог изменений?

Конечно. Всегда есть веские причины для усовершенствования лога изменений. Я регулярно подаю pull request’ы на добавление недостающих выпусков в проекты с открытым исходным кодом, которые оставили свои логи изменений без сопровождения.

К тому же, возможно, вы обнаружите, что в примечании к версии забыли рассмотреть одно из критичных изменений. Важность того, что в этом случае вы обновите ваш лог изменений, очевидна.

Как я могу помочь вашему проекту?

Этот документ — не истина в последней инстанции; это моё тщательно обдуманное мнение наряду с информацией и примерами, которые я собрал.

Дело в том, что я хочу, чтобы наше сообщество пришло к согласованному мнению. Я верю, что дискуссия так же важна, как и конечный результат.

Так что, пожалуйста, участвуйте.

Обсуждения

Я приходил на подкаст The Changelog, чтобы поговорить о том, почему maintainer’ам (персоналу сопровождения) и контрибуторам следует озаботиться ведением логов изменений, а также о мотивах, стоящих за этим проектом.

Ведите changelog

Не позволяйте своим друзьям сливать логи Git в changelog’и.

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

## [Unreleased]

## [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

Что такое лог изменений?

Лог изменений — это файл, который содержит поддерживаемый, хронологически упорядоченный список значимых изменений для каждой версии проекта.

Зачем вести лог изменений?

Чтобы пользователям и контрибуторам было проще в точности понять, какие значимые изменения были внесены в каждый выпуск (или версию) проекта.

Кому нужен лог изменений?

Людям. Конечные пользователи программного обеспечения, будь то клиенты или разработчики, — это человеческие существа, которым небезразлично, с чем они работают. Когда программное обеспечение изменяется, люди хотят знать, что и почему изменилось.

Как мне сделать хороший лог изменений?

Руководящие принципы

  • Лог изменений — для людей, а не для машин.
  • Для каждой версии без исключения следует создать отдельный раздел.
  • Однотипные изменения следует группировать.
  • Следует предусмотреть возможность поставить ссылку на любую версию или раздел.
  • Последняя версия должна идти в начале файла.
  • Указаны даты выпуска каждой версии.
  • Уточните, следуете ли вы принципам семантического версионирования.

Типы изменений

  • Добавлено — для новых функций.
  • Изменено — для изменений в существующей функциональности.
  • Устарело — для функций, которые скоро будут удалены.
  • Удалено — для удалённых на данный момент функций.
  • Исправлено — для любых исправлений багов.
  • Безопасность — на случай уязвимостей.

Как мне тратить меньше усилий на ведение лога изменений?

Держите в начале файла раздел Новое, позволяющий отслеживать предстоящие изменения.

Это служит достижению двух целей:

  • люди смогут видеть, каких изменений им можно ожидать в предстоящих выпусках;
  • в момент релиза вы можете переместить изменения из раздела Новое в раздел нового выпуска.

Бывают ли плохие логи изменений?

Да. Вот несколько причин, по которым они могут оказаться совершенно бесполезными.

Diff’ы лога коммитов

Использование diff’ов лога коммитов в качестве лога изменений — это плохая идея: они полны информационного шума от слияния коммитов, от коммитов с непонятными заглавиями, от изменений, вносимых в документацию, и т. п.

Назначение коммита в том, чтобы задокументировать шаг в эволюции исходного кода. В некоторых проектах следят за историей коммитов, в некоторых — нет.

Назначение же раздела в логе изменений — задокументировать заслуживающие внимания различия (зачастую привнесённые несколькими коммитами), чтобы внятно сообщить конечным пользователям об этих различиях.

Игнорирование устаревших функций

Когда люди переходят с одной версии продукта на другую, им должно быть до боли ясно, в какой именно момент что-то сломается. Следует предусмотреть возможность перейти к версии, в которой перечислены устаревшие функции, удалить то, что устарело, а затем перейти к версии, из которой эти устаревшие функции удалены.

Перечисляйте в логе изменений устаревшие и удалённые функции, а также любые критические изменения, даже если не перечисляете ничего другого.

Даты, сбивающие с толку

Региональные форматы дат различаются по всему миру, и зачастую трудно найти удобный для человека формат, который был бы интуитивно понятен каждому. Преимущество дат в форматах наподобие 2017-07-17 заключается в том, что элементы в них следуют в порядке от более крупной единицы измерения к более мелкой: год, месяц и день. К тому же, в отличие от некоторых региональных форматов, в которых изменено положение чисел, обозначающих день и месяц, этот формат не пересекается с другим и не вызывает неоднозначных толкований. Исходя из этих причин и того факта, что этот формат соответствует стандарту ISO, именно он рекомендован для записей в логе изменений.

Непоследовательное освещение изменений

Лог, в котором упомянуты лишь некоторые изменения, может быть опасен в той же мере, что и отсутствие лога изменений. Несмотря на то, что многие изменения могут быть нерелевантными (например, удаление одного пробела не во всех случаях может нуждаться в регистрации), в логе следует упоминать о любых важных изменениях. При непоследовательном освещении изменений ваши пользователи будут заблуждаться, считая лог изменений единственным источником истины. А ведь таким он и должен быть. С большой силой приходит большая ответственность — наличие хорошего лога изменений означает наличие последовательно обновляемого лога изменений.

Часто задаваемые вопросы

Существует ли стандартный формат для логов изменений?

На самом деле, нет. Есть стилистический путеводитель по логам изменений от GNU, есть «руководство» длиной в два абзаца по файлам GNU NEWS. Оба или неадекватны, или недостаточно полны.

Этот проект нацелен на то, чтобы стать улучшенной версией соглашения о формате логов изменений. Проект опирается на отслеживание и накопление передового опыта сообщества пользователей открытого исходного кода.

Здоровая критика, дискуссии и предложения по улучшению приветствуются.

Как назвать файл лога изменений?

Назовите его CHANGELOG.md. Некоторые проекты используют HISTORY, NEWS или RELEASES.

Хотя легко подумать, что имя файла лога изменений не имеет большого значения, зачем усложнять вашим конечным пользователям поиск места, в котором описаны все значимые изменения?

Что насчёт функции «Релизы» на GitHub’е?

Это отличная инициатива. Релизы можно использовать для превращения простых тегов Git (например, тега, названного v1.0.0) в подробные примечания к выпускам, вручную добавляя эти примечания, или же можно извлечь сообщения из аннотированных тегов Git и превратить их в примечания.

Релизы на GitHub’е создают непортируемый лог изменений, который может быть показан пользователям только на самом GitHub’е. Имеется возможность вести такой лог в формате, очень похожем на формат проекта Keep a Changelog, но это, как правило, требует большей вовлечённости в процесс.

Также возможно, что конечным пользователям не всегда легко обнаружить текущую версию GitHub Releases, в отличие от обычных файлов с именами в верхнем регистре (README, CONTRIBUTING и т. д.). Другая небольшая проблема заключается в том, что в настоящее время интерфейс не предлагает ссылок на логи коммитов, выполненных между релизами.

Могут ли логи изменений быть автоматически распарсены?

Это сложно, потому что люди соблюдают сильно различающиеся форматы и используют разные имена файлов.

Vandamme — это gem для Ruby, созданный командой Gemnasium и способный парсить логи изменений во многих (но не всех) проектах с открытым исходным кодом.

Что насчёт yanked-выпусков?

Yanked-выпуски — это версии, которые пришлось изъять из обращения из-за серьёзного бага или проблем с безопасностью. Часто такие версии даже не обозначают в логах изменений. А следовало бы. И вот как вам следует их обозначать:

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

Тег [YANKED] так бросается в глаза неспроста. Очень важно, чтобы люди его заметили. Поскольку он заключён в квадратные скобки, его также проще распарсить программно.

Следует ли вам когда-либо переписывать лог изменений?

Конечно. Всегда есть веские причины для усовершенствования лога изменений. Я регулярно подаю pull request’ы на добавление недостающих выпусков в проекты с открытым исходным кодом, которые оставили свои логи изменений без сопровождения.

К тому же, возможно, вы обнаружите, что в примечании к версии забыли рассмотреть одно из критичных изменений. Важность того, что в этом случае вы обновите ваш лог изменений, очевидна.

Как я могу помочь вашему проекту?

Этот документ — не истина в последней инстанции; это моё тщательно обдуманное мнение наряду с информацией и примерами, которые я собрал.

Дело в том, что я хочу, чтобы наше сообщество пришло к согласованному мнению. Я верю, что дискуссия так же важна, как и конечный результат.

Так что, пожалуйста, участвуйте.

Обсуждения

Я приходил на подкаст The Changelog, чтобы поговорить о том, почему maintainer’ам (персоналу сопровождения) и контрибуторам следует озаботиться ведением логов изменений, а также о мотивах, стоящих за этим проектом.

Ведите changelog

Не позволяйте своим друзьям сливать логи Git в changelog’и.

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

## [Unreleased]

## [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

Что такое лог изменений?

Лог изменений — это файл, который содержит поддерживаемый, хронологически упорядоченный список значимых изменений для каждой версии проекта.

Зачем вести лог изменений?

Чтобы пользователям и контрибуторам было проще в точности понять, какие значимые изменения были внесены в каждый выпуск (или версию) проекта.

Кому нужен лог изменений?

Людям. Конечные пользователи программного обеспечения, будь то клиенты или разработчики, — это человеческие существа, которым небезразлично, с чем они работают. Когда программное обеспечение изменяется, люди хотят знать, что и почему изменилось.

Как мне сделать хороший лог изменений?

Руководящие принципы

  • Лог изменений — для людей, а не для машин.
  • Для каждой версии без исключения следует создать отдельный раздел.
  • Однотипные изменения следует группировать.
  • Следует предусмотреть возможность поставить ссылку на любую версию или раздел.
  • Последняя версия должна идти в начале файла.
  • Указаны даты выпуска каждой версии.
  • Уточните, следуете ли вы принципам семантического версионирования.

Типы изменений

  • Добавлено — для новых функций.
  • Изменено — для изменений в существующей функциональности.
  • Устарело — для функций, которые скоро будут удалены.
  • Удалено — для удалённых на данный момент функций.
  • Исправлено — для любых исправлений багов.
  • Безопасность — на случай уязвимостей.

Как мне тратить меньше усилий на ведение лога изменений?

Держите в начале файла раздел Новое, позволяющий отслеживать предстоящие изменения.

Это служит достижению двух целей:

  • люди смогут видеть, каких изменений им можно ожидать в предстоящих выпусках;
  • в момент релиза вы можете переместить изменения из раздела Новое в раздел нового выпуска.

Бывают ли плохие логи изменений?

Да. Вот несколько причин, по которым они могут оказаться совершенно бесполезными.

Diff’ы лога коммитов

Использование diff’ов лога коммитов в качестве лога изменений — это плохая идея: они полны информационного шума от слияния коммитов, от коммитов с непонятными заглавиями, от изменений, вносимых в документацию, и т. п.

Назначение коммита в том, чтобы задокументировать шаг в эволюции исходного кода. В некоторых проектах следят за историей коммитов, в некоторых — нет.

Назначение же раздела в логе изменений — задокументировать заслуживающие внимания различия (зачастую привнесённые несколькими коммитами), чтобы внятно сообщить конечным пользователям об этих различиях.

Игнорирование устаревших функций

Когда люди переходят с одной версии продукта на другую, им должно быть до боли ясно, в какой именно момент что-то сломается. Следует предусмотреть возможность перейти к версии, в которой перечислены устаревшие функции, удалить то, что устарело, а затем перейти к версии, из которой эти устаревшие функции удалены.

Перечисляйте в логе изменений устаревшие и удалённые функции, а также любые критические изменения, даже если не перечисляете ничего другого.

Даты, сбивающие с толку

Региональные форматы дат различаются по всему миру, и зачастую трудно найти удобный для человека формат, который был бы интуитивно понятен каждому. Преимущество дат в форматах наподобие 2017-07-17 заключается в том, что элементы в них следуют в порядке от более крупной единицы измерения к более мелкой: год, месяц и день. К тому же, в отличие от некоторых региональных форматов, в которых изменено положение чисел, обозначающих день и месяц, этот формат не пересекается с другим и не вызывает неоднозначных толкований. Исходя из этих причин и того факта, что этот формат соответствует стандарту ISO, именно он рекомендован для записей в логе изменений.

Непоследовательное освещение изменений

Лог, в котором упомянуты лишь некоторые изменения, может быть опасен в той же мере, что и отсутствие лога изменений. Несмотря на то, что многие изменения могут быть нерелевантными (например, удаление одного пробела не во всех случаях может нуждаться в регистрации), в логе следует упоминать о любых важных изменениях. При непоследовательном освещении изменений ваши пользователи будут заблуждаться, считая лог изменений единственным источником истины. А ведь таким он и должен быть. С большой силой приходит большая ответственность — наличие хорошего лога изменений означает наличие последовательно обновляемого лога изменений.

Часто задаваемые вопросы

Существует ли стандартный формат для логов изменений?

На самом деле, нет. Есть стилистический путеводитель по логам изменений от GNU, есть «руководство» длиной в два абзаца по файлам GNU NEWS. Оба или неадекватны, или недостаточно полны.

Этот проект нацелен на то, чтобы стать улучшенной версией соглашения о формате логов изменений. Проект опирается на отслеживание и накопление передового опыта сообщества пользователей открытого исходного кода.

Здоровая критика, дискуссии и предложения по улучшению приветствуются.

Как назвать файл лога изменений?

Назовите его CHANGELOG.md. Некоторые проекты используют HISTORY, NEWS или RELEASES.

Хотя легко подумать, что имя файла лога изменений не имеет большого значения, зачем усложнять вашим конечным пользователям поиск места, в котором описаны все значимые изменения?

Что насчёт функции «Релизы» на GitHub’е?

Это отличная инициатива. Релизы можно использовать для превращения простых тегов Git (например, тега, названного v1.0.0) в подробные примечания к выпускам, вручную добавляя эти примечания, или же можно извлечь сообщения из аннотированных тегов Git и превратить их в примечания.

Релизы на GitHub’е создают непортируемый лог изменений, который может быть показан пользователям только на самом GitHub’е. Имеется возможность вести такой лог в формате, очень похожем на формат проекта Keep a Changelog, но это, как правило, требует большей вовлечённости в процесс.

Также возможно, что конечным пользователям не всегда легко обнаружить текущую версию GitHub Releases, в отличие от обычных файлов с именами в верхнем регистре (README, CONTRIBUTING и т. д.). Другая небольшая проблема заключается в том, что в настоящее время интерфейс не предлагает ссылок на логи коммитов, выполненных между релизами.

Могут ли логи изменений быть автоматически распарсены?

Это сложно, потому что люди соблюдают сильно различающиеся форматы и используют разные имена файлов.

Vandamme — это gem для Ruby, созданный командой Gemnasium и способный парсить логи изменений во многих (но не всех) проектах с открытым исходным кодом.

Что насчёт yanked-выпусков?

Yanked-выпуски — это версии, которые пришлось изъять из обращения из-за серьёзного бага или проблем с безопасностью. Часто такие версии даже не обозначают в логах изменений. А следовало бы. И вот как вам следует их обозначать:

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

Тег [YANKED] так бросается в глаза неспроста. Очень важно, чтобы люди его заметили. Поскольку он заключён в квадратные скобки, его также проще распарсить программно.

Следует ли вам когда-либо переписывать лог изменений?

Конечно. Всегда есть веские причины для усовершенствования лога изменений. Я регулярно подаю pull request’ы на добавление недостающих выпусков в проекты с открытым исходным кодом, которые оставили свои логи изменений без сопровождения.

К тому же, возможно, вы обнаружите, что в примечании к версии забыли рассмотреть одно из критичных изменений. Важность того, что в этом случае вы обновите ваш лог изменений, очевидна.

Как я могу помочь вашему проекту?

Этот документ — не истина в последней инстанции; это моё тщательно обдуманное мнение наряду с информацией и примерами, которые я собрал.

Дело в том, что я хочу, чтобы наше сообщество пришло к согласованному мнению. Я верю, что дискуссия так же важна, как и конечный результат.

Так что, пожалуйста, участвуйте.

Обсуждения

Я приходил на подкаст The Changelog, чтобы поговорить о том, почему maintainer’ам (персоналу сопровождения) и контрибуторам следует озаботиться ведением логов изменений, а также о мотивах, стоящих за этим проектом.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Udržuj changelog

Nenechaj kamarátov sypať git logy do changelogov.

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

## [Unreleased]

## [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

Čo je to changelog?

Changelog je súbor obsahujúci organizovaný, chronologicky usporiadaný zoznam významných zmien pre každú verziu daného projektu.

Prečo udržiavať changelog?

Aby používatelia a prispievatelia presne vedeli, aké podstatné zmeny sa udiali medzi jednotlivými vydaniami (alebo verziami) projektu.

Kto potrebuje changelog?

Ľudia. Či už konzumenti, alebo vývojári, koncoví používatelia softvéru sú ľudské bytosti, ktorým záleží na tom, čo softvér obsahuje. Keď sa softvér zmení, ľudia chcú vedieť prečo a ako.

Ako vytvorím dobrý changelog?

Hlavné princípy

  • Changelogy sú pre ľudí, nie stroje.
  • Changelog by mal obsahovať záznam pre každú jednu verziu.
  • Rovnaké typy zmien by mali byť zoskupené.
  • Mala by existovať možnosť odkazovať na jednotlivé verzie a sekcie.
  • Posledná verzia je uvedená na prvom mieste.
  • Pre každú verziu je uvedený dátum jej vydania.
  • Uveď tiež, že sa držíš sémantického verziovania.

Typy zmien

  • Added pre nové funkcie.
  • Changed pre zmeny existujúcej funkcie.
  • Deprecated pre funkcie, ktoré budú čoskoro odstránené.
  • Removed pre odstránené funkcie.
  • Fixed pre opravy chýb.
  • Security v prípade bezpečnostných zraniteľností.

Ako minimalizovať úsilie vynaložené na udržiavanie changelogu?

Udržuj Unreleased sekciu na začiatku changelogu pre nadchádzajúce zmeny.

Má to dva dôvody:

  • Ľudia môžu vidieť, aké zmeny môžu očakávať v ďalších vydaniach
  • V čase vydávania novej verzie môžeš presunúť zmeny z Unreleased sekcie do sekcie novej verzie

Môžu byť changelogy zlé?

Áno. Tu je hneď niekoľko spôsobov, ako môžu byť neužitočné.

Diffy z commit logu

Použitie diffov z commit logu ako changelog nie je dobrý nápad: sú plné balastu. Veci ako merge commity, commity s nejasnými názvami, zmeny dokumentácie a pod.

Účel commitu je dokumentovanie kroku v evolúcii zdrojového kódu. Niektoré projekty commity prečisťujú, iné nie.

Účelom changelogu je dokumentovanie významných zmien, často naprieč viacerými commitmi, a jasne ich komunikovať koncovému používateľovi.

Ignorovanie oznámenia zastaralých funkcií

Keď používatelia prechádzajú na novšiu verziu, musí byť jasné, čo sa rozbije. Mala by pre nich existovať možnosť prejsť na verziu so zoznamom zastaralých funkcií, tieto funkcie odstrániť a následne prejsť na verziu, kde sú tieto zastaralé funkcie už odstránené.

Ak už nič iné, tak aspoň uveď zastaralé, odstránené funkcie a všetky zmeny, ktoré môžu niečo rozbiť, do changelogu.

Mätúce dátumy

Regionálne formáty dátumov sa líšia naprieč svetom a často je zložité nájsť formát dátumu, ktorý by bol prívetivý a intuitívny pre všetkých používateľov. Výhodou dátumu vo formáte 2017-07-17 je poradie od najväčšej jednotky po najmenšiu: rok, mesiac, deň. Tento formát sa tiež neprekrýva s inými formátmi, ktoré zamieňajú pozíciu dňa a mesiaca. Kvôli týmto dôvodom spolu s faktom, že ide o ISO štandard, je tento formát odporučený pre záznamy v changelogu.

Často kladené otázky

Existuje štandardný formát pre changelog?

Nie. Existuje GNU príručka pre štýl changelogu alebo dvojodstavcová GNU "smernica" pre NEWS súbor. Obe sú však nevhodné či nedostatočné.

Tento projekt sa snaží byť lepšou konvenciou pre changelog. Vychádza z pozorovania a zozbierania osvedčených postupov komunity okolo projektov s otvoreným zdrojovým kódom.

Zdravá kritika, diskusia a návrhy na zlepšenie sú vítané.

Ako by mal byť súbor changelogu pomenovaný?

Nazvi ho CHANGELOG.md. Niektoré projekty používajú tiež HISTORY, NEWS alebo RELEASES.

Je jednoduché myslieť si, že názov changelogu nie je taký dôležitý. Prečo však sťažovať koncovému používateľovi hľadanie významných zmien?

A čo GitHub Releases?

Je to skvelá iniciatíva. Služba Releases môže byť použitá pre premenu git tagov (napríklad tagu v1.0.0) na bohaté poznámky k vydaniam manuálnym pridávaním týchto poznámok alebo získaním správ z anotovaných git tagov a vytvorením poznámok k vydaniu z nich.

GitHub Releases vytvorí neprenosný changelog, ktorý môže byť zobrazený používateľom v rámci GitHubu. Je možné ich upraviť na veľmi podobný štýl, aký navrhuje projekt Udržuj changelog, tento postup však býva trochu zložitejší.

Súčasná verzia GitHub Releases tiež nie je ľahko objaviteľná koncovým používateľom, na rozdiel od klasického súboru s názvom napísaným veľkými písmenami (README, CONTRIBUTING atď.). Ďalším menším problémom je, že v súčasnosti nepodporuje odkazy na commit logy medzi jednotlivými vydaniami.

Môžu byť changelogy automaticky parsované?

Je to zložité, pretože ľudia používajú rôzne formáty a názvy súborov.

Vandamme je Ruby gem vytvorený tímom Gemnasium, ktorý parsuje mnohé (ale nie všetky) changelogy projektov s otvoreným zdrojovým kódom.

A čo spätne stiahnuté vydania?

Stiahnuté vydania sú verzie, ktoré museli byť neskôr spätne odobraté kvôli vážnej chybe alebo bezpečnostným rizikám. Tieto verzie sa často v changelogu ani neobjavia. Ale mali by sa. Zobrazovať by sa mali takto:

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

Tag [YANKED] kričí naschvál. Je dôležité, aby si ho ľudia všimli. Keďže je uzavretý zátvorkami, je tiež jednoduchšie ho programovo parsovať.

Mal by sa changelog niekedy prepisovať?

Samozrejme. Vždy sa nájde dobrý dôvod na vylepšenie changelogu. Sám často otváram pull requesty pre pridanie chýbajúceho vydania projektov s otvoreným kódom a neudržiavaným changelogom.

Tiež môže nastať situácia, že v poznámkach k vydaniu určitej verzie sa zabudla spomenúť podstatná zmena. V takom prípade je samozrejme dôležité tento changelog aktualizovať.

Ako môžem prispieť?

Tento dokument nie je úplná pravda; je mojím starostlivo zváženým názorom spolu s informáciami a príkladmi, ktoré som zozbieral.

Je tomu tak preto, aby komunita dosiahla určitý konsenzus. Verím, že diskusia je rovnako dôležitá ako samotný výsledok.

Takže, prosím, prilož ruku k dielu.

Rozhovory

Zúčastnil som sa podcastu The Changelog, kde sme sa rozprávali o tom, prečo by sa správci projektov a prispievatelia mali zaujímať o changelogy a tiež o motivácii za týmto projektom.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Udržuj changelog

Nenechaj kamarátov sypať git logy do changelogov.

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

## [Unreleased]

## [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

Čo je to changelog?

Changelog je súbor obsahujúci organizovaný, chronologicky usporiadaný zoznam významných zmien pre každú verziu daného projektu.

Prečo udržiavať changelog?

Aby používatelia a prispievatelia presne vedeli, aké podstatné zmeny sa udiali medzi jednotlivými vydaniami (alebo verziami) projektu.

Kto potrebuje changelog?

Ľudia. Či už konzumenti, alebo vývojári, koncoví používatelia softvéru sú ľudské bytosti, ktorým záleží na tom, čo softvér obsahuje. Keď sa softvér zmení, ľudia chcú vedieť prečo a ako.

Ako vytvorím dobrý changelog?

Hlavné princípy

  • Changelogy sú pre ľudí, nie stroje.
  • Changelog by mal obsahovať záznam pre každú jednu verziu.
  • Rovnaké typy zmien by mali byť zoskupené.
  • Mala by existovať možnosť odkazovať na jednotlivé verzie a sekcie.
  • Posledná verzia je uvedená na prvom mieste.
  • Pre každú verziu je uvedený dátum jej vydania.
  • Uveď tiež, že sa držíš sémantického verziovania.

Typy zmien

  • Added pre nové funkcie.
  • Changed pre zmeny existujúcej funkcie.
  • Deprecated pre funkcie, ktoré budú čoskoro odstránené.
  • Removed pre odstránené funkcie.
  • Fixed pre opravy chýb.
  • Security v prípade bezpečnostných zraniteľností.

Ako minimalizovať úsilie vynaložené na udržiavanie changelogu?

Udržuj Unreleased sekciu na začiatku changelogu pre nadchádzajúce zmeny.

Má to dva dôvody:

  • Ľudia môžu vidieť, aké zmeny môžu očakávať v ďalších vydaniach
  • V čase vydávania novej verzie môžeš presunúť zmeny z Unreleased sekcie do sekcie novej verzie

Môžu byť changelogy zlé?

Áno. Tu je hneď niekoľko spôsobov, ako môžu byť neužitočné.

Diffy z commit logu

Použitie diffov z commit logu ako changelog nie je dobrý nápad: sú plné balastu. Veci ako merge commity, commity s nejasnými názvami, zmeny dokumentácie a pod.

Účel commitu je dokumentovanie kroku v evolúcii zdrojového kódu. Niektoré projekty commity prečisťujú, iné nie.

Účelom changelogu je dokumentovanie významných zmien, často naprieč viacerými commitmi, a jasne ich komunikovať koncovému používateľovi.

Ignorovanie oznámenia zastaralých funkcií

Keď používatelia prechádzajú na novšiu verziu, musí byť jasné, čo sa rozbije. Mala by pre nich existovať možnosť prejsť na verziu so zoznamom zastaralých funkcií, tieto funkcie odstrániť a následne prejsť na verziu, kde sú tieto zastaralé funkcie už odstránené.

Ak už nič iné, tak aspoň uveď zastaralé, odstránené funkcie a všetky zmeny, ktoré môžu niečo rozbiť, do changelogu.

Mätúce dátumy

Regionálne formáty dátumov sa líšia naprieč svetom a často je zložité nájsť formát dátumu, ktorý by bol prívetivý a intuitívny pre všetkých používateľov. Výhodou dátumu vo formáte 2017-07-17 je poradie od najväčšej jednotky po najmenšiu: rok, mesiac, deň. Tento formát sa tiež neprekrýva s inými formátmi, ktoré zamieňajú pozíciu dňa a mesiaca. Kvôli týmto dôvodom spolu s faktom, že ide o ISO štandard, je tento formát odporučený pre záznamy v changelogu.

Často kladené otázky

Existuje štandardný formát pre changelog?

Nie. Existuje GNU príručka pre štýl changelogu alebo dvojodstavcová GNU "smernica" pre NEWS súbor. Obe sú však nevhodné či nedostatočné.

Tento projekt sa snaží byť lepšou konvenciou pre changelog. Vychádza z pozorovania a zozbierania osvedčených postupov komunity okolo projektov s otvoreným zdrojovým kódom.

Zdravá kritika, diskusia a návrhy na zlepšenie sú vítané.

Ako by mal byť súbor changelogu pomenovaný?

Nazvi ho CHANGELOG.md. Niektoré projekty používajú tiež HISTORY, NEWS alebo RELEASES.

Je jednoduché myslieť si, že názov changelogu nie je taký dôležitý. Prečo však sťažovať koncovému používateľovi hľadanie významných zmien?

A čo GitHub Releases?

Je to skvelá iniciatíva. Služba Releases môže byť použitá pre premenu git tagov (napríklad tagu v1.0.0) na bohaté poznámky k vydaniam manuálnym pridávaním týchto poznámok alebo získaním správ z anotovaných git tagov a vytvorením poznámok k vydaniu z nich.

GitHub Releases vytvorí neprenosný changelog, ktorý môže byť zobrazený používateľom v rámci GitHubu. Je možné ich upraviť na veľmi podobný štýl, aký navrhuje projekt Udržuj changelog, tento postup však býva trochu zložitejší.

Súčasná verzia GitHub Releases tiež nie je ľahko objaviteľná koncovým používateľom, na rozdiel od klasického súboru s názvom napísaným veľkými písmenami (README, CONTRIBUTING atď.). Ďalším menším problémom je, že v súčasnosti nepodporuje odkazy na commit logy medzi jednotlivými vydaniami.

Môžu byť changelogy automaticky parsované?

Je to zložité, pretože ľudia používajú rôzne formáty a názvy súborov.

Vandamme je Ruby gem vytvorený tímom Gemnasium, ktorý parsuje mnohé (ale nie všetky) changelogy projektov s otvoreným zdrojovým kódom.

A čo spätne stiahnuté vydania?

Stiahnuté vydania sú verzie, ktoré museli byť neskôr spätne odobraté kvôli vážnej chybe alebo bezpečnostným rizikám. Tieto verzie sa často v changelogu ani neobjavia. Ale mali by sa. Zobrazovať by sa mali takto:

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

Tag [YANKED] kričí naschvál. Je dôležité, aby si ho ľudia všimli. Keďže je uzavretý zátvorkami, je tiež jednoduchšie ho programovo parsovať.

Mal by sa changelog niekedy prepisovať?

Samozrejme. Vždy sa nájde dobrý dôvod na vylepšenie changelogu. Sám často otváram pull requesty pre pridanie chýbajúceho vydania projektov s otvoreným kódom a neudržiavaným changelogom.

Tiež môže nastať situácia, že v poznámkach k vydaniu určitej verzie sa zabudla spomenúť podstatná zmena. V takom prípade je samozrejme dôležité tento changelog aktualizovať.

Ako môžem prispieť?

Tento dokument nie je úplná pravda; je mojím starostlivo zváženým názorom spolu s informáciami a príkladmi, ktoré som zozbieral.

Je tomu tak preto, aby komunita dosiahla určitý konsenzus. Verím, že diskusia je rovnako dôležitá ako samotný výsledok.

Takže, prosím, prilož ruku k dielu.

Rozhovory

Zúčastnil som sa podcastu The Changelog, kde sme sa rozprávali o tom, prečo by sa správci projektov a prispievatelia mali zaujímať o changelogy a tiež o motivácii za týmto projektom.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Vzdržujte dnevnik sprememb oz. CHANGELOG

Ne dopustite, da vaši prijatelji odlagajo git dnevnike v CHANGELOG™

Verzija 0.3.0

Kaj je dnevnik sprememb?

Dnevnik sprememb je datoteka, ki vsebuje kuriran, kronološko urejen seznam opaznih sprememb za vsako verzijo projekta.

# 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.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?".

Kaj je smisel dnevnika sprememb?

Za poenostavitev, da uporabniki in prispevajoči sodelavci natančno vidijo, katere opazne spremembe so bile narejene med vsako izdajo (ali verzijo) projekta.

Zakaj se truditi?

Ker so programska orodja za ljudi. Če vam to ni pomembno, zakaj prispevate odprto kodnemu projektu? Zagotovo mora obstajati malenkost (hehe) skrbnosti nekje v vaši lepi glavi.

Govorili smo z Adam-om Stacoviak-om in Jerod-om Santo na temo Changelog-a (ustrezno, kajne?) podcast o tem zakaj bi se morali vzdrževalci in sodelavci, ki prispevajo, truditi in o motivaciji za tem projektom. Če imate na voljo nekaj časa (1:06), je odlično poslušanje.

Kaj naredi dnevnik sprememb odličen?

Veseli me, da ste vprašali.

Dober dnevnik sprememb se drži teh načel:

Kako zmanjšati potreben trud?

Vedno imejte "Unreleased" sekcijo na vrhu za sledenje katerih koli sprememb.

To služi dvema namenoma:

Kaj spravi samoroga v jok?

Dobro … pojdimo skozi.

Tega je še več. Pomagajte zbrati te solze samoroga preko odprtja težave ali zahtevka potega.

Ali obstaja standardna oblika dnevnika sprememb?

Na žalost ne. Vendar mirno kri. Vem, da besno hitite najti to povezavo v vodiču dnevnika sprememb GNU ali v datoteki dveh odstavkov "guideline" GNU NEWS. Stilski vodič GNU je lep začetek, vendar je na žalost preveč enostaven. S tem ni nič narobe, vendar ko uporabniki potrebujejo vodič, je redko v pomoč. Posebej, ko je za reševati veliko situacij in posebnih primerov.

Ta projekt vsebuje, kar upamo, da bo postalo boljša datoteka konvencij CHANGELOG. Mislimo, da status quo ni dovolj dober in mislimo, da lahko kot skupnost naredimo boljšo konvencijo, če poskusimo izvleči dobre prakse iz realnih programskih projektov. Prosimo, poglejte naokoli in si zapomnite, da diskusije in predlogi za izboljšave so dobrodošli!

Kako se mora dnevnik sprememb imenovati?

Če niste uspeli razbrati iz zgornjega primera, je CHANGELOG.md najboljša konvencija do sedaj.

Nekateri projekti uporabljajo tudi HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md itd.

Gre za zmešnjavo. Vsa ta imena ljudem samo otežijo najti dnevnik sprememb.

Zakaj uporabniki ne morejo uporabiti enostavno samo git log sprememb?

Ker so spremembe dnevnika polne šuma - privzeto. Lahko bi naredili ustrezen dnevnik sprememb tudi v hipotetičnem projektu, ki ga poganjajo popolni ljudje, ki nikoli ne naredijo napak, nikoli ne pozabijo poslati novih datotek in nikoli ne zamudijo nobenega dela refaktorizacije. Razlog pošiljke (commit-a) je dokumentirati en atomičen korak v procesu preko katerega se koda razvija iz enega stanja v drugo. Razlog dnevnika sprememb je dokumentiranje omembe vrednih sprememb med temi stanji.

Kakor obstaja razlika med dobrimi komentarji in samo kodo, tako je razlika med dnevnikom sprememb in dnevnikom git commit-a: eden opisuje zakaj, drugi pa kako.

Ali se da dnevnik sprememb samodejno razlčeniti?

Je težko, ker uporabniki sledijo divje različnim formatom in imenom datotek.

Vandamme je Ruby gem, ki ga je ustvarila ekipa Gemnasium. Razčlenjuje mnoge (vendar ne vse) dnevnike sprememb odprto kodnih projektov.

Zakaj razlikovanje med črkovanjem "CHANGELOG" in "change log"?

"CHANGELOG" je ime same datoteke. Je nekoliko glasno, vendar je to zgodovinska konvencija, kateri sledi mnogo odprto kodnih projektov. Drugi primeri podobnih datotek vključujejo README, LICENSE, in CONTRIBUTING.

Ime z velikimi črkami (kar je datoteko v starih operacijskih sistemih prikazalo na vrhu) je uporabljeno, da se povleče pozornost nanje. Ker gre za pomembne meta podatke o projektu, so lahko uporabne za kogarkoli, ki namerava uporabiti ali prispevati, precej enako kot značke odprto kodnih projektov.

Ko se sklicujemo na "change log", govorimo o funkciji te datoteke: beleženje sprememb.

Kaj pa povlečene izdaje?

T.i. yanked ali povlečene izdaje so verzije, ki so bile primorane biti potegnjene zaradi resnega hrošča ali varnostne težave. Pogostokrat se te verzije niti ne pojavijo v dnevnikih sprememb. Vendar bi se morale. Prikazane bi morale biti sledeče:

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

Oznaka [YANKED] je izpisana z velikimi črkami z razlogom. Pomembno je, da jo uporabniki opazijo. Ker je obdana z oglatimi oklepaji, jo je tudi enostavnejše razčleniti programsko.

Ali bi morali kadarkoli prepisati dnevnik sprememb?

Seveda. Vedno obstajajo dobri razlogi, kako izboljšati dnevnik sprememb. Odpiranje zahtevkov potegov je pogostokrat priporočljivo, da se doda manjkajoče izdaje odprtokodnih projektov z nevzdrževanimi dnevniki sprememb.

Možno je tudi, da odkrijete, da ste pozabili nasloviti pomembne spremembe v opombah verzije. Očitno je pomembno, da vaš dnevnik sprememb v tem primeru posodobite.

Kako lahko pomagam?

Ta dokument ni dejstvo; je osebno temeljito premišljeno mnenje, skupaj z informacijami in primeri, ki smo jih zbrali. Čeprav ponujamo dejanski CHANGELOG v GitHub repozitoriju, namenoma ni ustvarjene primerne izdaje ali jasnega seznama pravil za sledenje (kot ima to npr. SemVer.org).

To je zato, ker želimo, da naša skupnost doseže soglasje. Verjamemo, da je razprava tako pomembna kot končni rezultat.

Torej, prosimo pridružite se.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Vzdržujte dnevnik sprememb oz. CHANGELOG

Ne dopustite, da vaši prijatelji odlagajo git dnevnike v CHANGELOG™

Verzija 0.3.0

Kaj je dnevnik sprememb?

Dnevnik sprememb je datoteka, ki vsebuje kuriran, kronološko urejen seznam opaznih sprememb za vsako verzijo projekta.

# 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.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?".

Kaj je smisel dnevnika sprememb?

Za poenostavitev, da uporabniki in prispevajoči sodelavci natančno vidijo, katere opazne spremembe so bile narejene med vsako izdajo (ali verzijo) projekta.

Zakaj se truditi?

Ker so programska orodja za ljudi. Če vam to ni pomembno, zakaj prispevate odprto kodnemu projektu? Zagotovo mora obstajati malenkost (hehe) skrbnosti nekje v vaši lepi glavi.

Govorili smo z Adam-om Stacoviak-om in Jerod-om Santo na temo Changelog-a (ustrezno, kajne?) podcast o tem zakaj bi se morali vzdrževalci in sodelavci, ki prispevajo, truditi in o motivaciji za tem projektom. Če imate na voljo nekaj časa (1:06), je odlično poslušanje.

Kaj naredi dnevnik sprememb odličen?

Veseli me, da ste vprašali.

Dober dnevnik sprememb se drži teh načel:

Kako zmanjšati potreben trud?

Vedno imejte "Unreleased" sekcijo na vrhu za sledenje katerih koli sprememb.

To služi dvema namenoma:

Kaj spravi samoroga v jok?

Dobro … pojdimo skozi.

Tega je še več. Pomagajte zbrati te solze samoroga preko odprtja težave ali zahtevka potega.

Ali obstaja standardna oblika dnevnika sprememb?

Na žalost ne. Vendar mirno kri. Vem, da besno hitite najti to povezavo v vodiču dnevnika sprememb GNU ali v datoteki dveh odstavkov "guideline" GNU NEWS. Stilski vodič GNU je lep začetek, vendar je na žalost preveč enostaven. S tem ni nič narobe, vendar ko uporabniki potrebujejo vodič, je redko v pomoč. Posebej, ko je za reševati veliko situacij in posebnih primerov.

Ta projekt vsebuje, kar upamo, da bo postalo boljša datoteka konvencij CHANGELOG. Mislimo, da status quo ni dovolj dober in mislimo, da lahko kot skupnost naredimo boljšo konvencijo, če poskusimo izvleči dobre prakse iz realnih programskih projektov. Prosimo, poglejte naokoli in si zapomnite, da diskusije in predlogi za izboljšave so dobrodošli!

Kako se mora dnevnik sprememb imenovati?

Če niste uspeli razbrati iz zgornjega primera, je CHANGELOG.md najboljša konvencija do sedaj.

Nekateri projekti uporabljajo tudi HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md itd.

Gre za zmešnjavo. Vsa ta imena ljudem samo otežijo najti dnevnik sprememb.

Zakaj uporabniki ne morejo uporabiti enostavno samo git log sprememb?

Ker so spremembe dnevnika polne šuma - privzeto. Lahko bi naredili ustrezen dnevnik sprememb tudi v hipotetičnem projektu, ki ga poganjajo popolni ljudje, ki nikoli ne naredijo napak, nikoli ne pozabijo poslati novih datotek in nikoli ne zamudijo nobenega dela refaktorizacije. Razlog pošiljke (commit-a) je dokumentirati en atomičen korak v procesu preko katerega se koda razvija iz enega stanja v drugo. Razlog dnevnika sprememb je dokumentiranje omembe vrednih sprememb med temi stanji.

Kakor obstaja razlika med dobrimi komentarji in samo kodo, tako je razlika med dnevnikom sprememb in dnevnikom git commit-a: eden opisuje zakaj, drugi pa kako.

Ali se da dnevnik sprememb samodejno razlčeniti?

Je težko, ker uporabniki sledijo divje različnim formatom in imenom datotek.

Vandamme je Ruby gem, ki ga je ustvarila ekipa Gemnasium. Razčlenjuje mnoge (vendar ne vse) dnevnike sprememb odprto kodnih projektov.

Zakaj razlikovanje med črkovanjem "CHANGELOG" in "change log"?

"CHANGELOG" je ime same datoteke. Je nekoliko glasno, vendar je to zgodovinska konvencija, kateri sledi mnogo odprto kodnih projektov. Drugi primeri podobnih datotek vključujejo README, LICENSE, in CONTRIBUTING.

Ime z velikimi črkami (kar je datoteko v starih operacijskih sistemih prikazalo na vrhu) je uporabljeno, da se povleče pozornost nanje. Ker gre za pomembne meta podatke o projektu, so lahko uporabne za kogarkoli, ki namerava uporabiti ali prispevati, precej enako kot značke odprto kodnih projektov.

Ko se sklicujemo na "change log", govorimo o funkciji te datoteke: beleženje sprememb.

Kaj pa povlečene izdaje?

T.i. yanked ali povlečene izdaje so verzije, ki so bile primorane biti potegnjene zaradi resnega hrošča ali varnostne težave. Pogostokrat se te verzije niti ne pojavijo v dnevnikih sprememb. Vendar bi se morale. Prikazane bi morale biti sledeče:

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

Oznaka [YANKED] je izpisana z velikimi črkami z razlogom. Pomembno je, da jo uporabniki opazijo. Ker je obdana z oglatimi oklepaji, jo je tudi enostavnejše razčleniti programsko.

Ali bi morali kadarkoli prepisati dnevnik sprememb?

Seveda. Vedno obstajajo dobri razlogi, kako izboljšati dnevnik sprememb. Odpiranje zahtevkov potegov je pogostokrat priporočljivo, da se doda manjkajoče izdaje odprtokodnih projektov z nevzdrževanimi dnevniki sprememb.

Možno je tudi, da odkrijete, da ste pozabili nasloviti pomembne spremembe v opombah verzije. Očitno je pomembno, da vaš dnevnik sprememb v tem primeru posodobite.

Kako lahko pomagam?

Ta dokument ni dejstvo; je osebno temeljito premišljeno mnenje, skupaj z informacijami in primeri, ki smo jih zbrali. Čeprav ponujamo dejanski CHANGELOG v GitHub repozitoriju, namenoma ni ustvarjene primerne izdaje ali jasnega seznama pravil za sledenje (kot ima to npr. SemVer.org).

To je zato, ker želimo, da naša skupnost doseže soglasje. Verjamemo, da je razprava tako pomembna kot končni rezultat.

Torej, prosimo pridružite se.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Vodite Changelog

Ne dajte prijateljima da trpaju git logove u changelogove.

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

## [Unreleased]

## [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

Šta je changelog?

Changelog je datoteka koja sadrži uređeni hronološki poređani popis značajnih promena unutar svake verzije projekta.

Zašto voditi changelog?

Kako bi korisnici i saradnici detaljno videli značajne promjene među pojedinim izdanjima (ili verzijama) projekta.

Kome treba changelog?

Ljudima. Bilo da su uobičajeni korisnici ili programeri, krajnji su korisnici softvera ljudska bića kojima je stalo do toga od čega je sastavljen. Kada se softver menja, korisnici žele znati kako i zašto.

Kako kreirati dobar changelog?

Glavna načela

  • Changelogs služi ljudima, ne mašinama.
  • Potrebno je stvoriti unos za svaku verziju.
  • Slične promene potrebno je grupisati.
  • Verzije i odeljci trebaju imati vezu.
  • Poslednja verzija treba biti na prvom mestu.
  • Datum izdavanja svake pojedine verzije treba biti vidljiv.
  • Navesti prati li se Semantičko verzioniranje.

Vrste promena

  • Added za nove funkcionalnosti.
  • Changed za promene u postojećim funkcionalnostima.
  • Deprecated za funkcionalnosti koje će se ukloniti u budućim verzijama.
  • Removed za uklonjene funkcionalnosti.
  • Fixed za ispravke bagova.
  • Security za slučaj sigurnosnih propusta.

Kako održavati changelog sa što manje napora?

Na vrh postavite Unreleased sekciju gde ćete navoditi nadolazeće promene.

To radimo iz dva razloga:

  • Korisnici mogu videti promene koje mogu očekivati u nadolazećim izdanjima
  • Kod izdavanja nove verzije, moguće je Unreleased sekciju samo preimenovati u novo izdanje.

Može li changelog biti loš?

Naravno. Postoji nekoliko slučajeva u kojima changelog može biti beskoristan.

Commit log diffovi

Korištenje commit log diffova u svrhu changeloga nije dobra ideja: puni su šuma. Npr. merge commitovi, commitovi s nejasnim naslovima, promene u dokumentaciji i sl.

Svrha commita je da beleži korake u razvoju izvornog koda. U nekim projektima se comittovi čiste, no ponekad i ne.

Svrha unosa u changelogu je da beleži značajne razlike, a često kroz više commitova i jasno ih prenese krajnjem korisniku.

Ignorisanje uklonjenih funkcionalnosti

Kad korisnici nadograde softver na noviju verziju, treba biti potpuno jasno da postoji mogućnost da će se neki deo pokvariti. Softver treba biti moguće nadograditi na verziju koja će navesti funkcionalnosti koje trebaju biti uklonjene, uklanja takve te se kasnije može nadograditi na verziju gde su već uklonjene.

U najmanju ruku, potrebno je u changelogu navoditi funkcionalnosti koje će biti uklonjene, funkcionalnosti koje su uklonjene i promene koje će uticati na rad softvera (breaking change).

Nejasni datumi

Regionalni formati datuma variraju delom sveta, pa je često teško pronaći format datuma koji će odgovarati svima. Prednost datuma u formatu 2017-07-17 je to što je poređan od veće prema manjoj jedinici: godina, mesec, dan. Ovaj je format takođe teško zameniti s drugim regionalnim formatima, za razliku od nekih koji, primera radi, menjaju poziciju oznake meseca i dana. Iz tog razloga, a i zbog toga što je navedeni format ISO standard, taj se format preporučuje za changelog unose.

Česta pitanja

Postoji li standardni changelog format?

Zapravo ne. Postoji GNU changelog stilski priručnik, i GNU NEWS file "priručnik od dva odlomka". Nijedan nije adekvatan ni dovoljan.

Cilj ovoga projekta kvalitetniji changelog standard. Nastao je prikupljanjem primera dobra prakse u open source zajednici.

Konstruktivna kritika, raprave i predlozi za poboljšanje su dobrodošli.

Kako nazvati changelog datoteku?

Dajemo joj naziv CHANGELOG.md. Neki projekti još koriste HISTORY, NEWS ili RELEASES.

Iako može delovati da naziv changelog datoteke i nije toliko bitan, čemu otežavati korisnicima da dođu do informacije o promjenama?

Šta s GitHub Releases?

To je ozbiljna inicijativa. Releases se mogu koristiti kako bi git oznake (npr. git oznaka v1.0.0) pretvorili u opširnije beleške o izdanju, upisujući ih ručno ili pak preuzimajući anotirane git oznake i pretvarajući ih u unose.

GitHub Releases stvara statični changelog vidljiv korisnicima unutar GitHub repozitorijuma. Moguće ih je urediti u format koji bi odgovarao Vodite changelog formatu, no često je nešto opširniji.

Trenutna GitHub releases verzija i nije baš sasvim vidljiva korisnicima, za razliku od uobičajenih datoteka označenih velikim slovima (README, CONTRIBUTING, itd.). Još je jedan manji problem što trenutno interfejs ne nudi poveznice na commit logove između izdanja.

Mogu li changelogovi automatski parsirati?

Teže, jer se koriste vrlo različiti formati, kao i nazivi datoteka.

Vandamme je Ruby gem koji je kreirao Gemnasium tim i može parsirati mnoge (ali ne sve) changelogove projekata otvorenog koda.

Šta s povučenim izdanjima?

Povučena ili 'Yanked' izdanja su verzije koje su uklonjene zbog ozbiljnijeg baga ili sigurnosnog propusta. Takva se izdanja najčešće i ne pojavljuju u changelogu, iako bi trebala. Trebala bi biti navedena na sledeći način:

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

[YANKED] oznaka jasno je istaknuta s razlogom. Bitno je da ju je lako primetiti. Buduće da je okružena zagradama, takođe ju je lakše parsirati.

Da li je potrebno prepravljati changelog?

Naravno. Često postoje dobri razlozi da bismo poboljšali changelog. Ja često otvaram pull requestove kako bih dodao nedostajuća izdanja projektima otvorenog koda, koji ne održavaju changelogove.

Moguće je, takođe da otkrijete, kako ste zaboravili navesti promenu koja bi uticala na rad (breaking change). U tom slučaju je, očito, vrlo bitno ažurirati changelog.

Kako doprineti?

Ovaj dokument nije Sveto Pismo; ovo je samo pažljivo razmotreno mišljenje, uz informacije i primere koje sam skupio.

Razlog je tome to što želim da zajednica postigne konsenzus. Verujem, takođe, da je i sama rasprava bitna kao i krajnji rezultat.

Zato, molimo uskočite.

Razgovori

Gostovao sam na The Changelog podcastu gde sam pokušao objasniti zašto začetnici projekata i saradnici trebaju brinuti o changelogovima te motivaciji iza ovog projekta.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Vodite Changelog

Ne dajte prijateljima da trpaju git logove u changelogove.

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

## [Unreleased]

## [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

Šta je changelog?

Changelog je datoteka koja sadrži uređeni hronološki poređani popis značajnih promena unutar svake verzije projekta.

Zašto voditi changelog?

Kako bi korisnici i saradnici detaljno videli značajne promjene među pojedinim izdanjima (ili verzijama) projekta.

Kome treba changelog?

Ljudima. Bilo da su uobičajeni korisnici ili programeri, krajnji su korisnici softvera ljudska bića kojima je stalo do toga od čega je sastavljen. Kada se softver menja, korisnici žele znati kako i zašto.

Kako kreirati dobar changelog?

Glavna načela

  • Changelogs služi ljudima, ne mašinama.
  • Potrebno je stvoriti unos za svaku verziju.
  • Slične promene potrebno je grupisati.
  • Verzije i odeljci trebaju imati vezu.
  • Poslednja verzija treba biti na prvom mestu.
  • Datum izdavanja svake pojedine verzije treba biti vidljiv.
  • Navesti prati li se Semantičko verzioniranje.

Vrste promena

  • Added za nove funkcionalnosti.
  • Changed za promene u postojećim funkcionalnostima.
  • Deprecated za funkcionalnosti koje će se ukloniti u budućim verzijama.
  • Removed za uklonjene funkcionalnosti.
  • Fixed za ispravke bagova.
  • Security za slučaj sigurnosnih propusta.

Kako održavati changelog sa što manje napora?

Na vrh postavite Unreleased sekciju gde ćete navoditi nadolazeće promene.

To radimo iz dva razloga:

  • Korisnici mogu videti promene koje mogu očekivati u nadolazećim izdanjima
  • Kod izdavanja nove verzije, moguće je Unreleased sekciju samo preimenovati u novo izdanje.

Može li changelog biti loš?

Naravno. Postoji nekoliko slučajeva u kojima changelog može biti beskoristan.

Commit log diffovi

Korištenje commit log diffova u svrhu changeloga nije dobra ideja: puni su šuma. Npr. merge commitovi, commitovi s nejasnim naslovima, promene u dokumentaciji i sl.

Svrha commita je da beleži korake u razvoju izvornog koda. U nekim projektima se comittovi čiste, no ponekad i ne.

Svrha unosa u changelogu je da beleži značajne razlike, a često kroz više commitova i jasno ih prenese krajnjem korisniku.

Ignorisanje uklonjenih funkcionalnosti

Kad korisnici nadograde softver na noviju verziju, treba biti potpuno jasno da postoji mogućnost da će se neki deo pokvariti. Softver treba biti moguće nadograditi na verziju koja će navesti funkcionalnosti koje trebaju biti uklonjene, uklanja takve te se kasnije može nadograditi na verziju gde su već uklonjene.

U najmanju ruku, potrebno je u changelogu navoditi funkcionalnosti koje će biti uklonjene, funkcionalnosti koje su uklonjene i promene koje će uticati na rad softvera (breaking change).

Nejasni datumi

Regionalni formati datuma variraju delom sveta, pa je često teško pronaći format datuma koji će odgovarati svima. Prednost datuma u formatu 2017-07-17 je to što je poređan od veće prema manjoj jedinici: godina, mesec, dan. Ovaj je format takođe teško zameniti s drugim regionalnim formatima, za razliku od nekih koji, primera radi, menjaju poziciju oznake meseca i dana. Iz tog razloga, a i zbog toga što je navedeni format ISO standard, taj se format preporučuje za changelog unose.

Česta pitanja

Postoji li standardni changelog format?

Zapravo ne. Postoji GNU changelog stilski priručnik, i GNU NEWS file "priručnik od dva odlomka". Nijedan nije adekvatan ni dovoljan.

Cilj ovoga projekta kvalitetniji changelog standard. Nastao je prikupljanjem primera dobra prakse u open source zajednici.

Konstruktivna kritika, raprave i predlozi za poboljšanje su dobrodošli.

Kako nazvati changelog datoteku?

Dajemo joj naziv CHANGELOG.md. Neki projekti još koriste HISTORY, NEWS ili RELEASES.

Iako može delovati da naziv changelog datoteke i nije toliko bitan, čemu otežavati korisnicima da dođu do informacije o promjenama?

Šta s GitHub Releases?

To je ozbiljna inicijativa. Releases se mogu koristiti kako bi git oznake (npr. git oznaka v1.0.0) pretvorili u opširnije beleške o izdanju, upisujući ih ručno ili pak preuzimajući anotirane git oznake i pretvarajući ih u unose.

GitHub Releases stvara statični changelog vidljiv korisnicima unutar GitHub repozitorijuma. Moguće ih je urediti u format koji bi odgovarao Vodite changelog formatu, no često je nešto opširniji.

Trenutna GitHub releases verzija i nije baš sasvim vidljiva korisnicima, za razliku od uobičajenih datoteka označenih velikim slovima (README, CONTRIBUTING, itd.). Još je jedan manji problem što trenutno interfejs ne nudi poveznice na commit logove između izdanja.

Mogu li changelogovi automatski parsirati?

Teže, jer se koriste vrlo različiti formati, kao i nazivi datoteka.

Vandamme je Ruby gem koji je kreirao Gemnasium tim i može parsirati mnoge (ali ne sve) changelogove projekata otvorenog koda.

Šta s povučenim izdanjima?

Povučena ili 'Yanked' izdanja su verzije koje su uklonjene zbog ozbiljnijeg baga ili sigurnosnog propusta. Takva se izdanja najčešće i ne pojavljuju u changelogu, iako bi trebala. Trebala bi biti navedena na sledeći način:

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

[YANKED] oznaka jasno je istaknuta s razlogom. Bitno je da ju je lako primetiti. Buduće da je okružena zagradama, takođe ju je lakše parsirati.

Da li je potrebno prepravljati changelog?

Naravno. Često postoje dobri razlozi da bismo poboljšali changelog. Ja često otvaram pull requestove kako bih dodao nedostajuća izdanja projektima otvorenog koda, koji ne održavaju changelogove.

Moguće je, takođe da otkrijete, kako ste zaboravili navesti promenu koja bi uticala na rad (breaking change). U tom slučaju je, očito, vrlo bitno ažurirati changelog.

Kako doprineti?

Ovaj dokument nije Sveto Pismo; ovo je samo pažljivo razmotreno mišljenje, uz informacije i primere koje sam skupio.

Razlog je tome to što želim da zajednica postigne konsenzus. Verujem, takođe, da je i sama rasprava bitna kao i krajnji rezultat.

Zato, molimo uskočite.

Razgovori

Gostovao sam na The Changelog podcastu gde sam pokušao objasniti zašto začetnici projekata i saradnici trebaju brinuti o changelogovima te motivaciji iza ovog projekta.

Den senaste versionen (1.1.0) är ännu inte tillgänglig på Svenska, men du kan läsa det på engelska och även hjälpa till att översätta det.

Håll en CHANGELOG

Låt inte dina vänner slänga in en git logs i CHANGELOG™

Version 0.3.0

Vad är en ändringslogg?

En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad lista över ändringar för varje version av ett projekt.

# 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.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?".

Vad är meningen med en ändringslogg?

För att göra det enkelt för användare och medarbetare att se exakt vilka viktiga ändringar som har gjorts mellan varje utgåva (eller version) av projektet.

Varför ska jag bry mig?

Därför att mjukvaruverktyg är för människor. Om du inte bryr dig, varför bidrar du till öppen källkod? Visst finns det väl någon del i din vackra hjärna som bryr sig.

Jag pratade med Adam Stacoviak och Jerod Santo från podcasten The Changelog (passande, eller hur?) om varför ansvariga och bidragsgivare bör bry sig, och motiveringen bakom detta projekt. Om du kan avvara lite tid (1:06), rekommenderar jag att lyssna på det.

Vad gör en bra ändringslogg?

Jag är glad att du frågade.

En bra ändringslogg håller sig till dessa principer:

Hur kan jag minimera den insats som krävs?

Ha alltid en sektion kallad "Unreleased" högst upp för att hålla reda på alla ändringar.

Detta tjänar två syften:

Vad får änglarna att gråta?

Okej...låt oss gå genom det.

Det finns mer. Hjälp mig att samla tårarna från änglarna genom att öppna en issue eller en pull-förfrågan.

Finns det ett standardformat på ändringsloggar?

Tyvärr inte. Men lugn. Jag vet att du frustrerad kommer att rusa iväg för att hitta den där länken till GNU:s format för ändringsloggar, eller den två stycken långa GNU NEWS-filen med "guideline". Stilguiden från GNU är en bra start, men den är tyvärr allt för naiv. Det är inget fel med att vara naiv, men när människor behöver vägledning är det inte speciellt hjälpsamt. Speciellt när det är många olika situationer och specialfall att hantera.

Detta projekt innehåller vad jag hoppas kommer att bli en bättre filkonvention för CHANGELOG. Jag tror inte att status quo är tillräckligt bra, och jag tror att vi tillsammans kan komma fram till en bättre konvention om vi försöker att plocka ut bra erfarenheter från riktiga mjukvaruprojekt. Titta runt och kom ihåg att diskussioner och förbättringsförslag är välkomna!

Vad bör filen med ändringsloggen heta?

Tja, om du inte kan lista ut det från exemplen ovan är CHANGELOG.md den bästa konvention hittills.

En del projekt använder också HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.

Det är en verklig röra. Alla dessa namn gör det bara svårare för människor att hitta.

Varför kan folk inte bara använda en diff från git log?

Eftersom logg-diffar av naturen är fulla med brus. Det kan inte ens användas för att göra en lämplig ändringslogg ens i ett hypotetiskt projekt drivet av perfekta människor som aldrig skriver fel, aldrig glömmer att checka in nya filer eller aldrig glömmer någon del av en refaktorering. Syftet med en commit är att dokumentera ett enskilt steg i processen då koden utvecklas från ett tillstånd till ett annat. Syftet med en ändringslogg är att dokumentera de anmärkningsvärda skillnaderna mellan dessa tillstånd.

På samma sätt som det är skillnad mellan bra kommentarer och själva koden, är det skillnad mellan ändringsloggen och commit-loggen: en beskriver varför och den andra hur.

Kan ändringsloggar bli automatiskt tolkade?

Det är svårt då människor följer vitt olika format och filnamn.

Vandamme är en Ruby gem skapad av gruppen bakom Gemnasium som tolkar många (men inte alla) ändringsloggar för öppen källkod.

Varför alternerar du mellan att skriva det som "CHANGELOG" och "ändringslogg"?

"CHANGELOG" är namnet på själva filen. Det sticker ut lite, men det är en historisk konvention använt i många öppna källkodsprojekt. Andra exempel på liknande filer är README, LICENSE och CONTRIBUTING.

De stora bokstäverna i namnen (som gjorde att de i äldre operativsystem hamnade högst upp) används för att dra uppmärksamhet till dem. Då de är viktig metadata om projektet borde de vara användbara för att alla som vill använda eller bidra till det, ungefär som open source project badges.

När jag refererar till "ändringslogg" pratar jag om syftet med denna fil: att logga ändringar.

Hur är det med brådskande utgåvor ("yanked")?

Brådskande utgåvor är versioner som måste släppas p.g.a. alvarliga buggar eller säkerhetsproblem. Oftast brukar dessa versioner inte ens finnas med i ändringsloggarna. De borde det. Så här borde du visa dem:

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

Taggen [YANKED] står ut av en anledning, det är viktigt för människor att se den. Då den är omsluten med hakparenteser är det också lättare för ett program att tolka.

Borde du någonsin förändra en ändringslogg?

Självklart. Det finns alltid en bra anlending att förbättra en ändringslogg. Jag öppnar regelbundet pull requests för att lägga till saknade utgåvor för öppna källkodsprojekt som inte tar hand om sin ändringslogg.

Det kan också hända att du upptäcker att du glömt att ta upp en icke bakåtkompatibel förändring i en version. I sådana fall är det självklart viktigt att uppdatera din ändringslogg.

Hur kan jag bidra?

Detta dokument är inte sanningen, det är en noga övervägd åsikt tillsammans med information och exempel jag har samlat på mig. Även om jag tillhandahåller en CHANGELOG i min GitHub repo, har jag avsiktligt inte skapat en egentlig utgåva eller en tydlig lista med regler att följa (som t.ex. SemVer.org gör).

Detta beror på att jag vill att vår gemenskap ska nå samförstånd. Jag tror att diskussionen är lika viktig som slutresultatet.

Så välkomna att diskutera.

Den senaste versionen (1.1.0) är ännu inte tillgänglig på Svenska, men du kan läsa det på engelska och även hjälpa till att översätta det.

Håll en CHANGELOG

Låt inte dina vänner slänga in en git logs i CHANGELOG™

Version 0.3.0

Vad är en ändringslogg?

En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad lista över ändringar för varje version av ett projekt.

# 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.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?".

Vad är meningen med en ändringslogg?

För att göra det enkelt för användare och medarbetare att se exakt vilka viktiga ändringar som har gjorts mellan varje utgåva (eller version) av projektet.

Varför ska jag bry mig?

Därför att mjukvaruverktyg är för människor. Om du inte bryr dig, varför bidrar du till öppen källkod? Visst finns det väl någon del i din vackra hjärna som bryr sig.

Jag pratade med Adam Stacoviak och Jerod Santo från podcasten The Changelog (passande, eller hur?) om varför ansvariga och bidragsgivare bör bry sig, och motiveringen bakom detta projekt. Om du kan avvara lite tid (1:06), rekommenderar jag att lyssna på det.

Vad gör en bra ändringslogg?

Jag är glad att du frågade.

En bra ändringslogg håller sig till dessa principer:

Hur kan jag minimera den insats som krävs?

Ha alltid en sektion kallad "Unreleased" högst upp för att hålla reda på alla ändringar.

Detta tjänar två syften:

Vad får änglarna att gråta?

Okej...låt oss gå genom det.

Det finns mer. Hjälp mig att samla tårarna från änglarna genom att öppna en issue eller en pull-förfrågan.

Finns det ett standardformat på ändringsloggar?

Tyvärr inte. Men lugn. Jag vet att du frustrerad kommer att rusa iväg för att hitta den där länken till GNU:s format för ändringsloggar, eller den två stycken långa GNU NEWS-filen med "guideline". Stilguiden från GNU är en bra start, men den är tyvärr allt för naiv. Det är inget fel med att vara naiv, men när människor behöver vägledning är det inte speciellt hjälpsamt. Speciellt när det är många olika situationer och specialfall att hantera.

Detta projekt innehåller vad jag hoppas kommer att bli en bättre filkonvention för CHANGELOG. Jag tror inte att status quo är tillräckligt bra, och jag tror att vi tillsammans kan komma fram till en bättre konvention om vi försöker att plocka ut bra erfarenheter från riktiga mjukvaruprojekt. Titta runt och kom ihåg att diskussioner och förbättringsförslag är välkomna!

Vad bör filen med ändringsloggen heta?

Tja, om du inte kan lista ut det från exemplen ovan är CHANGELOG.md den bästa konvention hittills.

En del projekt använder också HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.

Det är en verklig röra. Alla dessa namn gör det bara svårare för människor att hitta.

Varför kan folk inte bara använda en diff från git log?

Eftersom logg-diffar av naturen är fulla med brus. Det kan inte ens användas för att göra en lämplig ändringslogg ens i ett hypotetiskt projekt drivet av perfekta människor som aldrig skriver fel, aldrig glömmer att checka in nya filer eller aldrig glömmer någon del av en refaktorering. Syftet med en commit är att dokumentera ett enskilt steg i processen då koden utvecklas från ett tillstånd till ett annat. Syftet med en ändringslogg är att dokumentera de anmärkningsvärda skillnaderna mellan dessa tillstånd.

På samma sätt som det är skillnad mellan bra kommentarer och själva koden, är det skillnad mellan ändringsloggen och commit-loggen: en beskriver varför och den andra hur.

Kan ändringsloggar bli automatiskt tolkade?

Det är svårt då människor följer vitt olika format och filnamn.

Vandamme är en Ruby gem skapad av gruppen bakom Gemnasium som tolkar många (men inte alla) ändringsloggar för öppen källkod.

Varför alternerar du mellan att skriva det som "CHANGELOG" och "ändringslogg"?

"CHANGELOG" är namnet på själva filen. Det sticker ut lite, men det är en historisk konvention använt i många öppna källkodsprojekt. Andra exempel på liknande filer är README, LICENSE och CONTRIBUTING.

De stora bokstäverna i namnen (som gjorde att de i äldre operativsystem hamnade högst upp) används för att dra uppmärksamhet till dem. Då de är viktig metadata om projektet borde de vara användbara för att alla som vill använda eller bidra till det, ungefär som open source project badges.

När jag refererar till "ändringslogg" pratar jag om syftet med denna fil: att logga ändringar.

Hur är det med brådskande utgåvor ("yanked")?

Brådskande utgåvor är versioner som måste släppas p.g.a. alvarliga buggar eller säkerhetsproblem. Oftast brukar dessa versioner inte ens finnas med i ändringsloggarna. De borde det. Så här borde du visa dem:

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

Taggen [YANKED] står ut av en anledning, det är viktigt för människor att se den. Då den är omsluten med hakparenteser är det också lättare för ett program att tolka.

Borde du någonsin förändra en ändringslogg?

Självklart. Det finns alltid en bra anlending att förbättra en ändringslogg. Jag öppnar regelbundet pull requests för att lägga till saknade utgåvor för öppna källkodsprojekt som inte tar hand om sin ändringslogg.

Det kan också hända att du upptäcker att du glömt att ta upp en icke bakåtkompatibel förändring i en version. I sådana fall är det självklart viktigt att uppdatera din ändringslogg.

Hur kan jag bidra?

Detta dokument är inte sanningen, det är en noga övervägd åsikt tillsammans med information och exempel jag har samlat på mig. Även om jag tillhandahåller en CHANGELOG i min GitHub repo, har jag avsiktligt inte skapat en egentlig utgåva eller en tydlig lista med regler att följa (som t.ex. SemVer.org gör).

Detta beror på att jag vill att vår gemenskap ska nå samförstånd. Jag tror att diskussionen är lika viktig som slutresultatet.

Så välkomna att diskutera.

Den senaste versionen (1.1.0) är ännu inte tillgänglig på Svenska, men du kan läsa det på engelska och även hjälpa till att översätta det.

För en ändringslogg

Låt inte dina vänner slänga in git-loggar i ändringsloggar.

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

## [Unreleased]

## [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

Vad är en ändringslogg?

En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad lista över viktiga ändringar för varje version av ett projekt.

Vad är meningen med en ändringslogg?

För att göra det enklare för användare och medarbetare att se exakt vilka viktiga ändringar som har gjorts mellan varje utgåva (eller version) av projektet.

Vem behöver en ändringslogg?

Alla behöver det. Oavsett om det är användare eller utvecklare, är alla slutanvändare av mjukvaran människor som bryr sig vad som finns i mjukvaran. När mjukvaran förändras vill folk veta varför och hur.

Hur gör jag en bra ändringslogg?

Riktlinjer

  • Ändringsloggar är för människor, inte maskiner.
  • Det bör finnas en post för varje enskild version.
  • Samma typ av ändringar bör grupperas.
  • Det bör vara möjligt att länka till versioner och sektioner.
  • Senaste versionen kommer först.
  • Datum då respektive version släpptes ska visas.
  • Notering att du följer Semantisk versionshantering.

Typer av ändringar

  • Added för nya funktioner.
  • Changed för ändringar på existerande funktionalitet.
  • Deprecated för funktionalitet som snart tas bort.
  • Removed för nu borttagen funktionalitet.
  • Fixed för alla buggfixar
  • Security i fall av sårbarheter.

Hur kan jag minimera den insats som krävs för att underhålla en ändringslogg?

Ha en sektion kallad Unreleased högst upp för att hålla reda på kommande ändringar.

Detta tjänar två syften:

  • Folk kan se vilka ändringar de kan förvänta sig i kommande utgåvor
  • Vid lansering behöver du bara flytta innehållet i sektionen Unreleased till en ny versionspost.

Kan ändringsloggar vara dåliga?

Ja, här är några exempel på då de är mindre användbara.

Diffar från incheckningsloggen.

Det är en dålig idé att använda incheckningsloggen som ändringslogg: de är fulla av brus. Saker så som merge-incheckningar, incheckningar med otydliga titlar, dokumentationsförändringar etc.

Syftet med en incheckning är att dokumentera ett steg i utvecklingen av källkoden. Vissa projekt städar upp bland incheckningarna, andra inte.

Syftet med en post i en ändringslogg är att dokumentera den noterbara skillnaden, oftast över flera incheckningar, för att kommunicera dessa tydligt till slutanvändaren.

Ignorera föråldrad funktionalitet (deprecations)

När användare uppgraderar från en version till en annan, ska det vara smärtsamt uppenbart när något förväntas gå sönder. Den bör vara möjligt att uppgradera till en version som listar föråldrad funktionalitet, ta bort dessa beroenden i sitt program, och sedan uppgradera till en version där den föråldrade funktionaliteten är borttagen.

Om du inte gör något annat, lista åtminstone föråldrad och borttagen funktionalitet samt förstörande förändringar i din ändringslogg.

Förvillande datum

Lokala datumformat varierar över hela världen, och det är ofta svårt att hitta ett användbart datumformat som känns intuitivt för alla. Fördelen med datumformat så som 2017-07-17 är att det följer storleksordningen från störst till minst: år, månad och dag. Detta format överlappar inte heller på ett tvetydligt sätt med andra datumformat, till skillnad från lokala format som kan växla positionen på månad och dag. Dessa anledningar tillsammans med det faktum att detta datumformat är en ISO-standard, gör att detta är rekommenderat format för ändringsloggar.

Vanliga frågor

Finns det ett standardformat på ändringsloggar?

Inte riktigt. GNU:s stilguide för ändringsloggar och den två stycke långa GNU NEWS-filen med "riktlinjer" finns. Båda är bristfälliga och otillräckliga.

Detta projekt har som mål att bli en bättre konvention för ändringsloggar. Det utgår från uppenbart goda praxis från öppen källkods-världen och sammanför dem.

Konstruktiv kritik, diskussion och förslag till förbättring är välkommen.

Vad bör filen med ändringsloggen heta?

Döp den till CHANGELOG.md. En del projekt använder HISTORY, NEWS eller RELEASES.

Även om det är lätt att tänka att det inte spelar så stor roll vad filen med ändringsloggar kallas, varför göra det svårare för dina slutanvändare att enkelt hitta de viktigaste ändringarna?

Hur är det med GitHub Releases?

Det är ett fantasiskt initiativ. Releases kan användas för att göra enkla git-taggar (t.ex. en tagg kallad v1.0.0) till formaterade versionsanteckningar genom att manuellt lägga till versionsanteckningar eller så kan den hämta meddelandena i kommenterade git-taggar och omvandla dessa till versionsanteckningar.

GitHub Releases skapar en icke porterbar ändringslogg som enbart kan visas för användare på GitHub. Det är möjligt att formatera det ungefär som på För en ändringslogg-formatet, men det tendera att bli lite mer invecklat.

Nuvarande version av GitHub releases är möjligtvis också lite svår att hitta för slutanvändare, till skillnad från filer med normalt stora bokstäver (README, CONTRIBUTING, etc.). Ett annat bekymmer är att användargränssnittet för närvarande inte erbjuder länkar till incheckningsloggar mellan olika versioner.

Kan ändringsloggar bli automatiskt tolkade?

Det är svårt då människor följer vitt olika format och filnamn.

Vandamme är en Ruby gem skapad av gruppen Gemnasium som tolkar många (men inte alla) ändringsloggar för öppen källkod.

Hur är det med återtagna utgåvor ("yanked")?

Återtagna utgåvor är versioner som måste tas tillbaka på grund av allvarliga buggar eller säkerhetsproblem. Oftast brukar dessa versioner inte ens finnas med i ändringsloggarna. De borde det. Så här borde du visa dem:

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

Taggen [YANKED] står ut av en anledning, det är viktigt att folk se det. Då den är omsluten med hakparenteser är det också lättare för ett program att tolka det.

Borde du någonsin förändra en ändringslogg?

Självklart. Det finns alltid en bra anledning att förbättra en ändringslogg. Jag öppnar regelbundet pull requests för att lägga till saknade utgåvor för öppna källkodsprojekt som inte tar hand om sin ändringslogg.

Det kan också hända att du upptäcker att du glömt att ta upp en icke bakåtkompatibel förändring i en version. I sådana fall är det självklart viktigt att uppdatera din ändringslogg.

Hur kan jag bidra?

Detta dokument är inte sanningen, det är en noga övervägd åsikt tillsammans med information och exempel jag har samlat på mig.

Detta beror på att jag vill att vår gemenskap ska nå enighet. Jag tror på att diskussionen är lika viktig som slutresultatet.

Så tveka inte att kasta dig in i diskussionen.

Samtal

Jag var med i The Changelog podcast för att prata om varför förvaltare och bidragsgivare bör bry sig om ändringsloggar, och motiveringen bakom detta projekt.

Den senaste versionen (1.1.0) är ännu inte tillgänglig på Svenska, men du kan läsa det på engelska och även hjälpa till att översätta det.

För en ändringslogg

Låt inte dina vänner slänga in git-loggar i ändringsloggar.

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

## [Unreleased]

## [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

Vad är en ändringslogg?

En ändringslogg är en fil innehållandes en sammanfattad, kronologiskt ordnad lista över viktiga ändringar för varje version av ett projekt.

Vad är meningen med en ändringslogg?

För att göra det enklare för användare och medarbetare att se exakt vilka viktiga ändringar som har gjorts mellan varje utgåva (eller version) av projektet.

Vem behöver en ändringslogg?

Alla behöver det. Oavsett om det är användare eller utvecklare, är alla slutanvändare av mjukvaran människor som bryr sig vad som finns i mjukvaran. När mjukvaran förändras vill folk veta varför och hur.

Hur gör jag en bra ändringslogg?

Riktlinjer

  • Ändringsloggar är för människor, inte maskiner.
  • Det bör finnas en post för varje enskild version.
  • Samma typ av ändringar bör grupperas.
  • Det bör vara möjligt att länka till versioner och sektioner.
  • Senaste versionen kommer först.
  • Datum då respektive version släpptes ska visas.
  • Notering att du följer Semantisk versionshantering.

Typer av ändringar

  • Added för nya funktioner.
  • Changed för ändringar på existerande funktionalitet.
  • Deprecated för funktionalitet som snart tas bort.
  • Removed för nu borttagen funktionalitet.
  • Fixed för alla buggfixar
  • Security i fall av sårbarheter.

Hur kan jag minimera den insats som krävs för att underhålla en ändringslogg?

Ha en sektion kallad Unreleased högst upp för att hålla reda på kommande ändringar.

Detta tjänar två syften:

  • Folk kan se vilka ändringar de kan förvänta sig i kommande utgåvor
  • Vid lansering behöver du bara flytta innehållet i sektionen Unreleased till en ny versionspost.

Kan ändringsloggar vara dåliga?

Ja, här är några exempel på då de är mindre användbara.

Diffar från incheckningsloggen.

Det är en dålig idé att använda incheckningsloggen som ändringslogg: de är fulla av brus. Saker så som merge-incheckningar, incheckningar med otydliga titlar, dokumentationsförändringar etc.

Syftet med en incheckning är att dokumentera ett steg i utvecklingen av källkoden. Vissa projekt städar upp bland incheckningarna, andra inte.

Syftet med en post i en ändringslogg är att dokumentera den noterbara skillnaden, oftast över flera incheckningar, för att kommunicera dessa tydligt till slutanvändaren.

Ignorera föråldrad funktionalitet (deprecations)

När användare uppgraderar från en version till en annan, ska det vara smärtsamt uppenbart när något förväntas gå sönder. Den bör vara möjligt att uppgradera till en version som listar föråldrad funktionalitet, ta bort dessa beroenden i sitt program, och sedan uppgradera till en version där den föråldrade funktionaliteten är borttagen.

Om du inte gör något annat, lista åtminstone föråldrad och borttagen funktionalitet samt förstörande förändringar i din ändringslogg.

Förvillande datum

Lokala datumformat varierar över hela världen, och det är ofta svårt att hitta ett användbart datumformat som känns intuitivt för alla. Fördelen med datumformat så som 2017-07-17 är att det följer storleksordningen från störst till minst: år, månad och dag. Detta format överlappar inte heller på ett tvetydligt sätt med andra datumformat, till skillnad från lokala format som kan växla positionen på månad och dag. Dessa anledningar tillsammans med det faktum att detta datumformat är en ISO-standard, gör att detta är rekommenderat format för ändringsloggar.

Vanliga frågor

Finns det ett standardformat på ändringsloggar?

Inte riktigt. GNU:s stilguide för ändringsloggar och den två stycke långa GNU NEWS-filen med "riktlinjer" finns. Båda är bristfälliga och otillräckliga.

Detta projekt har som mål att bli en bättre konvention för ändringsloggar. Det utgår från uppenbart goda praxis från öppen källkods-världen och sammanför dem.

Konstruktiv kritik, diskussion och förslag till förbättring är välkommen.

Vad bör filen med ändringsloggen heta?

Döp den till CHANGELOG.md. En del projekt använder HISTORY, NEWS eller RELEASES.

Även om det är lätt att tänka att det inte spelar så stor roll vad filen med ändringsloggar kallas, varför göra det svårare för dina slutanvändare att enkelt hitta de viktigaste ändringarna?

Hur är det med GitHub Releases?

Det är ett fantasiskt initiativ. Releases kan användas för att göra enkla git-taggar (t.ex. en tagg kallad v1.0.0) till formaterade versionsanteckningar genom att manuellt lägga till versionsanteckningar eller så kan den hämta meddelandena i kommenterade git-taggar och omvandla dessa till versionsanteckningar.

GitHub Releases skapar en icke porterbar ändringslogg som enbart kan visas för användare på GitHub. Det är möjligt att formatera det ungefär som på För en ändringslogg-formatet, men det tendera att bli lite mer invecklat.

Nuvarande version av GitHub releases är möjligtvis också lite svår att hitta för slutanvändare, till skillnad från filer med normalt stora bokstäver (README, CONTRIBUTING, etc.). Ett annat bekymmer är att användargränssnittet för närvarande inte erbjuder länkar till incheckningsloggar mellan olika versioner.

Kan ändringsloggar bli automatiskt tolkade?

Det är svårt då människor följer vitt olika format och filnamn.

Vandamme är en Ruby gem skapad av gruppen Gemnasium som tolkar många (men inte alla) ändringsloggar för öppen källkod.

Hur är det med återtagna utgåvor ("yanked")?

Återtagna utgåvor är versioner som måste tas tillbaka på grund av allvarliga buggar eller säkerhetsproblem. Oftast brukar dessa versioner inte ens finnas med i ändringsloggarna. De borde det. Så här borde du visa dem:

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

Taggen [YANKED] står ut av en anledning, det är viktigt att folk se det. Då den är omsluten med hakparenteser är det också lättare för ett program att tolka det.

Borde du någonsin förändra en ändringslogg?

Självklart. Det finns alltid en bra anledning att förbättra en ändringslogg. Jag öppnar regelbundet pull requests för att lägga till saknade utgåvor för öppna källkodsprojekt som inte tar hand om sin ändringslogg.

Det kan också hända att du upptäcker att du glömt att ta upp en icke bakåtkompatibel förändring i en version. I sådana fall är det självklart viktigt att uppdatera din ändringslogg.

Hur kan jag bidra?

Detta dokument är inte sanningen, det är en noga övervägd åsikt tillsammans med information och exempel jag har samlat på mig.

Detta beror på att jag vill att vår gemenskap ska nå enighet. Jag tror på att diskussionen är lika viktig som slutresultatet.

Så tveka inte att kasta dig in i diskussionen.

Samtal

Jag var med i The Changelog podcast för att prata om varför förvaltare och bidragsgivare bör bry sig om ändringsloggar, och motiveringen bakom detta projekt.

There is a newer version available: Türkçe 1.1.0

CHANGELOG dosyası kullanın

Arkadaşlarınızın, git kayıtlarını CHANGELOG dosyalarına yığmasını engelleyin™

Nedir bu değişiklik kayıtları?

Değişiklik kayıtları bir proje için özel olarak hazırlanmış, tarihsel sıralamayla sıralanmış, önemli değişikliklerin bir bütünüdür.

# 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.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?".

Değişikliklerin kayıtlarını tutmanın anlamı ne?

Bir projenin kullanıcılarının ya da katılımcılarının, dağıtımlar (ya da sürümler) arasındaki tam olarak hangi önemli değişikliklerin olduğunu takip edebilmelerini sağlar.

Neden umrumda olsun ki?

Çünkü yazılım paketleri insanlar içindir. Eğer umrunuzda değilse neden açık kaynağa katkıda bulunuyorsunuz ki? Mutlaka sevimli beyninizin bir yerlerinde bunu önemseyen bir çekirdek (a-ha!) vardır.

Adam Stacoviak ve Jerod Santo ile Changelog Podcast'inde (uyuyor, değil mi?) neden geliştiricilerin ve katılımcıların umrunda olması gerektiğini ve bu projenin arkasındaki motivasyonu konuştuk. Eğer vaktiniz varsa (1:06) iyi bir söyleşi oldu.

Bir değişiklik kaydını iyi yapan nedir?

Bunu sorduğunuza sevindim.

İyi bir değişiklik kaydı şu prensiplere bağlıdır:

Gerekli çabayı nasıl en aza indirebilirim?

Her zaman en üstte değişiklikleri takip ettiğiniz bir "Yayımlanmadı" bölümü olsun.

Bu, iki amaca hizmet eder:

Tek boynuzlu atları ağlatan ne?

Peki… Gelelim sadede.

Dahası da var. Bu tek boynuzlu at gözyaşlarını toplamak için bir başlık açın ya da bir çekme isteği (pull request) gönderin.

Standart bir değişiklik kaydı biçimi var mı?

Ne yazık ki hayır. Sakin olun. Biliyorum, şu an alelacele GNU değişiklik kaydı stil rehberi için bağlantı arıyorsunuz, ya da iki paragraflık GNU NEWS dosyasına bakınıyorsunuz. GNU stil rehberi iyi bir başlangıç fakat üzücü derece naif. Naif olmakta yanlış bir şey yok, fakat insanlar rehberlik aradığında nadiren yardımcı oluyorlar. Özellikle ortada uğraşılacak bir çok durum ve uç örnekler mevcutken.

Bu proje umuyorum ki daha iyi CHANGELOG dosyaları için bir altyapı oluşturacak. Mevcut durumun çok iyi olduğunu düşünmüyorum, ve topluluk olarak, gerçek yazılım projelerinden iyi pratikleri toplayarak bundan daha iyisini yapabiliriz. Lütfen etrafa bir göz gezdirin ve unutmayın gelişme yolunda tartışmalara ve önerilere her zaman açığız!

Değişiklik kayıtlarının dosya ismi ne olmalı?

Eh, üstteki örnekten çıkartamadıysanız eğer, CHANGELOG.md şu ana kadarki en iyi çözüm.

Bazı projeler HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md vb de kullanıyor.

Tam bir karmaşa. Tüm bu isimler insanların bu dosyayı bulmasını zorlaştırıyor.

Neden git log farkları kullanılmasın?

Çünkü kayıt farkları bir sürü parazit içerir - doğal olarak. Mükemmel insanlar tarafından yürütülen, hiç yazım hatasının yapılmadığı, dosyaların gönderilmesinin hiç unutulmadığı, refaktör yapılmasının atlanmadığı varsayımsal bir projede bile, uygun bir değişiklik kaydı oluşmayacaktır. Dosyaları repoya göndermenin amacı, atomik seviyede kodun bir durumdan diğerine geçişinin sağlanmasıdır. Değişiklik kayıtları ise, bu durumlar arasında önem arz eden değişiklikleri belgelemeyi amaçlıyor.

İyi yorumlar ve kodun kendisi arasındaki fark, aynı şekilde değişiklik kayıtları ve commit kayıtları arasındaki gibidir: biri neden olduğunu, diğeri nasıl olduğunu açıklar.

Değişiklik kayıtları otomatik olarak toplanabilir mi?

Zor, çünkü insanlar bir çok farklı biçim ve dosya isimleri kullanıyorlar.

Vandamme, Gemnasium ekibi tarafından oluşturulmuş bir Ruby Gem'idir ve bir çok (hepsini değil) açık kaynaklı projenin değişiklik kayıtlarını ayrıştırabiliyor.

Neden arada bir "CHANGELOG" ve arada bir "değişiklik kaydı" yazıyorsun?

"CHANGELOG" dosyanın ismi. Biraz fazla şaşalı ama bir çok açık kaynak kodlu proje tarafından uygulanan tarihi bir gelenek. Benzer dosyalar da var; README, LICENSE, ve CONTRIBUTING.

Büyük harfle isimlendirme (eski işletim sistemlerinde dosyaların tepede gözükmelerini sağlardı) dikkat çekmek için. Proje hakkında önemli meta verileri içerdikleri için, kullanmak ya da katkıda bulunmak isteyen herkesin işine yarar, tıpkı açık kaynaklı proje rozetleri gibi.

"Değişiklik kaydı"ndan bahsettiğim zamanlar bu dosyanın işlevinden bahsediyorum: Değişiklikleri kaydetmek.

Peki ya Geri çekilen dağıtımlar?

Geri çekilen dağıtımlar, önemli hatalar ya da güvenlik sebepleri nedeniyle yayından geri çekilen sürümlerdir. Genelde bu sürümler değişiklik kayıtlarında görüntülenmezler. Görünmeliler. Tam da şu şekilde görünmeliler:

## 0.0.5 - 2014-12-13 [GERİ ÇEKİLDİ]

[GERİ ÇEKİLDİ] etiketi belirli bir sebepten büyük harf. İnsanların bunu fark etmeleri çok önemli. Ayrıca köşeli parantezler ile çevrelenmiş olması programatik olarak da ayrıştırılabilmesine olanak sağlıyor.

Değişiklik kayıtlarınızı tekrar yazmalı mısınız?

Tabii ki. Her zaman değişiklik kayıtlarını geliştirmek için iyi sebepler vardır. Düzenli olarak açık kaynaklı projelerde bakım yapılmayan değişiklik kayıtları için çekme istekleri yapıyorum.

Ayrıca bir sürümdeki notların arasında önemli bir değişiklikten bahsetmeyi unutmuş olduğunuzu fark edebilirsiniz. Değişiklik kayıtlarınızı bu bilgi ışığında güncellemeniz gerektiği gün gibi ortada.

Nasıl katkıda bulunabilirim?

Bu belge doğrunun kendisi değil; benim hesaplı görüşlerimdir. Beraberinde toparlamış olduğum bilgiler ve örnekler bulunur. GitHub reposunda güncel bir CHANGELOG sağlıyor olsam da, özellikle bir sürüm ya da (SemVer.org benzeri) takip edilecek kurallar oluşturmadım.

Bunu istememin sebebi topluluğun ortak bir paydada buluşmasını istememdir. İnanıyorum ki tartışmanın kendisi de sonucu kadar önemli.

Yani lütfen, siz de katılın.

There is a newer version available: Türkçe 1.1.0

CHANGELOG dosyası kullanın

Arkadaşlarınızın, git kayıtlarını CHANGELOG dosyalarına yığmasını engelleyin™

Nedir bu değişiklik kayıtları?

Değişiklik kayıtları bir proje için özel olarak hazırlanmış, tarihsel sıralamayla sıralanmış, önemli değişikliklerin bir bütünüdür.

# 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.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?".

Değişikliklerin kayıtlarını tutmanın anlamı ne?

Bir projenin kullanıcılarının ya da katılımcılarının, dağıtımlar (ya da sürümler) arasındaki tam olarak hangi önemli değişikliklerin olduğunu takip edebilmelerini sağlar.

Neden umrumda olsun ki?

Çünkü yazılım paketleri insanlar içindir. Eğer umrunuzda değilse neden açık kaynağa katkıda bulunuyorsunuz ki? Mutlaka sevimli beyninizin bir yerlerinde bunu önemseyen bir çekirdek (a-ha!) vardır.

Adam Stacoviak ve Jerod Santo ile Changelog Podcast'inde (uyuyor, değil mi?) neden geliştiricilerin ve katılımcıların umrunda olması gerektiğini ve bu projenin arkasındaki motivasyonu konuştuk. Eğer vaktiniz varsa (1:06) iyi bir söyleşi oldu.

Bir değişiklik kaydını iyi yapan nedir?

Bunu sorduğunuza sevindim.

İyi bir değişiklik kaydı şu prensiplere bağlıdır:

Gerekli çabayı nasıl en aza indirebilirim?

Her zaman en üstte değişiklikleri takip ettiğiniz bir "Yayımlanmadı" bölümü olsun.

Bu, iki amaca hizmet eder:

Tek boynuzlu atları ağlatan ne?

Peki… Gelelim sadede.

Dahası da var. Bu tek boynuzlu at gözyaşlarını toplamak için bir başlık açın ya da bir çekme isteği (pull request) gönderin.

Standart bir değişiklik kaydı biçimi var mı?

Ne yazık ki hayır. Sakin olun. Biliyorum, şu an alelacele GNU değişiklik kaydı stil rehberi için bağlantı arıyorsunuz, ya da iki paragraflık GNU NEWS dosyasına bakınıyorsunuz. GNU stil rehberi iyi bir başlangıç fakat üzücü derece naif. Naif olmakta yanlış bir şey yok, fakat insanlar rehberlik aradığında nadiren yardımcı oluyorlar. Özellikle ortada uğraşılacak bir çok durum ve uç örnekler mevcutken.

Bu proje umuyorum ki daha iyi CHANGELOG dosyaları için bir altyapı oluşturacak. Mevcut durumun çok iyi olduğunu düşünmüyorum, ve topluluk olarak, gerçek yazılım projelerinden iyi pratikleri toplayarak bundan daha iyisini yapabiliriz. Lütfen etrafa bir göz gezdirin ve unutmayın gelişme yolunda tartışmalara ve önerilere her zaman açığız!

Değişiklik kayıtlarının dosya ismi ne olmalı?

Eh, üstteki örnekten çıkartamadıysanız eğer, CHANGELOG.md şu ana kadarki en iyi çözüm.

Bazı projeler HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md vb de kullanıyor.

Tam bir karmaşa. Tüm bu isimler insanların bu dosyayı bulmasını zorlaştırıyor.

Neden git log farkları kullanılmasın?

Çünkü kayıt farkları bir sürü parazit içerir - doğal olarak. Mükemmel insanlar tarafından yürütülen, hiç yazım hatasının yapılmadığı, dosyaların gönderilmesinin hiç unutulmadığı, refaktör yapılmasının atlanmadığı varsayımsal bir projede bile, uygun bir değişiklik kaydı oluşmayacaktır. Dosyaları repoya göndermenin amacı, atomik seviyede kodun bir durumdan diğerine geçişinin sağlanmasıdır. Değişiklik kayıtları ise, bu durumlar arasında önem arz eden değişiklikleri belgelemeyi amaçlıyor.

İyi yorumlar ve kodun kendisi arasındaki fark, aynı şekilde değişiklik kayıtları ve commit kayıtları arasındaki gibidir: biri neden olduğunu, diğeri nasıl olduğunu açıklar.

Değişiklik kayıtları otomatik olarak toplanabilir mi?

Zor, çünkü insanlar bir çok farklı biçim ve dosya isimleri kullanıyorlar.

Vandamme, Gemnasium ekibi tarafından oluşturulmuş bir Ruby Gem'idir ve bir çok (hepsini değil) açık kaynaklı projenin değişiklik kayıtlarını ayrıştırabiliyor.

Neden arada bir "CHANGELOG" ve arada bir "değişiklik kaydı" yazıyorsun?

"CHANGELOG" dosyanın ismi. Biraz fazla şaşalı ama bir çok açık kaynak kodlu proje tarafından uygulanan tarihi bir gelenek. Benzer dosyalar da var; README, LICENSE, ve CONTRIBUTING.

Büyük harfle isimlendirme (eski işletim sistemlerinde dosyaların tepede gözükmelerini sağlardı) dikkat çekmek için. Proje hakkında önemli meta verileri içerdikleri için, kullanmak ya da katkıda bulunmak isteyen herkesin işine yarar, tıpkı açık kaynaklı proje rozetleri gibi.

"Değişiklik kaydı"ndan bahsettiğim zamanlar bu dosyanın işlevinden bahsediyorum: Değişiklikleri kaydetmek.

Peki ya Geri çekilen dağıtımlar?

Geri çekilen dağıtımlar, önemli hatalar ya da güvenlik sebepleri nedeniyle yayından geri çekilen sürümlerdir. Genelde bu sürümler değişiklik kayıtlarında görüntülenmezler. Görünmeliler. Tam da şu şekilde görünmeliler:

## 0.0.5 - 2014-12-13 [GERİ ÇEKİLDİ]

[GERİ ÇEKİLDİ] etiketi belirli bir sebepten büyük harf. İnsanların bunu fark etmeleri çok önemli. Ayrıca köşeli parantezler ile çevrelenmiş olması programatik olarak da ayrıştırılabilmesine olanak sağlıyor.

Değişiklik kayıtlarınızı tekrar yazmalı mısınız?

Tabii ki. Her zaman değişiklik kayıtlarını geliştirmek için iyi sebepler vardır. Düzenli olarak açık kaynaklı projelerde bakım yapılmayan değişiklik kayıtları için çekme istekleri yapıyorum.

Ayrıca bir sürümdeki notların arasında önemli bir değişiklikten bahsetmeyi unutmuş olduğunuzu fark edebilirsiniz. Değişiklik kayıtlarınızı bu bilgi ışığında güncellemeniz gerektiği gün gibi ortada.

Nasıl katkıda bulunabilirim?

Bu belge doğrunun kendisi değil; benim hesaplı görüşlerimdir. Beraberinde toparlamış olduğum bilgiler ve örnekler bulunur. GitHub reposunda güncel bir CHANGELOG sağlıyor olsam da, özellikle bir sürüm ya da (SemVer.org benzeri) takip edilecek kurallar oluşturmadım.

Bunu istememin sebebi topluluğun ortak bir paydada buluşmasını istememdir. İnanıyorum ki tartışmanın kendisi de sonucu kadar önemli.

Yani lütfen, siz de katılın.

There is a newer version available: Türkçe 1.1.0

Değişiklik kayıtları tutun

Arkadaşlarınızın, git mesajlarını değişiklik kayıtlarına yığmasını engelleyin.

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

## [Unreleased]

## [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

Nedir bu değişiklik kayıtları?

Değişiklik kayıtları bir proje için özel olarak hazırlanmış, tarihsel sıralamayla sıralanmış, önemli değişikliklerin bir bütünüdür.

Değişikliklerin kayıtlarını tutmanın anlamı ne?

Bir projenin kullanıcılarının ya da katılımcılarının, dağıtımlar (ya da sürümler) arasındaki tam olarak hangi önemli değişikliklerin olduğunu takip edebilmelerini sağlar.

Kim değişiklik kayıtlarına ihtiyaç duyar ki?

İnsanlar. İster tüketici olsun, ister geliştirici, kullanılan yazılımın son kullanıcıları, o yazılımın içinde ne olduğunu önemseyen kişilerdir. Yazılım değiştiğinde, insanlar neden ve nasıl olduğunu bilmek isterler.

Nası iyi değişiklik kayıtları tutarım?

Rehber prensipler

  • Değişiklik kayıtları insanlar içindir, makineler için değil.
  • Her sürüm için bir girdi içermelidir.
  • Benzer değişiklikler gruplanmalıdır.
  • Sürümler ve bölümlere bağlantı verilebilir olmalıdır.
  • En son sürüm ilk başta olmalıdır.
  • Her sürümün dağıtım tarihi bulunmalıdır.
  • Geliştirirken anlamlı sürümlendirme (Semver) kullanıp kullanmadığınızı bildirin.

Değişiklik tipleri

  • Eklendi : Yeni özellikler için.
  • Değişti : Var olan becerilerde yapılan değişiklikler için.
  • Rafa kalktı : Gelecekte yok olacak beceriler için.
  • Kaldırıldı : Kaldırılan beceriler için.
  • Düzeltildi : Ayıklanmış hatalar için.
  • Güvenlik : Bir güvenlik açığı söz konusuysa.

Gerekli çabayı nasıl en aza indirebilirim?

Her zaman en üstte, değişiklikleri takip ettiğiniz bir Yayımlanmadı bölümü olsun

Bu, iki amaca hizmet eder:

  • İnsanlar gelecek sürümlerde karşılarına ne gibi değişiklikler çıkacağını görebilirler
  • Dağıtım zamanı geldiğinde Yayımlanmadı bölümünü yeni dağıtım sürümü bölümü olarak kullanabilirsiniz.

Değişiklik kütükleri kötü olabilirler mi?

Evet. Buyrun size işe yaramayacak bir kaç örnek;

Commit kayıtlarının farkları

Değişiklik kayıtları için commit kayıtlarının farklarını kullanmak kötü bir fikirdir: genellikle çok gürültülü olurlar. Commit birleşmeleri, kötü başlıklı commitler, belgeleme değişiklikleri vb.

Bir commit yapılmasının sebebi, kodun bir sonraki aşamaya evrilmesidir. Bazı projeler commitleri temizler, bazıları temizlemez.

Değişiklik kayıtlarına eklenen bir girdi ise, öneme sahip bir değişikliğin belgelenmesi amaçlıdır. Genelde bir çok commit işlemini kapsar ve son kullanıcıyla iletişimi açık tutar.

Rafa kalkanları göz ardı etmek

İnsanlar bir sürümden diğerine yükselttiklerinde, bir şeylerin bozulup bozulmayacağı acı verici derecede açık olmalıdır. Rafa kalkan özelliklerin listelendiği sürüme geçip, bu rafa kaldırılanlara yönelik kendi geliştirmelerini yaparak, en nihayetinde özelliklerin tamamen kaldırıldığı sürüme geçiş yapabilmeliler.

Eğer hiç bir şey yapmasanız bile, rafa kalkanları, kaldırılanları ve önemli değişiklikleri, değişiklik kayıtlarınızda listeleyin.

Kafa karıştırıcı tarihler

A.B.D.'de insanlar ay kısmını önce kullanırken (2 Haziran 2012 için 06-02-2012), dünyanın bir çok bölümünde daha robotik bir kullanım 2 Haziran 2012 söz konusu. 2012-06-02 biçimi en küçüğünden en büyüğüne tüm biçimlerle çakışmadan kullanılabiliyor ve aynı zamanda bir ISO standardı. Bu sebeple değişiklik kayıtları için önerilen tarih biçimidir.

Sıkça sorulan sorular

Standart bir değişiklik kayıt biçimi var mı?

Pek sayılmaz. GNU değişiklik kayıtları stil rehberi mevcut ya da iki paragraflık GNU NEWS "rehber" dosyası var. İkisi de uygun değiller ve yetersizler.

Bu proje daha iyi bir değişiklik kayıtları düzeni oluşturmaya çalışıyor. Bunun için de açık kaynaklı topluluklardaki en iyi kullanımları inceleyip, topluyoruz.

Sağlıklı eleştiriler, tartışmalar ve öneriler, projenin gelişmesi için her zaman hoş karşılanır.

Değişiklik kayıtları dosyasının ismi ne olmalı?

İsterseniz CHANGELOG.md olarak isimlendirin. Bazı projeler HISTORY, NEWS ya da RELEASES kullanıyor.

Dosya isminin çok da önemli olmadığını düşünebilirsiniz, fakat neden kullanıcılarınızın değişiklikleri takip edebilmesi için onların işlerini zorlaştırasınız ki?

Peki ya GitHub dağıtımları?

Harika bir girişim. Dağıtımlar içine kendiniz değişiklik kayıtları eklerseniz basit git etiketlerini (örneğin v1.0.0) zengin dağıtım notlarına çevirebilir ya da notlar eklenmiş git etiketlerinden oluşturulabilirsiniz.

GtHub dağıtımları sadece GitHub içeriğinde görüntülenebilecek, taşınamaz değişiklik kayıtları oluşturur. Biraz emek harcayarak "Değişiklik kayıtları tutun" biçimine uygun hale getirilebilir.

Ayrıca GitHub dağıtımlarının şu anki hali son kullanıcılar tarafından çok kolay bulunabilir değil. Tipik büyük harfli dosyalar (README, CONTRIBUTING, vb.) daha çok göze çarpıyor. Bir başka konu da, mevcut arayüz her dağıtım arasındaki commit kayıtlarına bağlantı vermeye izin vermiyor..

Değişiklik kayıtları otomatik olarak toplanabilir mi?

Zor, çünkü insanlar bir çok farklı biçim ve dosya isimleri kullanıyorlar.

Vandamme, Gemnasium ekibi tarafından oluşturulmuş bir Ruby Gem'i ve bir çok (ama hepsi değil) açık kaynak projenin değişiklik kayıtlarını okuyabiliyor.

Peki ya geri çekilen dağıtımlar?

Geri çekilen dağıtımlar, önemli hatalar ya da güvenlik sebepleri nedeniyle yayından geri çekilen sürümlerdir. Genelde bu sürümler değişiklik kayıtlarında görüntülenmezler. Görünmeliler. Tam da şu şekilde görünmeliler:

## 0.0.5 - 2014-12-13 [GERİ ÇEKİLDİ]

[GERİ ÇEKİLDİ] etiketi belirli bir sebepten büyük harf. İnsanların bunu fark etmeleri çok önemli. Ayrıca köşeli parantezler ile çevrelenmiş olması programatik olarak da ayrıştırılabilmesine olanak sağlıyor.

Değişiklik kayıtlarınızı tekrar yazmalı mısınız?

Tabii ki. Her zaman değişiklik kayıtlarını geliştirmek için iyi sebepler vardır. Düzenli olarak açık kaynaklı projelerde bakım yapılmayan değişiklik kayıtları için çekme istekleri yapıyorum.

Ayrıca bir sürümdeki notların arasında önemli bir değişiklikten bahsetmeyi unutmuş olduğunuzu fark edebilirsiniz. Değişiklik kayıtlarınızı bu bilgi ışığında güncellemeniz gerektiği gün gibi ortada.

Nasıl katkıda bulunabilirim?

Bu belge doğrunun kendisi değil; benim ince eleyip sık dokuduğum görüşlerimdir. Beraberinde toparlamış olduğum bilgiler ve örnekler bulunur.

Burada yapmaya çalıştığım topluluğun ortak bir paydada buluşmasını sağlamak. İnanıyorum ki tartışmanın kendisi de sonucu kadar önemli.

Yani lütfen, siz de katılın.

Sohbetler

Geliştiricilerin ve katkıda bulunanların neden değişiklik kayıtlarını dikkate almaları gerekliliğini ve bu projenin arkasındaki motivasyonu anlattığım Değişiklik Kayıtları podcast'ini inceleyebilirsiniz.

There is a newer version available: Türkçe 1.1.0

Değişiklik kayıtları tutun

Arkadaşlarınızın, git mesajlarını değişiklik kayıtlarına yığmasını engelleyin.

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

## [Unreleased]

## [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

Nedir bu değişiklik kayıtları?

Değişiklik kayıtları bir proje için özel olarak hazırlanmış, tarihsel sıralamayla sıralanmış, önemli değişikliklerin bir bütünüdür.

Değişikliklerin kayıtlarını tutmanın anlamı ne?

Bir projenin kullanıcılarının ya da katılımcılarının, dağıtımlar (ya da sürümler) arasındaki tam olarak hangi önemli değişikliklerin olduğunu takip edebilmelerini sağlar.

Kim değişiklik kayıtlarına ihtiyaç duyar ki?

İnsanlar. İster tüketici olsun, ister geliştirici, kullanılan yazılımın son kullanıcıları, o yazılımın içinde ne olduğunu önemseyen kişilerdir. Yazılım değiştiğinde, insanlar neden ve nasıl olduğunu bilmek isterler.

Nası iyi değişiklik kayıtları tutarım?

Rehber prensipler

  • Değişiklik kayıtları insanlar içindir, makineler için değil.
  • Her sürüm için bir girdi içermelidir.
  • Benzer değişiklikler gruplanmalıdır.
  • Sürümler ve bölümlere bağlantı verilebilir olmalıdır.
  • En son sürüm ilk başta olmalıdır.
  • Her sürümün dağıtım tarihi bulunmalıdır.
  • Geliştirirken anlamlı sürümlendirme (Semver) kullanıp kullanmadığınızı bildirin.

Değişiklik tipleri

  • Eklendi : Yeni özellikler için.
  • Değişti : Var olan becerilerde yapılan değişiklikler için.
  • Rafa kalktı : Gelecekte yok olacak beceriler için.
  • Kaldırıldı : Kaldırılan beceriler için.
  • Düzeltildi : Ayıklanmış hatalar için.
  • Güvenlik : Bir güvenlik açığı söz konusuysa.

Gerekli çabayı nasıl en aza indirebilirim?

Her zaman en üstte, değişiklikleri takip ettiğiniz bir Yayımlanmadı bölümü olsun

Bu, iki amaca hizmet eder:

  • İnsanlar gelecek sürümlerde karşılarına ne gibi değişiklikler çıkacağını görebilirler
  • Dağıtım zamanı geldiğinde Yayımlanmadı bölümünü yeni dağıtım sürümü bölümü olarak kullanabilirsiniz.

Değişiklik kütükleri kötü olabilirler mi?

Evet. Buyrun size işe yaramayacak bir kaç örnek;

Commit kayıtlarının farkları

Değişiklik kayıtları için commit kayıtlarının farklarını kullanmak kötü bir fikirdir: genellikle çok gürültülü olurlar. Commit birleşmeleri, kötü başlıklı commitler, belgeleme değişiklikleri vb.

Bir commit yapılmasının sebebi, kodun bir sonraki aşamaya evrilmesidir. Bazı projeler commitleri temizler, bazıları temizlemez.

Değişiklik kayıtlarına eklenen bir girdi ise, öneme sahip bir değişikliğin belgelenmesi amaçlıdır. Genelde bir çok commit işlemini kapsar ve son kullanıcıyla iletişimi açık tutar.

Rafa kalkanları göz ardı etmek

İnsanlar bir sürümden diğerine yükselttiklerinde, bir şeylerin bozulup bozulmayacağı acı verici derecede açık olmalıdır. Rafa kalkan özelliklerin listelendiği sürüme geçip, bu rafa kaldırılanlara yönelik kendi geliştirmelerini yaparak, en nihayetinde özelliklerin tamamen kaldırıldığı sürüme geçiş yapabilmeliler.

Eğer hiç bir şey yapmasanız bile, rafa kalkanları, kaldırılanları ve önemli değişiklikleri, değişiklik kayıtlarınızda listeleyin.

Kafa karıştırıcı tarihler

A.B.D.'de insanlar ay kısmını önce kullanırken (2 Haziran 2012 için 06-02-2012), dünyanın bir çok bölümünde daha robotik bir kullanım 2 Haziran 2012 söz konusu. 2012-06-02 biçimi en küçüğünden en büyüğüne tüm biçimlerle çakışmadan kullanılabiliyor ve aynı zamanda bir ISO standardı. Bu sebeple değişiklik kayıtları için önerilen tarih biçimidir.

Sıkça sorulan sorular

Standart bir değişiklik kayıt biçimi var mı?

Pek sayılmaz. GNU değişiklik kayıtları stil rehberi mevcut ya da iki paragraflık GNU NEWS "rehber" dosyası var. İkisi de uygun değiller ve yetersizler.

Bu proje daha iyi bir değişiklik kayıtları düzeni oluşturmaya çalışıyor. Bunun için de açık kaynaklı topluluklardaki en iyi kullanımları inceleyip, topluyoruz.

Sağlıklı eleştiriler, tartışmalar ve öneriler, projenin gelişmesi için her zaman hoş karşılanır.

Değişiklik kayıtları dosyasının ismi ne olmalı?

İsterseniz CHANGELOG.md olarak isimlendirin. Bazı projeler HISTORY, NEWS ya da RELEASES kullanıyor.

Dosya isminin çok da önemli olmadığını düşünebilirsiniz, fakat neden kullanıcılarınızın değişiklikleri takip edebilmesi için onların işlerini zorlaştırasınız ki?

Peki ya GitHub dağıtımları?

Harika bir girişim. Dağıtımlar içine kendiniz değişiklik kayıtları eklerseniz basit git etiketlerini (örneğin v1.0.0) zengin dağıtım notlarına çevirebilir ya da notlar eklenmiş git etiketlerinden oluşturulabilirsiniz.

GtHub dağıtımları sadece GitHub içeriğinde görüntülenebilecek, taşınamaz değişiklik kayıtları oluşturur. Biraz emek harcayarak "Değişiklik kayıtları tutun" biçimine uygun hale getirilebilir.

Ayrıca GitHub dağıtımlarının şu anki hali son kullanıcılar tarafından çok kolay bulunabilir değil. Tipik büyük harfli dosyalar (README, CONTRIBUTING, vb.) daha çok göze çarpıyor. Bir başka konu da, mevcut arayüz her dağıtım arasındaki commit kayıtlarına bağlantı vermeye izin vermiyor..

Değişiklik kayıtları otomatik olarak toplanabilir mi?

Zor, çünkü insanlar bir çok farklı biçim ve dosya isimleri kullanıyorlar.

Vandamme, Gemnasium ekibi tarafından oluşturulmuş bir Ruby Gem'i ve bir çok (ama hepsi değil) açık kaynak projenin değişiklik kayıtlarını okuyabiliyor.

Peki ya geri çekilen dağıtımlar?

Geri çekilen dağıtımlar, önemli hatalar ya da güvenlik sebepleri nedeniyle yayından geri çekilen sürümlerdir. Genelde bu sürümler değişiklik kayıtlarında görüntülenmezler. Görünmeliler. Tam da şu şekilde görünmeliler:

## 0.0.5 - 2014-12-13 [GERİ ÇEKİLDİ]

[GERİ ÇEKİLDİ] etiketi belirli bir sebepten büyük harf. İnsanların bunu fark etmeleri çok önemli. Ayrıca köşeli parantezler ile çevrelenmiş olması programatik olarak da ayrıştırılabilmesine olanak sağlıyor.

Değişiklik kayıtlarınızı tekrar yazmalı mısınız?

Tabii ki. Her zaman değişiklik kayıtlarını geliştirmek için iyi sebepler vardır. Düzenli olarak açık kaynaklı projelerde bakım yapılmayan değişiklik kayıtları için çekme istekleri yapıyorum.

Ayrıca bir sürümdeki notların arasında önemli bir değişiklikten bahsetmeyi unutmuş olduğunuzu fark edebilirsiniz. Değişiklik kayıtlarınızı bu bilgi ışığında güncellemeniz gerektiği gün gibi ortada.

Nasıl katkıda bulunabilirim?

Bu belge doğrunun kendisi değil; benim ince eleyip sık dokuduğum görüşlerimdir. Beraberinde toparlamış olduğum bilgiler ve örnekler bulunur.

Burada yapmaya çalıştığım topluluğun ortak bir paydada buluşmasını sağlamak. İnanıyorum ki tartışmanın kendisi de sonucu kadar önemli.

Yani lütfen, siz de katılın.

Sohbetler

Geliştiricilerin ve katkıda bulunanların neden değişiklik kayıtlarını dikkate almaları gerekliliğini ve bu projenin arkasındaki motivasyonu anlattığım Değişiklik Kayıtları podcast'ini inceleyebilirsiniz.

Değişiklik kayıtları tutun

Arkadaşlarınızın, git mesajlarını değişiklik kayıtlarına yığmasını engelleyin.

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

## [Unreleased]

## [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

Nedir bu değişiklik kayıtları?

Değişiklik kayıtları bir proje için özel olarak hazırlanmış, tarihsel sıralamayla sıralanmış, önemli değişikliklerin bir bütünüdür.

Değişikliklerin kayıtlarını tutmanın anlamı ne?

Bir projenin kullanıcılarının ya da katılımcılarının, dağıtımlar (ya da sürümler) arasındaki tam olarak hangi önemli değişikliklerin olduğunu takip edebilmelerini sağlar.

Kim değişiklik kayıtlarına ihtiyaç duyar ki?

İnsanlar. İster tüketici olsun, ister geliştirici, kullanılan yazılımın son kullanıcıları, o yazılımın içinde ne olduğunu önemseyen kişilerdir. Yazılım değiştiğinde, insanlar neden ve nasıl olduğunu bilmek isterler.

Nası iyi değişiklik kayıtları tutarım?

Rehber prensipler

  • Değişiklik kayıtları insanlar içindir, makineler için değil.
  • Her sürüm için bir girdi içermelidir.
  • Benzer değişiklikler gruplanmalıdır.
  • Sürümler ve bölümlere bağlantı verilebilir olmalıdır.
  • En son sürüm ilk başta olmalıdır.
  • Her sürümün dağıtım tarihi bulunmalıdır.
  • Geliştirirken anlamlı sürümlendirme (Semver) kullanıp kullanmadığınızı bildirin.

Değişiklik tipleri

  • Eklendi : Yeni özellikler için.
  • Değişti : Var olan becerilerde yapılan değişiklikler için.
  • Rafa kalktı : Gelecekte yok olacak beceriler için.
  • Kaldırıldı : Kaldırılan beceriler için.
  • Düzeltildi : Ayıklanmış hatalar için.
  • Güvenlik : Bir güvenlik açığı söz konusuysa.

Gerekli çabayı nasıl en aza indirebilirim?

Her zaman en üstte, değişiklikleri takip ettiğiniz bir Yayımlanmadı bölümü olsun

Bu, iki amaca hizmet eder:

  • İnsanlar gelecek sürümlerde karşılarına ne gibi değişiklikler çıkacağını görebilirler
  • Dağıtım zamanı geldiğinde Yayımlanmadı bölümünü yeni dağıtım sürümü bölümü olarak kullanabilirsiniz.

Değişiklik kütükleri kötü olabilirler mi?

Evet. Buyrun size işe yaramayacak bir kaç örnek;

Commit kayıtlarının farkları

Değişiklik kayıtları için commit kayıtlarının farklarını kullanmak kötü bir fikirdir: genellikle çok gürültülü olurlar. Commit birleşmeleri, kötü başlıklı commitler, belgeleme değişiklikleri vb.

Bir commit yapılmasının sebebi, kodun bir sonraki aşamaya evrilmesidir. Bazı projeler commitleri temizler, bazıları temizlemez.

Değişiklik kayıtlarına eklenen bir girdi ise, öneme sahip bir değişikliğin belgelenmesi amaçlıdır. Genelde bir çok commit işlemini kapsar ve son kullanıcıyla iletişimi açık tutar.

Rafa kalkanları göz ardı etmek

İnsanlar bir sürümden diğerine yükselttiklerinde, bir şeylerin bozulup bozulmayacağı acı verici derecede açık olmalıdır. Rafa kalkan özelliklerin listelendiği sürüme geçip, bu rafa kaldırılanlara yönelik kendi geliştirmelerini yaparak, en nihayetinde özelliklerin tamamen kaldırıldığı sürüme geçiş yapabilmeliler.

Eğer hiç bir şey yapmasanız bile, rafa kalkanları, kaldırılanları ve önemli değişiklikleri, değişiklik kayıtlarınızda listeleyin.

Kafa karıştırıcı tarihler

A.B.D.'de insanlar ay kısmını önce kullanırken (2 Haziran 2012 için 06-02-2012), dünyanın bir çok bölümünde daha robotik bir kullanım 2 Haziran 2012 söz konusu. 2012-06-02 biçimi en küçüğünden en büyüğüne tüm biçimlerle çakışmadan kullanılabiliyor ve aynı zamanda bir ISO standardı. Bu sebeple değişiklik kayıtları için önerilen tarih biçimidir.

Tutarsız değişiklikler

Sadece bazı değişiklikleri içeren bir değişiklik kütüğü en az hiç olmaması kadar tehlikelidir. Bir çok değişikliğin kayıt altına alınması gerekmese bile - örneğin tek bir boşluğun kaldırılmasının kayıt altına alınması gerekmeyebilir - her türlü önemli değişiklikten kayıt kütüğünde bahsedilmelidir. Tutarsız bir şekilde değişiklikleri uygulamak, kullanıcıların tek doğrunun sadece değişiklik kütüğünde var olanlar olduğunu sanmasına yol açabilir. Öyle de olmalı. Büyük güç beraberinde büyük sorumluluk getirir - iyi değişiklik kayıtları demek tutarlı bir şekilde güncellenen değişiklik kayıtları demektir.

Sıkça sorulan sorular

Standart bir değişiklik kayıt biçimi var mı?

Pek sayılmaz. GNU değişiklik kayıtları stil rehberi mevcut ya da iki paragraflık GNU NEWS "rehber" dosyası var. İkisi de uygun değiller ve yetersizler.

Bu proje daha iyi bir değişiklik kayıtları düzeni oluşturmaya çalışıyor. Bunun için de açık kaynaklı topluluklardaki en iyi kullanımları inceleyip, topluyoruz.

Sağlıklı eleştiriler, tartışmalar ve öneriler, projenin gelişmesi için her zaman hoş karşılanır.

Değişiklik kayıtları dosyasının ismi ne olmalı?

İsterseniz CHANGELOG.md olarak isimlendirin. Bazı projeler HISTORY, NEWS ya da RELEASES kullanıyor.

Dosya isminin çok da önemli olmadığını düşünebilirsiniz, fakat neden kullanıcılarınızın değişiklikleri takip edebilmesi için onların işlerini zorlaştırasınız ki?

Peki ya GitHub dağıtımları?

Harika bir girişim. Dağıtımlar içine kendiniz değişiklik kayıtları eklerseniz basit git etiketlerini (örneğin v1.0.0) zengin dağıtım notlarına çevirebilir ya da notlar eklenmiş git etiketlerinden oluşturulabilirsiniz.

GtHub dağıtımları sadece GitHub içeriğinde görüntülenebilecek, taşınamaz değişiklik kayıtları oluşturur. Biraz emek harcayarak "Değişiklik kayıtları tutun" biçimine uygun hale getirilebilir.

Ayrıca GitHub dağıtımlarının şu anki hali son kullanıcılar tarafından çok kolay bulunabilir değil. Tipik büyük harfli dosyalar (README, CONTRIBUTING, vb.) daha çok göze çarpıyor. Bir başka konu da, mevcut arayüz her dağıtım arasındaki commit kayıtlarına bağlantı vermeye izin vermiyor..

Değişiklik kayıtları otomatik olarak toplanabilir mi?

Zor, çünkü insanlar bir çok farklı biçim ve dosya isimleri kullanıyorlar.

Vandamme, Gemnasium ekibi tarafından oluşturulmuş bir Ruby Gem'i ve bir çok (ama hepsi değil) açık kaynak projenin değişiklik kayıtlarını okuyabiliyor.

Peki ya geri çekilen dağıtımlar?

Geri çekilen dağıtımlar, önemli hatalar ya da güvenlik sebepleri nedeniyle yayından geri çekilen sürümlerdir. Genelde bu sürümler değişiklik kayıtlarında görüntülenmezler. Görünmeliler. Tam da şu şekilde görünmeliler:

## 0.0.5 - 2014-12-13 [GERİ ÇEKİLDİ]

[GERİ ÇEKİLDİ] etiketi belirli bir sebepten büyük harf. İnsanların bunu fark etmeleri çok önemli. Ayrıca köşeli parantezler ile çevrelenmiş olması programatik olarak da ayrıştırılabilmesine olanak sağlıyor.

Değişiklik kayıtlarınızı tekrar yazmalı mısınız?

Tabii ki. Her zaman değişiklik kayıtlarını geliştirmek için iyi sebepler vardır. Düzenli olarak açık kaynaklı projelerde bakım yapılmayan değişiklik kayıtları için çekme istekleri yapıyorum.

Ayrıca bir sürümdeki notların arasında önemli bir değişiklikten bahsetmeyi unutmuş olduğunuzu fark edebilirsiniz. Değişiklik kayıtlarınızı bu bilgi ışığında güncellemeniz gerektiği gün gibi ortada.

Nasıl katkıda bulunabilirim?

Bu belge doğrunun kendisi değil; benim ince eleyip sık dokuduğum görüşlerimdir. Beraberinde toparlamış olduğum bilgiler ve örnekler bulunur.

Burada yapmaya çalıştığım topluluğun ortak bir paydada buluşmasını sağlamak. İnanıyorum ki tartışmanın kendisi de sonucu kadar önemli.

Yani lütfen, siz de katılın.

Sohbetler

Geliştiricilerin ve katkıda bulunanların neden değişiklik kayıtlarını dikkate almaları gerekliliğini ve bu projenin arkasındaki motivasyonu anlattığım Değişiklik Kayıtları podcast'ini inceleyebilirsiniz.

Değişiklik kayıtları tutun

Arkadaşlarınızın, git mesajlarını değişiklik kayıtlarına yığmasını engelleyin.

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

## [Unreleased]

## [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

Nedir bu değişiklik kayıtları?

Değişiklik kayıtları bir proje için özel olarak hazırlanmış, tarihsel sıralamayla sıralanmış, önemli değişikliklerin bir bütünüdür.

Değişikliklerin kayıtlarını tutmanın anlamı ne?

Bir projenin kullanıcılarının ya da katılımcılarının, dağıtımlar (ya da sürümler) arasındaki tam olarak hangi önemli değişikliklerin olduğunu takip edebilmelerini sağlar.

Kim değişiklik kayıtlarına ihtiyaç duyar ki?

İnsanlar. İster tüketici olsun, ister geliştirici, kullanılan yazılımın son kullanıcıları, o yazılımın içinde ne olduğunu önemseyen kişilerdir. Yazılım değiştiğinde, insanlar neden ve nasıl olduğunu bilmek isterler.

Nası iyi değişiklik kayıtları tutarım?

Rehber prensipler

  • Değişiklik kayıtları insanlar içindir, makineler için değil.
  • Her sürüm için bir girdi içermelidir.
  • Benzer değişiklikler gruplanmalıdır.
  • Sürümler ve bölümlere bağlantı verilebilir olmalıdır.
  • En son sürüm ilk başta olmalıdır.
  • Her sürümün dağıtım tarihi bulunmalıdır.
  • Geliştirirken anlamlı sürümlendirme (Semver) kullanıp kullanmadığınızı bildirin.

Değişiklik tipleri

  • Eklendi : Yeni özellikler için.
  • Değişti : Var olan becerilerde yapılan değişiklikler için.
  • Rafa kalktı : Gelecekte yok olacak beceriler için.
  • Kaldırıldı : Kaldırılan beceriler için.
  • Düzeltildi : Ayıklanmış hatalar için.
  • Güvenlik : Bir güvenlik açığı söz konusuysa.

Gerekli çabayı nasıl en aza indirebilirim?

Her zaman en üstte, değişiklikleri takip ettiğiniz bir Yayımlanmadı bölümü olsun

Bu, iki amaca hizmet eder:

  • İnsanlar gelecek sürümlerde karşılarına ne gibi değişiklikler çıkacağını görebilirler
  • Dağıtım zamanı geldiğinde Yayımlanmadı bölümünü yeni dağıtım sürümü bölümü olarak kullanabilirsiniz.

Değişiklik kütükleri kötü olabilirler mi?

Evet. Buyrun size işe yaramayacak bir kaç örnek;

Commit kayıtlarının farkları

Değişiklik kayıtları için commit kayıtlarının farklarını kullanmak kötü bir fikirdir: genellikle çok gürültülü olurlar. Commit birleşmeleri, kötü başlıklı commitler, belgeleme değişiklikleri vb.

Bir commit yapılmasının sebebi, kodun bir sonraki aşamaya evrilmesidir. Bazı projeler commitleri temizler, bazıları temizlemez.

Değişiklik kayıtlarına eklenen bir girdi ise, öneme sahip bir değişikliğin belgelenmesi amaçlıdır. Genelde bir çok commit işlemini kapsar ve son kullanıcıyla iletişimi açık tutar.

Rafa kalkanları göz ardı etmek

İnsanlar bir sürümden diğerine yükselttiklerinde, bir şeylerin bozulup bozulmayacağı acı verici derecede açık olmalıdır. Rafa kalkan özelliklerin listelendiği sürüme geçip, bu rafa kaldırılanlara yönelik kendi geliştirmelerini yaparak, en nihayetinde özelliklerin tamamen kaldırıldığı sürüme geçiş yapabilmeliler.

Eğer hiç bir şey yapmasanız bile, rafa kalkanları, kaldırılanları ve önemli değişiklikleri, değişiklik kayıtlarınızda listeleyin.

Kafa karıştırıcı tarihler

A.B.D.'de insanlar ay kısmını önce kullanırken (2 Haziran 2012 için 06-02-2012), dünyanın bir çok bölümünde daha robotik bir kullanım 2 Haziran 2012 söz konusu. 2012-06-02 biçimi en küçüğünden en büyüğüne tüm biçimlerle çakışmadan kullanılabiliyor ve aynı zamanda bir ISO standardı. Bu sebeple değişiklik kayıtları için önerilen tarih biçimidir.

Tutarsız değişiklikler

Sadece bazı değişiklikleri içeren bir değişiklik kütüğü en az hiç olmaması kadar tehlikelidir. Bir çok değişikliğin kayıt altına alınması gerekmese bile - örneğin tek bir boşluğun kaldırılmasının kayıt altına alınması gerekmeyebilir - her türlü önemli değişiklikten kayıt kütüğünde bahsedilmelidir. Tutarsız bir şekilde değişiklikleri uygulamak, kullanıcıların tek doğrunun sadece değişiklik kütüğünde var olanlar olduğunu sanmasına yol açabilir. Öyle de olmalı. Büyük güç beraberinde büyük sorumluluk getirir - iyi değişiklik kayıtları demek tutarlı bir şekilde güncellenen değişiklik kayıtları demektir.

Sıkça sorulan sorular

Standart bir değişiklik kayıt biçimi var mı?

Pek sayılmaz. GNU değişiklik kayıtları stil rehberi mevcut ya da iki paragraflık GNU NEWS "rehber" dosyası var. İkisi de uygun değiller ve yetersizler.

Bu proje daha iyi bir değişiklik kayıtları düzeni oluşturmaya çalışıyor. Bunun için de açık kaynaklı topluluklardaki en iyi kullanımları inceleyip, topluyoruz.

Sağlıklı eleştiriler, tartışmalar ve öneriler, projenin gelişmesi için her zaman hoş karşılanır.

Değişiklik kayıtları dosyasının ismi ne olmalı?

İsterseniz CHANGELOG.md olarak isimlendirin. Bazı projeler HISTORY, NEWS ya da RELEASES kullanıyor.

Dosya isminin çok da önemli olmadığını düşünebilirsiniz, fakat neden kullanıcılarınızın değişiklikleri takip edebilmesi için onların işlerini zorlaştırasınız ki?

Peki ya GitHub dağıtımları?

Harika bir girişim. Dağıtımlar içine kendiniz değişiklik kayıtları eklerseniz basit git etiketlerini (örneğin v1.0.0) zengin dağıtım notlarına çevirebilir ya da notlar eklenmiş git etiketlerinden oluşturulabilirsiniz.

GtHub dağıtımları sadece GitHub içeriğinde görüntülenebilecek, taşınamaz değişiklik kayıtları oluşturur. Biraz emek harcayarak "Değişiklik kayıtları tutun" biçimine uygun hale getirilebilir.

Ayrıca GitHub dağıtımlarının şu anki hali son kullanıcılar tarafından çok kolay bulunabilir değil. Tipik büyük harfli dosyalar (README, CONTRIBUTING, vb.) daha çok göze çarpıyor. Bir başka konu da, mevcut arayüz her dağıtım arasındaki commit kayıtlarına bağlantı vermeye izin vermiyor..

Değişiklik kayıtları otomatik olarak toplanabilir mi?

Zor, çünkü insanlar bir çok farklı biçim ve dosya isimleri kullanıyorlar.

Vandamme, Gemnasium ekibi tarafından oluşturulmuş bir Ruby Gem'i ve bir çok (ama hepsi değil) açık kaynak projenin değişiklik kayıtlarını okuyabiliyor.

Peki ya geri çekilen dağıtımlar?

Geri çekilen dağıtımlar, önemli hatalar ya da güvenlik sebepleri nedeniyle yayından geri çekilen sürümlerdir. Genelde bu sürümler değişiklik kayıtlarında görüntülenmezler. Görünmeliler. Tam da şu şekilde görünmeliler:

## 0.0.5 - 2014-12-13 [GERİ ÇEKİLDİ]

[GERİ ÇEKİLDİ] etiketi belirli bir sebepten büyük harf. İnsanların bunu fark etmeleri çok önemli. Ayrıca köşeli parantezler ile çevrelenmiş olması programatik olarak da ayrıştırılabilmesine olanak sağlıyor.

Değişiklik kayıtlarınızı tekrar yazmalı mısınız?

Tabii ki. Her zaman değişiklik kayıtlarını geliştirmek için iyi sebepler vardır. Düzenli olarak açık kaynaklı projelerde bakım yapılmayan değişiklik kayıtları için çekme istekleri yapıyorum.

Ayrıca bir sürümdeki notların arasında önemli bir değişiklikten bahsetmeyi unutmuş olduğunuzu fark edebilirsiniz. Değişiklik kayıtlarınızı bu bilgi ışığında güncellemeniz gerektiği gün gibi ortada.

Nasıl katkıda bulunabilirim?

Bu belge doğrunun kendisi değil; benim ince eleyip sık dokuduğum görüşlerimdir. Beraberinde toparlamış olduğum bilgiler ve örnekler bulunur.

Burada yapmaya çalıştığım topluluğun ortak bir paydada buluşmasını sağlamak. İnanıyorum ki tartışmanın kendisi de sonucu kadar önemli.

Yani lütfen, siz de katılın.

Sohbetler

Geliştiricilerin ve katkıda bulunanların neden değişiklik kayıtlarını dikkate almaları gerekliliğini ve bu projenin arkasındaki motivasyonu anlattığım Değişiklik Kayıtları podcast'ini inceleyebilirsiniz.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Ведіть Changelog

Не дозволяйте друзям зливати логи гіта у лог змін.

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

## [Unreleased]

## [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

Що таке лог змін?

Лог змін - це файл, що містить підтримуваний та хронологічно впорядкований список змін для кожної версії проекту.

Навіщо вести лог змін?

Це дозволяє полегшити користувачам та контриб'юторам слідкувати за змінами у релізах (чи версіях) проекту.

Кому потрібен лог змін?

Людям. Користувачам та розробникам, кінцевими користувачами програмного забезпечення є люди, яким важливо знати з чим вони працюють. Якщо відбулися змін, то люди повинні знати що змінилося і як.

Як створити хороший лог змін?

Головні принципи

  • Лог змін для людей, а не машин.
  • Окремий розділ для кожної версії.
  • Зміни одного типу мають бути згруповані.
  • На версії та секції потрібно ставити гіперпосилання.
  • Остання версія мусить бути на початку.
  • Кожна версія має мати власну дату.
  • Вкажіть чи підтримуєте Ви принципи Семантичне версіювання.

Типи змін

  • Додано для нового функціоналу.
  • Змінено для змін в існуючий функціонал.
  • Застаріло для функціоналу, що планується видалити.
  • Видалено про вже видалений функціонал.
  • Виправлення для будь яких виправлень.
  • Безпека при виявленні вразливостей.

Як мені докладати мінімальні зусилля для ведення логу змін?

Ведіть розділ Нове на початку файла.

Для переслідування подвійної цілі:

  • Люди можуть бачити майбутні зміни в найближчому релізі
  • Як настане час релізу, Ви можете перемістити розділ Нове у розділ нового релізу,

Чи може лог змін бути поганим?

Так. Ось декілька способів зробити лог змін не вдалим.

Логи змін між комітами.

Використовувати логи комітів як логи змін - це погана ідея. Вони наповнені інформаційним шумом. Такими як коміти злиття, не інформативні назви комітів, змінами у документації тощо.

Призначення комітів у тому, щоб документувати кроки в еволюції коду. У деяких проектах історія комітів доглянута, в інших - ні.

Призначення ж логу змін полягає у документації вагомих змін, часто між багатьма комітами, доносячи їх призначення до кінцевого користувача.

Ігнорування застарілого функціоналу

Коли люди оновлюються з версії до версії, їм потрібна повна впевненість у тому, чи може щось зламатися. Їм повинна бути надана можливість оновитися до версії зі списком застарілого функціоналу, видалити все застаріле, а потім оновитися до версії з видаленим застарілим функціоналом.

Якщо Ви не займаєтеся логом змін, то хоча б ведіть список застарілого, видаленого або серйозних змін функціоналу.

Незрозумілі дати

Регіональні дати можуть відрізнятися і це може бути складно для правильного розуміння ваших дат для користувачів у різних куточках світу. Варто надавати переваги датам, що форматовані за таким зразком: 2017-07-17. У них числа ідуть від найбільшого до найменшого: рік, місяць, день. Мінімізує конфузи у випадку використання регіональних форматів, коли день і місяць можуть мати різний порядок. Цей формат не пересікається з більшістю інших форматів і є стандартом ISO. Тому такий формат рекомендується для логів змін.

Поширені запитання

Чи існує стандарт логів змін?

Не зовсім. Є стайлгайд логів змін GNU або довгий у два параграфа GNU NEWS file. Обидва неадекватні і неповні.

Цей проект покликаний бути поліпшеною угодою про логи змін. Це виходить із ліпших практик open source спільноти.

Здорова критика, дискусія та пропозиції поліпшення вітаються.

Як назвати файл логів змін?

Назвіть CHANGELOG.md. У деяких проектах файл носить назви HISTORY, NEWS або RELEASES.

Може видатися, що назва файлу для логів змін не суттєва, проте навіщо ускладнювати життя користувачам змушуючи їх шукати?

Як щодо GitHub релізів?

Це чудова ініціатива. Релізи можуть бути використані для перетворення простих тегів у Git (v1.0.0 - до прикладу) у деталізовані нотатки до релізів шляхом їх редагування вручну або за допомогою коментарів до цих тегів.

Релізи GitHub є не портативним логом змін, який може бути показаний користувачам лише на самому сайті GitHub. Його можна вести подібно до формату Keep a Changelog, але для цього потрібні значні зусилля.

Поточна версія на GitHub не так добре очевидна для користувача, на відмінну від звичайних файлів з іменами у верхньому регістрі (README, CONTRIBUTING і так далі). Крім того, інтерфейс не дозволяє посилання на логи комітів між релізами.

Чи можуть логи змін автоматично парситися?

Це заскладно, оскільки люди використовують різні формати та імена файлів.

Vandamme - це гем для Ruby, створений командою Gemnasium, який парсить багато (але не всі) логи змін проектів з відкритим кодом.

А як щодо yanked-релізів?

Yanked-релізи - це версії, що вилучаються із-за серйозних багів або проблем з безпекою у них. Часто вони навіть не згадуються у логах змін. А повинні. І описуватися вони повинні так:

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

[YANKED] навмисне кидається в очі. Важливо, щоб його помітили. Обмежений квадратними дужками, щоб його легше було спарсити.

Чи є сенс переписати лог змін?

Звісно. Завжди є сенс поліпшувати лог змін. І відкривати пул-реквести додаючи втрачені релізи у проекти з відкритим кодом і закинутими логами змін.

Також можлива ситуація, що Ви забули вказати критичні зміни для версії. Очевидно, що потрібно такий лог оновити.

Як я можу допомогти вашому проекту?

Цей документ не претендує на виключну правду; Це моє бачення, зі зібраною інформацію та прикладами.

Хотів би, щоб спільнота дійшла згоди. Я вірю у дискусію та результат.

Тому беріть участь.

Обговорення

Я приходив на підкаст The Changelog, щоб обговорити те, чому ментейнери та контриб'ютори повинні вести логи змін, а також про мою мотивацію для створення цього проекту.

The latest version (1.1.0) is not yet available in this language but you can read it in English for now and help translate it.

Ведіть Changelog

Не дозволяйте друзям зливати логи гіта у лог змін.

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

## [Unreleased]

## [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

Що таке лог змін?

Лог змін - це файл, що містить підтримуваний та хронологічно впорядкований список змін для кожної версії проекту.

Навіщо вести лог змін?

Це дозволяє полегшити користувачам та контриб'юторам слідкувати за змінами у релізах (чи версіях) проекту.

Кому потрібен лог змін?

Людям. Користувачам та розробникам, кінцевими користувачами програмного забезпечення є люди, яким важливо знати з чим вони працюють. Якщо відбулися змін, то люди повинні знати що змінилося і як.

Як створити хороший лог змін?

Головні принципи

  • Лог змін для людей, а не машин.
  • Окремий розділ для кожної версії.
  • Зміни одного типу мають бути згруповані.
  • На версії та секції потрібно ставити гіперпосилання.
  • Остання версія мусить бути на початку.
  • Кожна версія має мати власну дату.
  • Вкажіть чи підтримуєте Ви принципи Семантичне версіювання.

Типи змін

  • Додано для нового функціоналу.
  • Змінено для змін в існуючий функціонал.
  • Застаріло для функціоналу, що планується видалити.
  • Видалено про вже видалений функціонал.
  • Виправлення для будь яких виправлень.
  • Безпека при виявленні вразливостей.

Як мені докладати мінімальні зусилля для ведення логу змін?

Ведіть розділ Нове на початку файла.

Для переслідування подвійної цілі:

  • Люди можуть бачити майбутні зміни в найближчому релізі
  • Як настане час релізу, Ви можете перемістити розділ Нове у розділ нового релізу,

Чи може лог змін бути поганим?

Так. Ось декілька способів зробити лог змін не вдалим.

Логи змін між комітами.

Використовувати логи комітів як логи змін - це погана ідея. Вони наповнені інформаційним шумом. Такими як коміти злиття, не інформативні назви комітів, змінами у документації тощо.

Призначення комітів у тому, щоб документувати кроки в еволюції коду. У деяких проектах історія комітів доглянута, в інших - ні.

Призначення ж логу змін полягає у документації вагомих змін, часто між багатьма комітами, доносячи їх призначення до кінцевого користувача.

Ігнорування застарілого функціоналу

Коли люди оновлюються з версії до версії, їм потрібна повна впевненість у тому, чи може щось зламатися. Їм повинна бути надана можливість оновитися до версії зі списком застарілого функціоналу, видалити все застаріле, а потім оновитися до версії з видаленим застарілим функціоналом.

Якщо Ви не займаєтеся логом змін, то хоча б ведіть список застарілого, видаленого або серйозних змін функціоналу.

Незрозумілі дати

Регіональні дати можуть відрізнятися і це може бути складно для правильного розуміння ваших дат для користувачів у різних куточках світу. Варто надавати переваги датам, що форматовані за таким зразком: 2017-07-17. У них числа ідуть від найбільшого до найменшого: рік, місяць, день. Мінімізує конфузи у випадку використання регіональних форматів, коли день і місяць можуть мати різний порядок. Цей формат не пересікається з більшістю інших форматів і є стандартом ISO. Тому такий формат рекомендується для логів змін.

Поширені запитання

Чи існує стандарт логів змін?

Не зовсім. Є стайлгайд логів змін GNU або довгий у два параграфа GNU NEWS file. Обидва неадекватні і неповні.

Цей проект покликаний бути поліпшеною угодою про логи змін. Це виходить із ліпших практик open source спільноти.

Здорова критика, дискусія та пропозиції поліпшення вітаються.

Як назвати файл логів змін?

Назвіть CHANGELOG.md. У деяких проектах файл носить назви HISTORY, NEWS або RELEASES.

Може видатися, що назва файлу для логів змін не суттєва, проте навіщо ускладнювати життя користувачам змушуючи їх шукати?

Як щодо GitHub релізів?

Це чудова ініціатива. Релізи можуть бути використані для перетворення простих тегів у Git (v1.0.0 - до прикладу) у деталізовані нотатки до релізів шляхом їх редагування вручну або за допомогою коментарів до цих тегів.

Релізи GitHub є не портативним логом змін, який може бути показаний користувачам лише на самому сайті GitHub. Його можна вести подібно до формату Keep a Changelog, але для цього потрібні значні зусилля.

Поточна версія на GitHub не так добре очевидна для користувача, на відмінну від звичайних файлів з іменами у верхньому регістрі (README, CONTRIBUTING і так далі). Крім того, інтерфейс не дозволяє посилання на логи комітів між релізами.

Чи можуть логи змін автоматично парситися?

Це заскладно, оскільки люди використовують різні формати та імена файлів.

Vandamme - це гем для Ruby, створений командою Gemnasium, який парсить багато (але не всі) логи змін проектів з відкритим кодом.

А як щодо yanked-релізів?

Yanked-релізи - це версії, що вилучаються із-за серйозних багів або проблем з безпекою у них. Часто вони навіть не згадуються у логах змін. А повинні. І описуватися вони повинні так:

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

[YANKED] навмисне кидається в очі. Важливо, щоб його помітили. Обмежений квадратними дужками, щоб його легше було спарсити.

Чи є сенс переписати лог змін?

Звісно. Завжди є сенс поліпшувати лог змін. І відкривати пул-реквести додаючи втрачені релізи у проекти з відкритим кодом і закинутими логами змін.

Також можлива ситуація, що Ви забули вказати критичні зміни для версії. Очевидно, що потрібно такий лог оновити.

Як я можу допомогти вашому проекту?

Цей документ не претендує на виключну правду; Це моє бачення, зі зібраною інформацію та прикладами.

Хотів би, щоб спільнота дійшла згоди. Я вірю у дискусію та результат.

Тому беріть участь.

Обговорення

Я приходив на підкаст The Changelog, щоб обговорити те, чому ментейнери та контриб'ютори повинні вести логи змін, а також про мою мотивацію для створення цього проекту.

最新版 (1.1.0) 暂时还没有翻译到简体中文，您可以阅读最新的英语版，并且帮助翻译，不胜感激。

如何维护更新日志

更新日志绝对不应该是git日志的堆砌物

Version 0.3.0

更新日志是什么？

更新日志（Change Log）是一个由人工编辑，以时间为倒序的列表。 这个列表记录所有版本的重大变动。

# 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.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' 未发布区域，来记录当前的变化。 这样作有两大意义。

吐槽环节到了

请你一定要注意：

如果你还有要吐槽的，欢迎留issue或者直接PR

世界上不是有标准的更新日志格式吗？

貌似GNU或者GNU NEWS还是提过些规范的，事实是它们太过简陋了。 开发有那么多种情况，采用那样的规范，确实是不太合适的。

这个项目提供的规范是作者本人希望能够成为世界规范的。 作者不认为当前的标准足够好，而且作为一个社区，我们是有能力提供更棒的规范。 如果你对这个规范有不满的地方，不要忘记还可以吐槽呢。

更新日志文件名应该叫什么？

我们的案例中给的名字就是最好的规范：CHANGELOG.md，注意大小写。

像HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md这么 多文件名就太不统一了。

只会让大家更难找到。

为何不直接记录git log?

因为git日志一定是乱糟糟的。哪怕一个最理想的由完美的程序员开发和提交的，哪怕一个 从不忘记每次提交全部文件，不写错别字，不忘记重构每一个部分，也无法保证git日志完美无瑕。 况且git日志的核心在于记录代码的演化，而更新日志则是记录最重要的变更。

就像注释之于代码，更新日志之于git日志。前者解释为什么，而后者说明发生了什么。

更新日志能机器识别吗？

非常困难，因为有各种不同的文件格式和其它规范。

Vandamme是一个Ruby程序（由Gemnasium团队制作），可以解析 好多种（但绝对不是全部）开源库的更新日志。

到底是CHANGELOG还是更新日志

CHANGELOG是文件名，更新日志是常用说法。CHANGELOG采用大写是有历史根源的。就像很多类似的文件 README， LICENSE，还有CONTRIBUTING。

采用大写可以更加显著，毕竟这是项目很重要的元信息。就像开源徽章。

那些后来撤下的版本怎么办？

因为各种安全/重大bug原因被撤下的版本被标记'YANKED'。这些版本一般不出现在更新日志里，但作者建议他们出现。 显示方式应该是：

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

[YANKED]采用大写更加显著，因为这个信息很重要。而采用方括号则容易被程序解析。

是否可以重写更新日志

当然。哪怕已经上线了，也可以重新更新更新日志。有许多开源项目更新日志不够新，所以作者就会帮忙更新。

另外，很有可能你忘记记录一个重大功能更新。所以这时候应该去重写更新日志。

如何贡献？

本文档并不是真理。这只是原作者的个人建议，并且包括许多收集的例子。 哪怕本开源库提供一个更新日志案例，我刻意没有提供一个 过于苛刻的规则列表（不像语义化版本格式）。

这是因为我希望通过社区达到统一观点，我认为中间讨论的过程与结果一样重要。

所以欢迎贡献。

最新版 (1.1.0) 暂时还没有翻译到简体中文，您可以阅读最新的英语版，并且帮助翻译，不胜感激。

如何维护更新日志

更新日志绝对不应该是git日志的堆砌物

Version 0.3.0

更新日志是什么？

更新日志（Change Log）是一个由人工编辑，以时间为倒序的列表。 这个列表记录所有版本的重大变动。

# 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.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' 未发布区域，来记录当前的变化。 这样作有两大意义。

吐槽环节到了

请你一定要注意：

如果你还有要吐槽的，欢迎留issue或者直接PR

世界上不是有标准的更新日志格式吗？

貌似GNU或者GNU NEWS还是提过些规范的，事实是它们太过简陋了。 开发有那么多种情况，采用那样的规范，确实是不太合适的。

这个项目提供的规范是作者本人希望能够成为世界规范的。 作者不认为当前的标准足够好，而且作为一个社区，我们是有能力提供更棒的规范。 如果你对这个规范有不满的地方，不要忘记还可以吐槽呢。

更新日志文件名应该叫什么？

我们的案例中给的名字就是最好的规范：CHANGELOG.md，注意大小写。

像HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md这么 多文件名就太不统一了。

只会让大家更难找到。

为何不直接记录git log?

因为git日志一定是乱糟糟的。哪怕一个最理想的由完美的程序员开发和提交的，哪怕一个 从不忘记每次提交全部文件，不写错别字，不忘记重构每一个部分，也无法保证git日志完美无瑕。 况且git日志的核心在于记录代码的演化，而更新日志则是记录最重要的变更。

就像注释之于代码，更新日志之于git日志。前者解释为什么，而后者说明发生了什么。

更新日志能机器识别吗？

非常困难，因为有各种不同的文件格式和其它规范。

Vandamme是一个Ruby程序（由Gemnasium团队制作），可以解析 好多种（但绝对不是全部）开源库的更新日志。

到底是CHANGELOG还是更新日志

CHANGELOG是文件名，更新日志是常用说法。CHANGELOG采用大写是有历史根源的。就像很多类似的文件 README， LICENSE，还有CONTRIBUTING。

采用大写可以更加显著，毕竟这是项目很重要的元信息。就像开源徽章。

那些后来撤下的版本怎么办？

因为各种安全/重大bug原因被撤下的版本被标记'YANKED'。这些版本一般不出现在更新日志里，但作者建议他们出现。 显示方式应该是：

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

[YANKED]采用大写更加显著，因为这个信息很重要。而采用方括号则容易被程序解析。

是否可以重写更新日志

当然。哪怕已经上线了，也可以重新更新更新日志。有许多开源项目更新日志不够新，所以作者就会帮忙更新。

另外，很有可能你忘记记录一个重大功能更新。所以这时候应该去重写更新日志。

如何贡献？

本文档并不是真理。这只是原作者的个人建议，并且包括许多收集的例子。 哪怕本开源库提供一个更新日志案例，我刻意没有提供一个 过于苛刻的规则列表（不像语义化版本格式）。

这是因为我希望通过社区达到统一观点，我认为中间讨论的过程与结果一样重要。

所以欢迎贡献。

最新版 (1.1.0) 暂时还没有翻译到简体中文，您可以阅读最新的英语版，并且帮助翻译，不胜感激。

如何维护更新日志

更新日志绝对不应该是 git 日志的堆砌物

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

## [Unreleased]

## [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

更新日志是什么？

更新日志（Change Log）是一个由人工编辑、以时间为倒序的列表，用于记录项目中每个版本的显著变动。

为何要提供更新日志？

为了让用户和开发人员更简单清晰地知晓项目的不同版本之间有哪些显著变动。

哪些人需要更新日志？

人人需要更新日志。无论是用户还是开发者。当软件有变动时，大家希望知道改动是为何、以及如何进行的。

怎样制作高质量的更新日志？

指导原则

  • 记住日志是写给人而非机器的。
  • 每个版本都应该有独立的入口。
  • 同类改动应该分组放置。
  • 不同版本应分别设置链接。
  • 新版本在前，旧版本在后。
  • 应包括每个版本的发布日期。
  • 注明是否遵守语义化版本规范。

变动类型

  • Added 新添加的功能。
  • Changed 对现有功能的变更。
  • Deprecated 已经不建议使用，即将移除的功能。
  • Removed 已经移除的功能。
  • Fixed 对 bug 的修复。
  • Security 对安全性的改进。

如何减少维护更新日志的精力？

在文档最上方提供 Unreleased 区块以记录即将发布的更新内容。

这样做有两个好处：

  • 大家可以知道在未来版本中可能会有哪些变更。
  • 在发布新版本时，直接将 Unreleased 区块中的内容移动至新发布版本的描述区块就可以了。

有很糟糕的更新日志吗？

当然有，下面就是一些糟糕的方式。

使用 git 日志

使用 git 日志作为更新日志是个非常糟糕的方式：git 日志充满各种无意义的信息，如合并提交、语焉不详的提交标题、文档更新等。

提交的目的是记录源码的演化。一些项目会清理提交记录，一些则不会。

更新日志的目的则是记录重要的变更以供受众阅读，记录范围通常涵盖多次提交。

无视即将弃用的功能

当从一个版本升级至另一个时，人们应清楚（尽管痛苦）地知道哪些部分将不再被支持。应该允许先升级至一个列出哪些功能将会被弃用的版本，待去掉那些不再支持的部分后，再升级至把那些弃用功能真正移除的版本。

即使其他什么都不做，也至少要在更新日志中列出 deprecations，removals 以及其他重大变动。

易混淆的日期格式

不同区域有着不同的时间格式，要找到让大家都满意的日期格式不是件容易的事。2012-06-02 的格式从大到小排列符合逻辑、不容易与其他日期格式混淆，而且还符合 ISO 标准。因此，推荐在更新日志中采用使用此种日期格式。

常见问题

是否有一个标准化的更新日志格式？

并没有。虽然 GNU 提供了更新日志样式指引，以及那个仅有两段长的 GNU NEWS 文件“指南”，但两者均远远不够。

此项目旨在提供一个 更好的更新日志范例，所有点子都来自于对开源社区中优秀实例的观察与记录。

欢迎提供有建设性的批评、讨论及建议。

更新日志文件应被如何命名？

通常使用 CHANGELOG.md。有些项目将其命名为 HISTORY、NEWS 或是 RELEASES。

当然，你可能认为更新日志的命名并不那么重要，但为什么要为难那些仅仅是想看到都有哪些重大变更的用户呢？

GitHub Releases 怎么样？

这是个非常好的提议。GitHub Releases 可通过手动添加发布日志或将带有注释的 git 标签信息抓取后转换的方式，将简单的 git 标签（如一个叫 v1.0.0 的标签）转换为信息丰富的发布日志。

GitHub Releases 会创建一个非便携、仅可在 GitHub 环境下显示的更新日志。尽管会花费更多时间，但将之处理成更新日志格式是完全可能的。

现行版本的 GitHub Releases 不像那些典型的大写文件（README，CONTRIBUTING 等），仍可以认为是不利于用户探索的。另一个小问题则是目前的 GitHub Releases 界面并没有提供不同版本间的 commit 日志链接。

更新日志可以被自动识别吗？

非常困难，因为有各种不同的文件格式和命名。

Vandamme 是一个 Ruby 程序，由 Gemnasium 团队制作，可以解析多种（但绝对不是全部）开源库的更新日志。

那些后来撤下的版本怎么办？

因重大 bug 或安全性原因而被撤下的版本通常不会出现在更新日志中，但仍然建议记录下来。你可以这样作出记录：

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

因为这类更改十分重要，所以 [YANKED] 标签应该非常醒目。此外，用方括号包围可使其更易被程序识别。

是否可以重写更新日志？

当然可以。总会有合适的原因去改进更新日志。我也时常提 Pull Request 来为那些未维护更新日志的开源项目加入缺失的发布信息。

另外，你很有可能发现自己忘记记录一个重大功能更新。这种情况下显然应该重写更新日志。

如何贡献？

本文档并非真理。而是我深思熟虑后的建议，以及我收集的信息与样例。

希望我们的社区可以对此达成一致。我相信讨论的过程与最终结果一样重要。

所以欢迎贡献。

访谈

我在 The Changelog podcast 上讲述了为何维护者与贡献者应关心更新日志，以及这个项目背后的动机。

最新版 (1.1.0) 暂时还没有翻译到简体中文，您可以阅读最新的英语版，并且帮助翻译，不胜感激。

如何维护更新日志

更新日志绝对不应该是 git 日志的堆砌物

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

## [Unreleased]

## [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

更新日志是什么？

更新日志（Change Log）是一个由人工编辑、以时间为倒序的列表，用于记录项目中每个版本的显著变动。

为何要提供更新日志？

为了让用户和开发人员更简单清晰地知晓项目的不同版本之间有哪些显著变动。

哪些人需要更新日志？

人人需要更新日志。无论是用户还是开发者。当软件有变动时，大家希望知道改动是为何、以及如何进行的。

怎样制作高质量的更新日志？

指导原则

  • 记住日志是写给人而非机器的。
  • 每个版本都应该有独立的入口。
  • 同类改动应该分组放置。
  • 不同版本应分别设置链接。
  • 新版本在前，旧版本在后。
  • 应包括每个版本的发布日期。
  • 注明是否遵守语义化版本规范。

变动类型

  • Added 新添加的功能。
  • Changed 对现有功能的变更。
  • Deprecated 已经不建议使用，即将移除的功能。
  • Removed 已经移除的功能。
  • Fixed 对 bug 的修复。
  • Security 对安全性的改进。

如何减少维护更新日志的精力？

在文档最上方提供 Unreleased 区块以记录即将发布的更新内容。

这样做有两个好处：

  • 大家可以知道在未来版本中可能会有哪些变更。
  • 在发布新版本时，直接将 Unreleased 区块中的内容移动至新发布版本的描述区块就可以了。

有很糟糕的更新日志吗？

当然有，下面就是一些糟糕的方式。

使用 git 日志

使用 git 日志作为更新日志是个非常糟糕的方式：git 日志充满各种无意义的信息，如合并提交、语焉不详的提交标题、文档更新等。

提交的目的是记录源码的演化。一些项目会清理提交记录，一些则不会。

更新日志的目的则是记录重要的变更以供受众阅读，记录范围通常涵盖多次提交。

无视即将弃用的功能

当从一个版本升级至另一个时，人们应清楚（尽管痛苦）地知道哪些部分将不再被支持。应该允许先升级至一个列出哪些功能将会被弃用的版本，待去掉那些不再支持的部分后，再升级至把那些弃用功能真正移除的版本。

即使其他什么都不做，也至少要在更新日志中列出 deprecations，removals 以及其他重大变动。

易混淆的日期格式

不同区域有着不同的时间格式，要找到让大家都满意的日期格式不是件容易的事。2012-06-02 的格式从大到小排列符合逻辑、不容易与其他日期格式混淆，而且还符合 ISO 标准。因此，推荐在更新日志中采用使用此种日期格式。

常见问题

是否有一个标准化的更新日志格式？

并没有。虽然 GNU 提供了更新日志样式指引，以及那个仅有两段长的 GNU NEWS 文件“指南”，但两者均远远不够。

此项目旨在提供一个 更好的更新日志范例，所有点子都来自于对开源社区中优秀实例的观察与记录。

欢迎提供有建设性的批评、讨论及建议。

更新日志文件应被如何命名？

通常使用 CHANGELOG.md。有些项目将其命名为 HISTORY、NEWS 或是 RELEASES。

当然，你可能认为更新日志的命名并不那么重要，但为什么要为难那些仅仅是想看到都有哪些重大变更的用户呢？

GitHub Releases 怎么样？

这是个非常好的提议。GitHub Releases 可通过手动添加发布日志或将带有注释的 git 标签信息抓取后转换的方式，将简单的 git 标签（如一个叫 v1.0.0 的标签）转换为信息丰富的发布日志。

GitHub Releases 会创建一个非便携、仅可在 GitHub 环境下显示的更新日志。尽管会花费更多时间，但将之处理成更新日志格式是完全可能的。

现行版本的 GitHub Releases 不像那些典型的大写文件（README，CONTRIBUTING 等），仍可以认为是不利于用户探索的。另一个小问题则是目前的 GitHub Releases 界面并没有提供不同版本间的 commit 日志链接。

更新日志可以被自动识别吗？

非常困难，因为有各种不同的文件格式和命名。

Vandamme 是一个 Ruby 程序，由 Gemnasium 团队制作，可以解析多种（但绝对不是全部）开源库的更新日志。

那些后来撤下的版本怎么办？

因重大 bug 或安全性原因而被撤下的版本通常不会出现在更新日志中，但仍然建议记录下来。你可以这样作出记录：

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

因为这类更改十分重要，所以 [YANKED] 标签应该非常醒目。此外，用方括号包围可使其更易被程序识别。

是否可以重写更新日志？

当然可以。总会有合适的原因去改进更新日志。我也时常提 Pull Request 来为那些未维护更新日志的开源项目加入缺失的发布信息。

另外，你很有可能发现自己忘记记录一个重大功能更新。这种情况下显然应该重写更新日志。

如何贡献？

本文档并非真理。而是我深思熟虑后的建议，以及我收集的信息与样例。

希望我们的社区可以对此达成一致。我相信讨论的过程与最终结果一样重要。

所以欢迎贡献。

访谈

我在 The Changelog podcast 上讲述了为何维护者与贡献者应关心更新日志，以及这个项目背后的动机。

最新版 (1.1.0) 暫時還沒有翻譯到正體中文，您可以閱讀最新的英語版，並且幫助翻譯，不勝感激。

如何維護更新日誌

更新日誌絕對不應該是 git 日誌的堆砌物

Version 0.3.0

更新日誌是什麽？

更新日誌（Change Log）是一個由人工編輯，以時間為倒敘的列表。 這個列表記錄所有版本的重大變動。

# 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.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' 未發布區域，來記錄當前的變化。 這樣做有兩大意義。

吐槽環節到了

請你一定要注意：

如果你還有要吐槽的，歡迎留 issue 或者直接 PR

世界上不是有標準的更新日誌格式嗎？

貌似 GNU 或者 GNU NEWS 還是提過些規範的，事實是它們太過簡陋了。 開發有那麽多中情況，採用那樣的規範，確實是不太合適的。

這個項目提供的規範是作者本人希望能夠成為世界規範的。 作者不認為當前的標準足夠好，而且作為一個社區，我們是有能力提供更棒的規範。 如果你對這個規範有不滿的地方，不要忘記還可以吐槽呢。

更新日誌文件名應該叫什麽？

我們的案例中給的名字就是最好的規範：CHANGELOG.md，注意大小寫。

像 HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md 這麽 多文件名就太不統一了。

只會讓大家更難找到。

為何不直接記錄 git log?

因為 git 日誌一定是亂糟糟的。哪怕一個最理想的由完美的程式設計師開發的提交的，哪怕一個 從不忘記每次提交全部文件，不寫錯別字，不忘記重構每一個部分——也無法保證 git 日誌完美無瑕。 況且 git 日誌的核心在於記錄程式碼的演化，而更新日誌則是記錄最重要的變更。

就像註解之於程式碼，更新日誌之於 git 日誌。前者解釋為什麽，而後者說明發生了什麽。

更新日誌能機器識別嗎？

非常困難，因為有各種不同的文件格式和其他規範。

Vandamme 是一支 Ruby 程式（由 Gemnasium 團隊制作），可以解析 很多種（但絕對不是全部）開源程式庫的更新日誌。

到底是 CHANGELOG 還是更新日誌

CHANGELOG 是文件名，更新日誌是常用說法。CHANGELOG 採用大寫是有歷史根源的。就像很多類似的文件 README，LICENSE，還有 CONTRIBUTING。

採用大寫可以更加顯著，畢竟這是項目很重要的 metadata。就像開源徽章。

那些後來撤下的版本怎麽辦？

因為各種安全/重大 bug 原因被撤下的版本被標記 'YANKED'。這些版本一般不出現在更新日誌裏，但作者建議他們出現。 顯示方式應該是：

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

[YANKED] 採用大寫更加顯著，因為這個訊息很重要。而採用方括號則容易被程式解析。

是否可以重寫更新日誌

當然。哪怕已經上線了，也可以重新更新更新日誌。有許多開源項目更新日誌不夠新，所以作者就會幫忙更新。

另外，很有可能你忘記記錄一個重大功能更新。所以這時候應該去重寫更新日誌。

如何貢獻？

本文檔並不是真理。這只是原作者的個人建議，並且包括許多收集的例子。 哪怕本開源庫提供一個更新日誌案例，我刻意沒有提供一個 過於苛刻的規則列表（不像語義化版本格式）。

這是因為我希望通過社區達到統一觀點，我認為中間討論的過程與結果一樣重要。

所以歡迎貢獻。

最新版 (1.1.0) 暫時還沒有翻譯到正體中文，您可以閱讀最新的英語版，並且幫助翻譯，不勝感激。

如何維護更新日誌

更新日誌絕對不應該是 git 日誌的堆砌物

Version 0.3.0

更新日誌是什麽？

更新日誌（Change Log）是一個由人工編輯，以時間為倒敘的列表。 這個列表記錄所有版本的重大變動。

# 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.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' 未發布區域，來記錄當前的變化。 這樣做有兩大意義。

吐槽環節到了

請你一定要注意：

如果你還有要吐槽的，歡迎留 issue 或者直接 PR

世界上不是有標準的更新日誌格式嗎？

貌似 GNU 或者 GNU NEWS 還是提過些規範的，事實是它們太過簡陋了。 開發有那麽多中情況，採用那樣的規範，確實是不太合適的。

這個項目提供的規範是作者本人希望能夠成為世界規範的。 作者不認為當前的標準足夠好，而且作為一個社區，我們是有能力提供更棒的規範。 如果你對這個規範有不滿的地方，不要忘記還可以吐槽呢。

更新日誌文件名應該叫什麽？

我們的案例中給的名字就是最好的規範：CHANGELOG.md，注意大小寫。

像 HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md 這麽 多文件名就太不統一了。

只會讓大家更難找到。

為何不直接記錄 git log?

因為 git 日誌一定是亂糟糟的。哪怕一個最理想的由完美的程式設計師開發的提交的，哪怕一個 從不忘記每次提交全部文件，不寫錯別字，不忘記重構每一個部分——也無法保證 git 日誌完美無瑕。 況且 git 日誌的核心在於記錄程式碼的演化，而更新日誌則是記錄最重要的變更。

就像註解之於程式碼，更新日誌之於 git 日誌。前者解釋為什麽，而後者說明發生了什麽。

更新日誌能機器識別嗎？

非常困難，因為有各種不同的文件格式和其他規範。

Vandamme 是一支 Ruby 程式（由 Gemnasium 團隊制作），可以解析 很多種（但絕對不是全部）開源程式庫的更新日誌。

到底是 CHANGELOG 還是更新日誌

CHANGELOG 是文件名，更新日誌是常用說法。CHANGELOG 採用大寫是有歷史根源的。就像很多類似的文件 README，LICENSE，還有 CONTRIBUTING。

採用大寫可以更加顯著，畢竟這是項目很重要的 metadata。就像開源徽章。

那些後來撤下的版本怎麽辦？

因為各種安全/重大 bug 原因被撤下的版本被標記 'YANKED'。這些版本一般不出現在更新日誌裏，但作者建議他們出現。 顯示方式應該是：

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

[YANKED] 採用大寫更加顯著，因為這個訊息很重要。而採用方括號則容易被程式解析。

是否可以重寫更新日誌

當然。哪怕已經上線了，也可以重新更新更新日誌。有許多開源項目更新日誌不夠新，所以作者就會幫忙更新。

另外，很有可能你忘記記錄一個重大功能更新。所以這時候應該去重寫更新日誌。

如何貢獻？

本文檔並不是真理。這只是原作者的個人建議，並且包括許多收集的例子。 哪怕本開源庫提供一個更新日誌案例，我刻意沒有提供一個 過於苛刻的規則列表（不像語義化版本格式）。

這是因為我希望通過社區達到統一觀點，我認為中間討論的過程與結果一樣重要。

所以歡迎貢獻。

最新版 (1.1.0) 暫時還沒有翻譯到正體中文，您可以閱讀最新的英語版，並且幫助翻譯，不勝感激。

如何維護更新日誌

別讓你的更新日誌成為 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.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [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

更新日誌是什麼？

更新日誌（Changelog）是說明專案在開發過程中，版本之間的差異紀錄，由開發人員由新而舊撰寫。

為什麼需要提供更新日誌？

為了讓使用者和開發人員更簡單明確地了解各個版本之間有著哪些改動。

哪些人需要更新日誌？

大家都需要更新日誌。

無論是開發人員或是使用者，都會在意軟體包含了什麼東西。 當軟體更新了，大家都想知道改了些什麼以及為什麼要改。

如何寫出高品質的日誌？

撰寫原則

  • 更新日誌是寫給「人」看的，不是機器。
  • 每個版本都應該有獨立的進入點。
  • 相同類型的改動應該被分類在同一組。
  • 版本與章節應「可連結化」。
  • 新版本總是寫在最前面。
  • 每個版本都應該註記發佈日期。
  • 版本命名應遵守語意化版本格式。

改動類型

  • Added ：當增加了新功能。
  • Changed ：當更動了既有的功能。
  • Deprecated ：當功能將在近期被移除。
  • Removed ：當移除了現有的功能。
  • Fixed ：當修復了某些錯誤。
  • Security ：當增進了安全性漏洞。

如何提升維護「更新日誌」的效率？

在日誌上方使用 Unreleased 區塊記錄即將發佈的更新內容。

這麼做能夠：

  • 讓大家知道在未來的版本中可能會有哪些改動。
  • 發佈新版本時，直接將 Unreleased 移到新版本的區塊就完成了 ヾ(*´ω｀*)ノ

不就只是個日記而已嗎？難道可以把日誌得很糟嗎？

當然，下面有些糟糕的範例：

🚫 直接複製 git log 到更新日誌

直接把 git log 複製一份成更新日誌絕對不是個好主意。

git log 充滿了各種瑣碎的訊息，像 merge commits、亂七八糟的提交訊息或是文件更新等。

Commits 的目的應該是記錄原始碼演進的過程，有些專案會清理 commits，但有些不會。

更新日誌的目的則是記錄那些值得一提的改動，經常涵蓋多個 commits，最終目的仍然是讓看的人一目了然。

🚫 忽略 Deprecations

當使用者升級版本時，他應該要能預先知道哪些環節可能會出問題，然而，在理想的狀況下，應該讓使用者有空間能預先升級即將被棄用的功能，替換掉棄用功能之後，再升級至棄用功能被真正移除的版本。

即使不這麼做，也要在更新日誌中列出棄用的、移除的或是任何可能導致程式碼失效的重大改動。

🚫 容易混淆的日期格式

在世界的每個角落，不同區域有著不同的時間格式，找到讓大家都滿意的日期格式不是件簡單的事。使用像 2017-07-17 的格式能清楚傳達日期，而且不易與其他日期格式混淆，同時也遵守 ISO 標準，因此推薦使用像這樣的日期格式。

常見問題

有沒有標準格式可以參考呢？

並沒有。雖然有 GNU 更新日誌指南 以及只有兩段長的 GNU - The NEWS File 指南（括弧笑），但這些並不足以稱為「標準」。

這項專案的宗旨在於提供一個 更好的更新日誌範例，源於觀察開源社群中優秀的實際案例，把它們蒐集在一起。

歡迎各位提供有建設性的建議和批評。

更新日誌的檔案名稱應該是？

通常使用 CHANGELOG.md。也有用 HISTORY、NEWS、或是 RELEASES 的例子。

或許你認為取什麼名字並不是件多麼重要的事，但為什麼要讓只是想看日誌的使用者不容易找到它呢？

那麼 GitHub Releases 呢？

這是個好問題。GitHub Releases 能手動在簡單的 git tag（如 v1.0.0） 上附加豐富的版本資訊，也能把附帶的 tag messages 轉換成漂亮的日誌格式。

GitHub Releases 產生的日誌只能在 GitHub 上瀏覽，雖然 GitHub Releases 能做出接近本專案範例的日誌格式，但這會增加些許與 GitHub 的相依性。

現行的 GitHub Releases 畢竟不像典型的大寫文件（README、CONTRIBUTING 之類的），按理說會增加使用者找到的難度。另外還有個小問題，目前 GitHub Releases 頁面上並沒有提供兩版版本之間 commit logs 的連結。

更新日誌能被自動生成嗎？

非常困難，各式各樣的提交訊息和檔案名稱難以完全掌握。

另外，有些開源專案使用由 Gemnasium 團隊開發的 Vandamme 轉換更新日誌，或許可以當作參考。

那麼被撤下的版本呢？

因為重大漏洞或安全性問題而被撤下（unpublished）的版本通常不會出現在日誌裡，但建議仍然記錄下來。你可以這樣記錄它們：

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

其中 [YANKED] 標記應該和原因顯眼地標示在一起，讓使用者注意到它是最重要的事。此外，用中括弧能讓轉換用的程式更容易辨認它們。

可以更改過去版本的日誌內容嗎？

當然可以，總是會有好的原因來改善以往寫下的日誌。我也時常發 pull request 給更新日誌不齊全的開源專案。

偶爾會發現自己遺漏了某項重大更新的紀錄，很明顯你應該補齊它們。

我能做些什麼嗎？

這份文件並不是《真理》，而是我經過深思熟慮、遵循蒐集到的資訊和範例之後提出的建議。

源於我期望社群能達到共識，我相信討論的過程與結果一樣重要。

所以，加入我們吧 ٩(｡・ω・｡)و

訪談

我在 The Changelog podcast 上講述了為什麼維護者與協作者應該在意更新日誌，以及建立這項專案背後的契機。

最新版 (1.1.0) 暫時還沒有翻譯到正體中文，您可以閱讀最新的英語版，並且幫助翻譯，不勝感激。

如何維護更新日誌

別讓你的更新日誌成為 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.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [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

更新日誌是什麼？

更新日誌（Changelog）是說明專案在開發過程中，版本之間的差異紀錄，由開發人員由新而舊撰寫。

為什麼需要提供更新日誌？

為了讓使用者和開發人員更簡單明確地了解各個版本之間有著哪些改動。

哪些人需要更新日誌？

大家都需要更新日誌。

無論是開發人員或是使用者，都會在意軟體包含了什麼東西。 當軟體更新了，大家都想知道改了些什麼以及為什麼要改。

如何寫出高品質的日誌？

撰寫原則

  • 更新日誌是寫給「人」看的，不是機器。
  • 每個版本都應該有獨立的進入點。
  • 相同類型的改動應該被分類在同一組。
  • 版本與章節應「可連結化」。
  • 新版本總是寫在最前面。
  • 每個版本都應該註記發佈日期。
  • 版本命名應遵守語意化版本格式。

改動類型

  • Added ：當增加了新功能。
  • Changed ：當更動了既有的功能。
  • Deprecated ：當功能將在近期被移除。
  • Removed ：當移除了現有的功能。
  • Fixed ：當修復了某些錯誤。
  • Security ：當增進了安全性漏洞。

如何提升維護「更新日誌」的效率？

在日誌上方使用 Unreleased 區塊記錄即將發佈的更新內容。

這麼做能夠：

  • 讓大家知道在未來的版本中可能會有哪些改動。
  • 發佈新版本時，直接將 Unreleased 移到新版本的區塊就完成了 ヾ(*´ω｀*)ノ

不就只是個日記而已嗎？難道可以把日誌得很糟嗎？

當然，下面有些糟糕的範例：

🚫 直接複製 git log 到更新日誌

直接把 git log 複製一份成更新日誌絕對不是個好主意。

git log 充滿了各種瑣碎的訊息，像 merge commits、亂七八糟的提交訊息或是文件更新等。

Commits 的目的應該是記錄原始碼演進的過程，有些專案會清理 commits，但有些不會。

更新日誌的目的則是記錄那些值得一提的改動，經常涵蓋多個 commits，最終目的仍然是讓看的人一目了然。

🚫 忽略 Deprecations

當使用者升級版本時，他應該要能預先知道哪些環節可能會出問題，然而，在理想的狀況下，應該讓使用者有空間能預先升級即將被棄用的功能，替換掉棄用功能之後，再升級至棄用功能被真正移除的版本。

即使不這麼做，也要在更新日誌中列出棄用的、移除的或是任何可能導致程式碼失效的重大改動。

🚫 容易混淆的日期格式

在世界的每個角落，不同區域有著不同的時間格式，找到讓大家都滿意的日期格式不是件簡單的事。使用像 2017-07-17 的格式能清楚傳達日期，而且不易與其他日期格式混淆，同時也遵守 ISO 標準，因此推薦使用像這樣的日期格式。

常見問題

有沒有標準格式可以參考呢？

並沒有。雖然有 GNU 更新日誌指南 以及只有兩段長的 GNU - The NEWS File 指南（括弧笑），但這些並不足以稱為「標準」。

這項專案的宗旨在於提供一個 更好的更新日誌範例，源於觀察開源社群中優秀的實際案例，把它們蒐集在一起。

歡迎各位提供有建設性的建議和批評。

更新日誌的檔案名稱應該是？

通常使用 CHANGELOG.md。也有用 HISTORY、NEWS、或是 RELEASES 的例子。

或許你認為取什麼名字並不是件多麼重要的事，但為什麼要讓只是想看日誌的使用者不容易找到它呢？

那麼 GitHub Releases 呢？

這是個好問題。GitHub Releases 能手動在簡單的 git tag（如 v1.0.0） 上附加豐富的版本資訊，也能把附帶的 tag messages 轉換成漂亮的日誌格式。

GitHub Releases 產生的日誌只能在 GitHub 上瀏覽，雖然 GitHub Releases 能做出接近本專案範例的日誌格式，但這會增加些許與 GitHub 的相依性。

現行的 GitHub Releases 畢竟不像典型的大寫文件（README、CONTRIBUTING 之類的），按理說會增加使用者找到的難度。另外還有個小問題，目前 GitHub Releases 頁面上並沒有提供兩版版本之間 commit logs 的連結。

更新日誌能被自動生成嗎？

非常困難，各式各樣的提交訊息和檔案名稱難以完全掌握。

另外，有些開源專案使用由 Gemnasium 團隊開發的 Vandamme 轉換更新日誌，或許可以當作參考。

那麼被撤下的版本呢？

因為重大漏洞或安全性問題而被撤下（unpublished）的版本通常不會出現在日誌裡，但建議仍然記錄下來。你可以這樣記錄它們：

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

其中 [YANKED] 標記應該和原因顯眼地標示在一起，讓使用者注意到它是最重要的事。此外，用中括弧能讓轉換用的程式更容易辨認它們。

可以更改過去版本的日誌內容嗎？

當然可以，總是會有好的原因來改善以往寫下的日誌。我也時常發 pull request 給更新日誌不齊全的開源專案。

偶爾會發現自己遺漏了某項重大更新的紀錄，很明顯你應該補齊它們。

我能做些什麼嗎？

這份文件並不是《真理》，而是我經過深思熟慮、遵循蒐集到的資訊和範例之後提出的建議。

源於我期望社群能達到共識，我相信討論的過程與結果一樣重要。

所以，加入我們吧 ٩(｡・ω・｡)و

訪談

我在 The Changelog podcast 上講述了為什麼維護者與協作者應該在意更新日誌，以及建立這項專案背後的契機。