CHANGELOG file kullanımı, Avantajları ve Zorlukları
İster mobil ister farklı bir platform olsun uzun soluklu projelerde en sık karşılaşılan problemlerden biri neyin, ne zaman yayınladığıdır. Bu hem developer hem business hem de product ekipleri için mutlaka günün birinde sorulacak olan sorudur?
X Hanım : “A feature’ını ne zaman çıkmıştık hatırlıyor musunuz?”
Y Bey : “Sanırım geçtiğimiz sene Mart ayında çıkmıştık? Ama emin değilim. Bu arada bununla beraber hangi feature’lar gitti?”
Yukarıdaki dialog çok tanıdık geldi değil mi? Peki bir sonraki release içerisinde hangi işler gidecek onları nasıl takip edebiliriz. Yanıt : “Changelog file kullanımı ”
Changelog file nedir?
Aslında kısaca değişikliklerin saklandığı bir günlük diyebiliriz. Kronolojik olarak yapılan bütün değişiklikler buraya değişikliği yapan developer tarafından eklenir. Sadece geçmiş sürümlerdeki değişiklikler değil, hali hazırda yapılan değişiklikler de [unreleased] tag’i altında bu dosyada yer alır. Burdaki amaç çıkılacak release içerisinde hangi geliştirmelerin yer aldığını görmektir.
Bir çok open-source proje’de ana dizinde yer alan Changelog file’ı eminim hepiniz en az bir github projesinde görmüşsünüzdür. Son zamanlarda hep “CHANGELOG” ismiyle kullanılsa da “CHANGES”,”HISTORY” ve “NEWS” şeklinde de adlandırılabilirler.
Format ve Kullanım
Önceden bir çok yazılım projesinde “CHANGELOG” file formatı oradaki yazılımcıların stilini yansıtırdı. Günümüzde nisbeten standart bir format takip ediliyor. Bunlardan birisi GNU tarafında kullanılan stil.(https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html#Style-of-Change-Logs)
2019-08-29 Noam Postavsky <npostavs@gmail.com>Handle completely undecoded input in term (Bug#29918) * lisp/term.el (term-emulate-terminal): Avoid errors if the whole
decoded string is eight-bit characters. Don't attempt to save the
string for next iteration in that case.
* test/lisp/term-tests.el (term-decode-partial)
(term-undecodable-input): New tests.2019-06-15 Paul Eggert <eggert@cs.ucla.edu> Port to platforms where tputs is in libtinfow * configure.ac (tputs_library): Also try tinfow, ncursesw (Bug#33977).2019-02-08 Eli Zaretskii <eliz@gnu.org> Improve documentation of 'date-to-time' and 'parse-time-string' * doc/lispref/os.texi (Time Parsing): Document
'parse-time-string', and refer to it for the description of
the argument of 'date-to-time'. * lisp/calendar/time-date.el (date-to-time): Refer in the doc
string to 'parse-time-string' for more information about the
format of the DATE argument. (Bug#34303)
Bir diğer format ise günümüz projelerinde çok fazla karşımıza çıkan Keep a Changelog ekibinin yarattığı stil. (https://keepachangelog.com/en/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.0.0] - 2017-06-20
### Added
- New visual identity by [@tylerfortune8](https://github.com/tylerfortune8).
- Version navigation.
- Links to latest released version in previous versions.
- "Why keep a changelog?" section.
- "Who needs a changelog?" section.
- "How do I make a changelog?" section.
- "Frequently Asked Questions" section.
- New "Guiding Principles" sub-section to "How do I make a changelog?".
- Simplified and Traditional Chinese translations from [@tianshuo](https://github.com/tianshuo).
- German translation from [@mpbzh](https://github.com/mpbzh) & [@Art4](https://github.com/Art4).
- Italian translation from [@azkidenz](https://github.com/azkidenz).
- Swedish translation from [@magol](https://github.com/magol).
- Turkish translation from [@karalamalar](https://github.com/karalamalar).
- French translation from [@zapashcanon](https://github.com/zapashcanon).
- Brazilian Portugese translation from [@Webysther](https://github.com/Webysther).
- Polish translation from [@amielucha](https://github.com/amielucha) & [@m-aciek](https://github.com/m-aciek).
- Russian translation from [@aishek](https://github.com/aishek).
- Czech translation from [@h4vry](https://github.com/h4vry).
- Slovak translation from [@jkostolansky](https://github.com/jkostolansky).
- Korean translation from [@pierceh89](https://github.com/pierceh89).
- Croatian translation from [@porx](https://github.com/porx).
- Persian translation from [@Hameds](https://github.com/Hameds).
- Ukrainian translation from [@osadchyi-s](https://github.com/osadchyi-s).### Changed
- Start using "changelog" over "change log" since it's the common usage.
- Start versioning based on the current English version at 0.3.0 to help
translation authors keep things up-to-date.
- Rewrite "What makes unicorns cry?" section.
- Rewrite "Ignoring Deprecations" sub-section to clarify the ideal
scenario.
- Improve "Commit log diffs" sub-section to further argument against
them.
- Merge "Why can’t people just use a git log diff?" with "Commit log
diffs"
- Fix typos in Simplified Chinese and Traditional Chinese translations.
- Fix typos in Brazilian Portuguese translation.
- Fix typos in Turkish translation.
- Fix typos in Czech translation.
- Fix typos in Swedish translation.
- Improve phrasing in French translation.
- Fix phrasing and spelling in German translation.### Removed
- Section about "changelog" vs "CHANGELOG".## [0.3.0] - 2015-12-03
### Added
- RU translation from [@aishek](https://github.com/aishek).
- pt-BR translation from [@tallesl](https://github.com/tallesl).
- es-ES translation from [@ZeliosAriex](https://github.com/ZeliosAriex).## [0.2.0] - 2015-10-06
### Changed
- Remove exclusionary mentions of "open source" since this project can
benefit both "open" and "closed" source projects equally.## [0.1.0] - 2015-10-06
### Added
- Answer "Should you ever rewrite a change log?".### Changed
- Improve argument against commit logs.
- Start following [SemVer](https://semver.org) properly.## [0.0.8] - 2015-02-17
### Changed
- Update year to match in every README example.
- Reluctantly stop making fun of Brits only, since most of the world
writes dates in a strange way.### Fixed
- Fix typos in recent README changes.
- Update outdated unreleased diff link.## [0.0.7] - 2015-02-16
### Added
- Link, and make it obvious that date format is ISO 8601.### Changed
- Clarified the section on "Is there a standard change log format?".### Fixed
- Fix Markdown links to tag comparison URL with footnote-style links.## [0.0.6] - 2014-12-12
### Added
- README section on "yanked" releases.## [0.0.5] - 2014-08-09
### Added
- Markdown links to version tags on release headings.
- Unreleased section to gather unreleased changes and encourage note
keeping prior to releases.## [0.0.4] - 2014-08-09
### Added
- Better explanation of the difference between the file ("CHANGELOG")
and its function "the change log".### Changed
- Refer to a "change log" instead of a "CHANGELOG" throughout the site
to differentiate between the file and the purpose of the file — the
logging of changes.### Removed
- Remove empty sections from CHANGELOG, they occupy too much space and
create too much noise in the file. People will have to assume that the
missing sections were intentionally left out because they contained no
notable changes.## [0.0.3] - 2014-08-09
### Added
- "Why should I care?" section mentioning The Changelog podcast.## [0.0.2] - 2014-07-10
### Added
- Explanation of the recommended reverse chronological release ordering.## [0.0.1] - 2014-05-31
### Added
- This CHANGELOG file to hopefully serve as an evolving example of a
standardized open source project CHANGELOG.
- CNAME file to enable GitHub Pages custom domain
- README now contains answers to common questions about CHANGELOGs
- Good examples and basic guidelines, including proper date formatting.
- Counter-examples: "What makes unicorns cry?"
Bizim de kullandığımız ve son dönemlerde yaygın olarak kullanılan Keep a Changelog ekibinin stilinin kullanımından kısaca bahsedecek olursak:
- Unreleased ve en son sürüm her zaman yukarıda geliyor. Yani ters kronolojik bir akış söz konusu.
- [Added] eklenen yeni feature’lar bu tag’in altında listelenir.
- [Changed] mevcut işlevsellikte yapılan değişiklikler burda listelenir. Yalnızca teknik değişiklikler değil, business ve logical değişiklikler de yazılmalıdır.
- [Deprecated] bu tag’in altında önceki sürümlerde bulunan ama yakın zamanda silinecek feature’lar listelenir.
- [Removed] bu sürüm ile beraber kaldırılan feature’lar listelenir.
- [Fixed] projelerin olmazsa olmazlarından olan bug-fix’ler bu tag altında yer alır.
- [Security] yapılan güvenlik açıkları geliştirmeleri de bu tag altında listelenir.
Avantajları
Günümüzde özellikle pandeminin etkisi ile artık birçoğumuz tamamen evden çalışmaya başladık. Eski alışkanlıklarımızın bir çoğunun değiştiğine şahitlik ediyoruz. Örneğin artık işyerinde arkadaşımızdan kolayca alacağımız yanıtları almak artık daha zor. Çünkü artık sadece online olarak birbirimize ulaşabiliyoruz. Bu durumda tüm paydaşlar olarak herkesin align olması için “CHANGELOG” kullanımı gerçekten çok basit ve faydalı bir çözüm. Avantajlarını listeleştirecek olursak :
- Kullanım amacı ve en büyük faydası projenin tarihçesini ve sonraki release’in içeriğini göstermek.
- Dağıtık ekiplerin birbirlerinin yaptıkları işlerden haberdar olup, up to date kalmak.
- Geçmiş release’lerin içeriklerini inceleyerek,hangi sürümde hangi feature release edilmiş bilgi sahibi olmak. Böylece bazı dataları anlamlandırmak için input almak.
- Şeffaflığı artırarak takım olma güdüsüne ivme kazandırmak.
- Product ve Business ekiplerinin ileriyi görmelerine olanak sağlamak. Böylece daha detaylı ve tutarlı planlara sahip olmak.
Zorlukları
Aslında tek başınıza veya küçük bir ekiple birlikte proje geliştiriyorsanız “CHANGELOG” file kullanımının bir zorluğu bulunmuyor. Fakat büyük development takımlarıyla ve dağıtık ekiplerle iş geliştirdiğinizde “CHANGELOG” file kullanımının önemiyle birlikte zorluğu da artıyor. En büyük problem aslında conflict yaşanması. Bir çok developer aynı anda “CHANGELOG” file üzerinde değişiklik yapıyor ve conflict ile karşılaşıyor. Bunları da çözmek özellikle Junior developer’lar için bir sorun haline gelebiliyor. Aynı zamanda eğer bir build pipeline ile entegre çalışıyorsanız, build süreleri ile azımsanmayacak bir zaman kaybı yaşayabilirsiniz.
Biz de getirdiği kolaylıkların ve işlevselliğin yanında zorluklarıyla yüzleşiyoruz. Bunlara çözüm olarak ürettiğimiz kendi çözümlerimiz de var. Fakat bu da bir başka makalenin konusu olsun.
“CHANGELOG” dosyanız uzun, tag’lerinizin altı dolu olsun :) Görüşmek üzere.
