mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-08-26 04:08:12 +02:00
298 lines
21 KiB
Plaintext
298 lines
21 KiB
Plaintext
---
|
|
description: შეინარჩუნე ცვლილებების ჟურნალი
|
|
title: შეინარჩუნე ცვლილებების ჟურნალი
|
|
language: en
|
|
version: 1.0.0
|
|
---
|
|
|
|
- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
|
|
- gh = "https://github.com/olivierlacan/keep-a-changelog"
|
|
- issues = "https://github.com/olivierlacan/keep-a-changelog/issues"
|
|
- semver = "https://semver.org/"
|
|
- shields = "https://shields.io/"
|
|
- thechangelog = "https://changelog.com/podcast/127"
|
|
- vandamme = "https://github.com/tech-angels/vandamme/"
|
|
- iso = "http://www.iso.org/iso/home/standards/iso8601.htm"
|
|
- ghr = "https://help.github.com/articles/creating-releases/"
|
|
- gnustyle = "https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs"
|
|
- gnunews = "https://www.gnu.org/prep/standards/html_node/NEWS-File.html#NEWS-File"
|
|
|
|
.header
|
|
.title
|
|
%h1 შეინარჩუნე ცვლილებების ჟურნალი
|
|
%h2 არ მისცე უფლება მეგობრებს git ჩანაწერები ჩაწერონ ცვლილებების ჟურნალში
|
|
|
|
= link_to changelog do
|
|
Version
|
|
%strong= current_page.metadata[:page][:version]
|
|
|
|
%pre.changelog= File.read("CHANGELOG.md")
|
|
|
|
.answers
|
|
%h3#what
|
|
%a.anchor{ href: "#what", aria_hidden: "true" }
|
|
რა არის ცვლილებების ჟურნალი (changelog)?
|
|
|
|
%p
|
|
ცვლილებების ჟურნალი არის ფაილი რომელიც შეიცავს ქრონოლოგიურად დალაგებულ და კურირებულ სიას
|
|
იმ აღწერებისა რაც პროექტის თითოეულ ვერსიას აქვს
|
|
|
|
%h3#why
|
|
%a.anchor{ href: "#why", aria_hidden: "true" }
|
|
რატომ უნდა მოვუფრთხილდეთ ცვილებების ჟურნალს?
|
|
|
|
%p
|
|
რათა მომხმარებლებმა და კონტრიბუტორებმა ნათლად დაინახონ რა შეიცვალა პროექტის გამოშვებებს (ან ვერსიებს) შორის.
|
|
|
|
|
|
%h3#who
|
|
%a.anchor{ href: "#who", aria_hidden: "true" }
|
|
ვის სჭირდება ცვლილებების ჟურნალი?
|
|
|
|
%p
|
|
ხალხს სჭირდება. მნიშვნელობა არ აქვს მომხმარებელი იქნება თუ დეველოპერი, საბოლოო ჯამში ადამიანები არიან ისინი ვინც
|
|
ზრუნავენ რა არის ამ პროგრამაში. როდესაც პროგრამა იცვლება, ხალხს უნდა იცოდეს რატომ და როგორ.
|
|
|
|
.good-practices
|
|
%h3#how
|
|
%a.anchor{ href: "#how", aria_hidden: "true" }
|
|
როგორ გავაკეთო კარგი ცვლილებების ჟურნალი?
|
|
|
|
%h4#principles
|
|
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
|
მიყევი პრინციპებს
|
|
|
|
%ul
|
|
%li
|
|
ცვლილებების ჟურნალი <em>განკუთვნილია ადამიანებისთვის</em>, არა მანქანებისთვის.
|
|
%li
|
|
თითოეული ვერსიისთვის უნდა არსებობდეს ჩანაწერი.
|
|
%li
|
|
ერთნაირი ტიპის ჩანაწერები უნდა დაჯგფუდეს.
|
|
%li
|
|
ვერსიები და სექციების გადაბმა შესაძლებელი უნდა იყოს.
|
|
%li
|
|
უკანასკნელი ვერსია უნდა ეწეროს პირველი.
|
|
%li
|
|
გამოშვების თარიღი უნდა ეწეროს თითოეულ ვერსიას.
|
|
%li
|
|
ახსენე თუ იყენებ #{link_to "სემანტიკურ ვერსიონირებას", semver}.
|
|
|
|
%a.anchor{ href: "#types", aria_hidden: "true" }
|
|
%h4#types ცვლილებების ტიპი
|
|
|
|
%ul
|
|
%li
|
|
%code Added
|
|
ახალი ფუნქციონალისთვის.
|
|
%li
|
|
%code Changed
|
|
არსებულ ფუნქციონალში შეტანილი ცვლილებებისთვის.
|
|
%li
|
|
%code Deprecated
|
|
მალე წასაშლელი ფუნქციონალისთვის.
|
|
%li
|
|
%code Removed
|
|
უკვე წაშლილი ფუნქციონალისთვის.
|
|
%li
|
|
%code Fixed
|
|
შეცდომების გასწორებისთვის.
|
|
%li
|
|
%code Security
|
|
მოწყვლადობის აღმოჩენის შემთხვევაში.
|
|
|
|
.effort
|
|
|
|
%h3#effort
|
|
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
|
როგორ შევამცირო ძალისხმევა ცვლილებების ჟურნალის შესანარჩუნებლად?
|
|
|
|
%p
|
|
<code>Unreleased</code> სექცია დატოვე ყოველთვის მაღლა რათა მარტივად შეიძლებოდეს დანახვა მომავალი ცვლილებების
|
|
|
|
%p ამას ორი მიზეზი აქვს:
|
|
|
|
%ul
|
|
%li
|
|
ხალხს შეეძლება დაინახოს რა მოსალოდნელი ცვლილებებია მომავალ გამოშვებებში
|
|
%li
|
|
გაშვების დროს შეგიძლია უბრალოდ <code>Unreleased</code> სექცია შეცვალო ახალი ვერსიის სექციად.
|
|
|
|
.bad-practices
|
|
%h3#bad-practices
|
|
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
|
შესაძლებელია ცვლილებების ჟურნალი იყოს ცუდი?
|
|
|
|
%p დიახ. აქ არის რამოდენიმე მაგალითი რომელიც ნათლად გვაჩვენებს ამას.
|
|
|
|
%h4#log-diffs
|
|
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
|
commit-ების ჩანაწერების სხვაობა.
|
|
|
|
|
|
%p
|
|
commit-ების ჩანაწერების სხვაობის გამოყენება ცვლილებების ჟურნალის სახით ცუდი იდეაა:
|
|
სავსეა უსარგებლო ინფორმაციით, მათ შორის: არასწორი სახელებით და დოკუმენტაციის ცვლილებებით.
|
|
|
|
%p
|
|
commit-ის დანიშნულება არის კოდის ევოლუციის აღწერა. ზოგიერთი პროექტი შლის მათ, ზოგიერთი არა.
|
|
|
|
%p
|
|
ცვლილებების ჟურნალში ჩანაწერის მიზანი არის მნიშვნელოვანი ცვლილებები აღწეროს, ხშირად რამოდენიმე კომიტის
|
|
ერთად, რათა მარტივად იყოს საბოლოო მომხმარებლებისთვის გასაგები.
|
|
|
|
%h4#ignoring-deprecations
|
|
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
|
მოძველებული ფუნქციონალის იგნორირება
|
|
|
|
%p
|
|
როდესაც ხალხი ერთი ვერსიიდან განახლებას აკეთებს შემდგომზე, აშკარა უნდა იყოს რა შეიძლება გაფუჭდეს.
|
|
ჯერ განაახლე ისეთ ვერსიაზე რომელსაც აქვს მოძველებული ფუნქციონალის სია, წაშალე რაც მოძველდა და შემდგომ
|
|
ისეთ ვერსიაზე განაახლე სადაც მოძველებული ფუნქციონალი უკვე წაშლილია.
|
|
|
|
%p
|
|
თუ სხვა არაფერს აკეთებ, ჩამოწერე რაც მოძველდა, რაც წაიშალა და ნებისმიერი სხვა ცვლილება ამ ჟურნალში.
|
|
|
|
|
|
%h4#confusing-dates
|
|
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
|
დამაბნეველი თარიღები
|
|
|
|
%p
|
|
რეგიონალური თარიღის ფორმატები განსხვავდება მთელი მსოფლიოს მასშტაბით
|
|
და ხშირად რთულია იპოვო ადამიანისთვის მარტივად გასაგები თარირის ფორმატი,
|
|
რომელიც ინტუიციურია ყველასთვის. <code>2017-07-17</code> ასეთი ფორმატების უპირატესობა
|
|
არის ის, რომ მიმდევრობას ემორჩილება უდიდესიდან უმცირეს საზომ ერთეულამდე:
|
|
წელი, თვე და დღე. ეს ფორმატი ასევე არ ემთხვევა სხვა თარიღის ფორმატებს უცნაური ვარიანტებით,
|
|
განსხვავებით სხვა ფორმატებისგან რომლებიც ზოგჯერ ცვლიან დღის და თვის რიცხვების პოზიციას.
|
|
ამ მიზეზთან გამო და იმის გამო, რომ ეს ფორმატი
|
|
#{link_to "ISO სტანდარტია", iso}, იგი რეკომენდირებული თარიღის ფორმატია
|
|
ცვლილებების ჟურნალის ჩანაწერებისთვის.
|
|
|
|
%aside
|
|
დამეხმარე სხვა არაზუსტი შაბლონების შეგროვებაში
|
|
= link_to "ახალი საკითხის გახსნით", issues
|
|
ან pull მოთხოვნით.
|
|
|
|
.frequently-asked-questions
|
|
%h3#frequently-asked-questions
|
|
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
|
ხშირად დასმული კითხვები
|
|
|
|
%h4#standard
|
|
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
|
არის თუ არა რაიმე სტანდარტული ფორმატი ცვლილებების ჟურნალისთვის?
|
|
|
|
%p
|
|
არა. არსებობს #{link_to "GNU ცვლილებების ჟურნალის სტილი", gnustyle},
|
|
ან #{link_to "2 პარაგრაფის სიგრძის GNU NEWS ფაილი", gnunews}
|
|
"დირექტივა". ორივე შეუფერებელი და არასაკმარისია.
|
|
|
|
%p
|
|
პროექტის მიზანია
|
|
= link_to "ჩამოაყალიბოს უკეთესი კონვენცია ცვლილებების ჟურნალისთვის.", changelog
|
|
რომელიც შედეგია წარმატებულ გამოცდილებებზე დაკვირვების ჩვენს კომუნაში და შემდგომ ერთად თავმოყრის.
|
|
|
|
%p
|
|
ჯანსაღი კრიტიკა, დისკუსია და გაუმჯობესების რჩევები
|
|
= link_to "მისასალმებელია.", issues
|
|
|
|
|
|
%h4#filename
|
|
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
|
რა უნდა დაერქვას ცვლილებების ჟურნალის ფაილს?
|
|
|
|
%p
|
|
დაარქვი <code>CHANGELOG.md</code>. ზოგი პროექტი იყენებს
|
|
<code>HISTORY</code>, <code>NEWS</code> ან <code>RELEASES</code> სახელს.
|
|
|
|
%p
|
|
ადვილია იფიქრო რომ ჟურნალის ფაილის სახელს დიდი მნიშვნელობა არ აქვს,
|
|
მაგრამ რატომ უნდა გაურთულო შენი პროგრამის მომხმარებლებს ცვლილებების ძიება?
|
|
|
|
%h4#github-releases
|
|
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
|
რა ხდება GitHub Releases დროს?
|
|
|
|
%p
|
|
შესანიშნავი ინიციატივაა. #{link_to "Releases", ghr} შესაძლებელია გამოყენებულ იქნას როგორც,
|
|
უბრალო git იარლიყების(tag) (მაგალითად იარლიყი სახელად <code>v1.0.0</code>)
|
|
გადასაქცევად სრულყოფილ გამოშვების ჩანაწერებად ჩვენს მიერ
|
|
ან შესაძლებელია git იარლიყების შეტყობინების ავტომატურად წამოღება და ჩანაწერად ქცევა.
|
|
|
|
%p
|
|
GitHub Releases ქმნის არაპორტაბელურ ცვლილებების ჟურნალს რომელიც
|
|
მხოლოდ GitHub-ის შიგნით შეიძლება იქნას გამოყენებული. შესაძლებელია მათი
|
|
წარმოჩენა სხვა ფორმატით თუმცა უფრო მეტი შრომა სჭირდება.
|
|
|
|
%p
|
|
GitHub Releases მიმდინარე ვერსია არ არის მარტივად საპოვნელი მომხმარებლებისთვის, განსხავებით
|
|
სხვა ტიპიური ფაილებისგან (<code>README</code>, <code>CONTRIBUTING</code> და სხვა.). ასევე ინტერფეისი
|
|
ამ ეტაპზე არ იძლევა საშუალებას გვქონდეს ბმული commit ჩანაწერებზე თითოეულ გამოშვებას შორის.
|
|
|
|
%h4#automatic
|
|
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
|
შესაძლებელია ცვლილებების ჟურნალის ავტომატური სინტაქსური ანალიზი?
|
|
|
|
%p
|
|
რთულია, რადგან ხალხი იყენებს რადიკალურად განსხვავებულ ფორმატებს და ფაილის სახელებს.
|
|
|
|
%p
|
|
#{link_to "Vandamme", vandamme} არის Ruby gem შექმნილი
|
|
Gemnasium გუნდის მიერ რომელიც აანალიზებს უმრავლეს (თუმცა
|
|
ყველას არა) ,ღია პროექტის, ცვლილებების ჟურნალს.
|
|
|
|
|
|
%h4#yanked
|
|
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
|
რა ხდება yanked გამოშვებებისას?
|
|
|
|
%p
|
|
Yanked გამოშვებები არის ისეთი ვერსიები რომლებიც უკან უნდა დაბრუნდეს სერიოზული
|
|
შეცდომის ან უსაფრთხოების პრობლემის გამო. ხშირად ასეთი ვერსიები არც ხვდება ცვლილებების ჟურნალში.
|
|
არადა უნდა გამოჩნდეს და ასე მაგალითად:
|
|
|
|
%p <code>## [0.0.5] - 2014-12-13 [YANKED]</code>
|
|
|
|
%p
|
|
<code>[YANKED]</code> იარლიყი სპეციალურად არის. მნიშვნელოვანია რომ შეამჩნიოს ხალხმა.
|
|
ასევე რადგანაც ის კვადრატულ ფრჩხილებშია მოქცეული, პროგრამულადაც ადვილია სინტაქსური დამუშავება.
|
|
|
|
|
|
%h4#rewrite
|
|
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
|
უნდა გადაწერო თუ არა როდისმე ცვლილებების ჟურნალი?
|
|
|
|
%p
|
|
რათქმაუნდა. ყოველთვის არის მიზეზი რათა გააუმჯობესო ჟურნალი.
|
|
რეგულარულად გახსენი pull მოთხოვნები რათა დაამატო გამოტოვებული გამოშვებები
|
|
სხვადასხვა ღია პროექტების უპატრონოდ მიტოვებულ ცვლილებების ჟურნალს.
|
|
|
|
|
|
%p
|
|
ასევე შესაძლებელია აღმოაჩინო რომ დაგავიწყდა რომელიმე ისეთი ცვლილების ჩაწერა კონკრეტული ვერსიისთვის,
|
|
რაც აფუჭებს პროგრამას. ამ შემთხვევაში აშკარაზე აშკარაა რომ განაახლო შენი ცვლილებების ჟურნალი.
|
|
|
|
|
|
%h4#contribute
|
|
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
|
როგორ შემიძლია კონტრიბუცია?
|
|
|
|
%p
|
|
ეს დოკუმენტი არ არის აბსოლუტური <strong>ჭეშმარიტება</strong>; ეს უფრო არის ჩემს მიერ გათვალისწინებული მოსაზრებები
|
|
სხვადასხვა მაგალითებთან და მოპოვებულ ინფორმაციასთან ერთად.
|
|
|
|
%p
|
|
მინდა რომ ჩვენმა კომუნამ მიაღწიოს კონსესუსს და მჯერა რომ ეს დისკუსია ისეთივე მნიშვნელოვანია როგორც საბოლოო შედეგი.
|
|
|
|
|
|
%p
|
|
ასე რომ გთხოვ <strong>#{link_to "ჩაერთე", gh}</strong>.
|
|
|
|
.press
|
|
%h3 საუბრები
|
|
%p
|
|
ვიყავი #{link_to "The Changelog პოდკასტის", thechangelog} სტუმარი და ვისაუბრე
|
|
რატომ უნდა იზრუნონ ცვლილებების ჟურნალზე კონტრიბუტორებმა და ისინი ვინც კოდს ინარჩუნებენ ყველაზე მეტად.
|
|
ამავდროულად მოტივაციაზე ამ პროექტის უკან.
|