შეინარჩუნე ცვლილებების ჟურნალი

არ მისცე უფლება მეგობრებს 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.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

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

### Changed

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

### Removed

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

## [1.1.1] - 2023-03-05

### Added

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

### Fixed

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

### Changed

- Upgrade dependencies: Ruby 3.2.1, Middleman, etc.

### Removed

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

## [1.1.0] - 2019-02-15

### Added

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

### Fixed

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

## [1.0.0] - 2017-06-20

### Added

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

### Changed

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

### Removed

- Section about "changelog" vs "CHANGELOG".

## [0.3.0] - 2015-12-03

### Added

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

## [0.2.0] - 2015-10-06

### Changed

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

## [0.1.0] - 2015-10-06

### Added

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

### Changed

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

## [0.0.8] - 2015-02-17

### Changed

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

### Fixed

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

## [0.0.7] - 2015-02-16

### Added

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

### Changed

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

### Fixed

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

## [0.0.6] - 2014-12-12

### Added

- README section on "yanked" releases.

## [0.0.5] - 2014-08-09

### Added

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

## [0.0.4] - 2014-08-09

### Added

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

### Changed

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

### Removed

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

## [0.0.3] - 2014-08-09

### Added

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

## [0.0.2] - 2014-07-10

### Added

- Explanation of the recommended reverse chronological release ordering.

## [0.0.1] - 2014-05-31

### Added

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

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

რა არის ცვლილებების ჟურნალი (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 პოდკასტის სტუმარი და ვისაუბრე რატომ უნდა იზრუნონ ცვლილებების ჟურნალზე კონტრიბუტორებმა და ისინი ვინც კოდს ინარჩუნებენ ყველაზე მეტად. ამავდროულად მოტივაციაზე ამ პროექტის უკან.