Değişiklik kaydı 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.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

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.