Pencatatan Changelog

Standarisasi pencatatan Changelog untuk kolaborasi yang lebih baik

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

## [Unreleased]

## [2.0.0] - 2026-06-07

2.0.0 is the first major revision of Keep a Changelog. The format itself
does not change: the six change types, the
`YYYY-MM-DD` dates, and the `Unreleased` and `[YANKED]` markers all stay the same,
so nothing you have already written becomes invalid. What changes is the guidance
around it. 2.0.0 answers the questions the community has raised most often over the
years (marking breaking changes, versioning beyond SemVer, monorepos, the
boundary between Changed, Fixed, and Security) and adds guidance for an era in
which an LLM can draft a changelog from a diff in seconds. Along the way the
page is restructured from a flat FAQ into integrated guidance, given a new
tagline and a redesigned, accessible site, and gathers a round of wording
refinements that were never worth re-translating over on their own.

### Added

- New guidance answering long-standing community questions: the `# Changelog`
  header preamble; marking breaking changes and where upgrade steps belong;
  choosing between Changed, Fixed, and Security; leading a Security entry with its
  CVE; why the six change types don't grow; versioning schemes beyond SemVer;
  linking each version to a `compare` diff with reference links; changelogs versus
  release notes, how to derive one from the other without duplicate work, and why
  a host's generated release notes are vendor lock-in; optional per-release
  summaries; LLM-generated changelogs and a brief you can drop into an `AGENTS.md`;
  Conventional Commits; fitting a changelog into CI/CD; linking to issues and pull
  requests; crediting contributors; very large changelogs; monorepos; and a
  statement of what Keep a Changelog deliberately won't do.
- A redesigned site for 2.0: light and dark themes with a header
  switch (system, light, or dark); a header that pins below the hero as you
  scroll, keeping the language and theme controls and the brand wordmark within
  reach while reading; a sticky table-of-contents sidebar that collapses to a
  menu on small screens; a responsive header whose language picker collapses
  behind a globe icon on narrow screens; a "Changelog basics" intro shown as
  What/Why/Who cards; heading anchor links; indented lists; the topographic hero
  pattern and tree-ring mark (in the brand accent) restored; and Tyler Fortune's
  badge added to the footer, all meeting WCAG 2.1 AA. The English 2.0.0 page is
  now authored in Markdown, with reference-style links and fenced code examples.
- A note in the References section on the convention's reach: now translated into
  dozens of languages and used by tens of thousands of open-source projects.
- 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.
- v1.1 Swedish translation.

### Changed

- New tagline: "Clearly document the evolution of your projects." It replaces
  "Don't let your friends dump git logs into changelogs." The new line is active,
  idiom-free, and easier to translate. Earlier versions keep the original line.
- Restructured the page from a flat list of FAQs into integrated guidance:
  a how-to section (principles, types, breaking changes, structuring a release,
  curation, file naming, the header preamble, and release notes), a section on
  what makes a changelog worse, a section on automation and LLMs, a "Less common
  questions" section, and leaner About and References sections. The voice is
  plainer and less first-person, with translators in mind.
- Reworded and modernized several existing sections (what and why a
  changelog exists, the guiding principles, reducing maintenance effort, automatic
  parsing, rewriting, and contributing). These clarifications weren't significant
  enough to justify re-translating the page for a minor release, so they were
  held back and batched into this major version instead.
- Reframed the old "GitHub Releases" answer as "Is a changelog the same as
  release notes?", broadened beyond GitHub to any host's release system, with the
  case for keeping the canonical, portable record in your repository.
- 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

- Outdated specifics from two answers (the Vandamme gem reference, in
  "can changelogs be automatically parsed?", and a GitHub-Releases discoverability
  note) in favor of more general guidance.
- The FAQ scaffolding and most of the first-person framing, in favor of plainer
  prose; the personal podcast note now lives in a synthesized References section.
- Trademark sign previously shown after the project description in version 
0.3.0

## [1.1.1] - 2023-03-05

### Added

- v1.1 Arabic translation.
- v1.1 French translation.
- v1.1 Dutch translation.
- v1.1 Russian translation.
- v1.1 Japanese translation.
- v1.1 Norwegian Bokmål translation.
- v1.1 "Inconsistent Changes" Turkish translation.
- 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.
- Improve id-ID translation.
- Improve Persian translation.
- Improve Russian translation.
- Improve Swedish title.
- Improve zh-CN translation.
- Improve French translation.
- Improve zh-TW translation.
- Improve Spanish (es-ES) transltion.
- Foldout menu in Dutch translation.
- Missing periods at the end of each change.
- 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.
- Georgian translation from.
- Changelog inconsistency section in Bad Practices.

### Fixed

- Italian translation.
- Indonesian translation.

## [1.0.0] - 2017-06-20

### Added

- New visual identity by [@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].
- German translation from [@mpbzh] & [@Art4].
- Italian translation from [@azkidenz].
- Swedish translation from [@magol].
- Turkish translation from [@emreerkan].
- French translation from [@zapashcanon].
- Brazilian Portuguese translation from [@Webysther].
- Polish translation from [@amielucha] & [@m-aciek].
- Russian translation from [@aishek].
- Czech translation from [@h4vry].
- Slovak translation from [@jkostolansky].
- Korean translation from [@pierceh89].
- Croatian translation from [@porx].
- Persian translation from [@Hameds].
- Ukrainian translation from [@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].
- pt-BR translation from [@tallesl].
- es-ES translation from [@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] 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/v2.0.0...HEAD
[2.0.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.1...v2.0.0
[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
[SemVer]: https://semver.org
[@tylerfortune8]: https://github.com/tylerfortune8
[@tianshuo]: https://github.com/tianshuo
[@mpbzh]: https://github.com/mpbzh
[@Art4]: https://github.com/Art4
[@azkidenz]: https://github.com/azkidenz
[@magol]: https://github.com/magol
[@emreerkan]: https://github.com/emreerkan
[@zapashcanon]: https://github.com/zapashcanon
[@Webysther]: https://github.com/Webysther
[@amielucha]: https://github.com/amielucha
[@m-aciek]: https://github.com/m-aciek
[@aishek]: https://github.com/aishek
[@h4vry]: https://github.com/h4vry
[@jkostolansky]: https://github.com/jkostolansky
[@pierceh89]: https://github.com/pierceh89
[@porx]: https://github.com/porx
[@Hameds]: https://github.com/Hameds
[@osadchyi-s]: https://github.com/osadchyi-s
[@tallesl]: https://github.com/tallesl
[@ZeliosAriex]: https://github.com/ZeliosAriex

Apa itu changelog?

Changelog adalah sebuah file berisi perubahan penting setiap versi sebuah proyek yang kronologis dan terkurasi.

Kenapa mencatat changelog?

Agar perubahan penting antar versi sebuah proyek lebih mudah diamati bagi pengguna maupun kontributor.

Siapa yang membutuhkan changelog?

Kita semua. Baik itu pengguna atau pengembang, konsumen perangkat lunak adalah manusia yang peduli akan isi perangkat lunak tersebut. Kita semua ingin mengetahui bagaimana perangkat lunak tersebut berubah dan alasan dibalik perubahan tersebut.

Bagaimana cara mencatat changelog yang baik?

Panduan Dasar

Changelog dicatat untuk manusia, bukan mesin.
Ada catatan untuk setiap versi.
Perubahan dengan jenis yang sama dikelompokkan.
Tercantum rujukan untuk versi dan seksi.
Versi terbaru tercatat di bagian teratas.
Tanggal rilis setiap versi tercatat.
Sebutkan apakah anda mengikuti Semantic Versioning.

Jenis Perubahan

Added/Ditambahkan untuk fitur baru.
Changed/Diubah untuk perubahan pada fitur yang sudah ada.
Deprecated/Akan Dihilangkan untuk fitur yang akan dihilangkan dalam waktu dekat.
Removed/Dihilangkan untuk fitur yang telah dihilangkan.
Fixed/Diperbaiki untuk perbaikan bugs.
Security/Keamanan jika ada kerentanan.

Bagaimana cara mempermudah pemeliharaan changelog?

Sediakan bagian Unreleased/Belum Dirilis di atas file changelog untuk mencatat perubahan yang akan datang.

Manfaat bagian ini:

Kita dapat melihat perubahan yang akan datang.
Bagian Unreleased/Belum Dirilis dapat dipindahkan ke catatan versi terbaru saat sudah rilis.

Apakah bisa changelog menjadi tidak bermanfaat?

Bisa. Berikut sedikit contoh bagaimana keberadaan changelog menjadi tidak membantu:

Menggunakan pesan commit log diff seadanya

Pesan commit log diff (perbedaan sebuah file antar versi) merupakan catatan yang buruk untuk dijadikan changelog karena seringkali mereka tidak bermakna. Contohnya seperti merge commit, commit berjudul samar, perubahan dokumentasi, dan lainnya.

Tujuan pesan commit adalah mendokumentasikan sebuah tindakan dalam source code. Pesan ini bisa jadi tidak dirapikan.

Tujuan sebuah catatan dalam changelog adalah mendokumentasikan perubahan-perubahan yang patut diperhatikan, dimana catatan ini seringkali merangkum perubahan serangkaian commit agar mudah dimengerti.

Mengabaikan Deprecations (fitur yang akan dihilangkan)

Jika ada perubahan yang tidak kompatibel dari satu versi ke versi lainnya, perubahan ini seharusnya teramat jelas bagi orang-orang. Saat kita menggunakan sebuah versi perangkat lunak yang di dalamnya terdapat fitur yang akan dihilangkan (Deprecated), seharusnya kita dapat menghapus fitur tersebut lalu melakukan upgrade ke versi dimana fitur tersebut sudah dihilangkan (Removed).

Catat fitur yang akan dihapus, telah dihapus, dan perubahan tidak kompatibel pada changelog anda jika anda tidak mencoba hal tersebut.

Perbedaan Format Tanggal

Mencari pola tanggal yang intuitif dan mudah dipahami oleh semua orang adalah masalah yang sulit. Hal ini karena pola tanggal di satu belahan bumi akan berbeda dengan belahan bumi lainnya. Tanggal yang disusun dalam pola 2017-07-17 memiliki keuntungan dimana pola tersebut dimulai dari unit terbesar: tahun, bulan, lalu hari. Format ini juga tidak tumpang tindih dengan format tanggal lainnya. Berbeda dengan format tanggal regional yang terkadang menukar posisi angka bulan dan tanggal. Format tanggal ini direkomendasikan dalam catatan changelog bukan hanya karena alasan yang telah disebut, tetapi juga karena pola ini mengikuti ISO standard untuk penulisan tanggal.

Pencatatan yang tidak konsisten

Catatan changelog yang tidak lengkap sama bahayanya dengan tidak mencatatnya sama sekali. Walau perubahan kecil - menghapus sebuah spasi misalnya - mungkin tidak perlu dicatat, semua perubahan penting yang patut diperhatikan harus disebut dan tercatat di changelog. Jika dilakukan setengah-setengah konsumen perangkat lunak anda akan berpikir mereka sedang membaca changelog yang benar, padahal kenyataannya salah. Changelog seharusnya selalu benar. Changelog yang baik adalah changelog yang selalu diperbarui. Jika anda ingin memiliki changelog yang baik, inilah tanggung jawab anda.

Pertanyaan yang Sering Diajukan

Apakah ada format standar untuk sebuah changelog?

Tidak, sih. Ada Panduan Ragam Penulisan Changelog GNU, atau "panduan" dua paragraf untuk GNU NEWS file. Tapi keduanya antara tidak mumpuni atau tidak lengkap.

Proyek ini ingin menghasilkan konvensi changelog yang lebih baik. Hal-hal yang diutarakan merupakan sekumpulan pengamatan berbagai disiplin baik yang telah diadopsi oleh komunitas open source lain.

Kritik sehat, saran, dan diskusi untuk meningkatkan proyek ini dipersilakan.

Sebaiknya file changelog diberi nama apa?

Sebut saja CHANGELOG.md. Beberapa proyek menyebutnya HISTORY, NEWS or RELEASES.

Walau perihal nama ini sepertinya sepele, kenapa pengguna perangkat lunak anda yang mencari perubahan penting harus dibuat sulit?

Bagaimana dengan GitHub Releases?

Github Releases merupakan upaya yang baik. Releases dapat merubah git tag (contohnya sebuah tag dengan judul v1.0.0) menjadi catatan rilis yang informatif dengan menambahkan catatan secara manual atau dengan memanfaatkan pesan-pesan git tag dan merubahnya menjadi catatan.

Changelog yang dihasilkan oleh GitHub Releases bermanfaat hanya dalam konteks pengguna GitHub. Hasil catatannya dapat dibuat menyerupai format Pencatatan Changelog namun akan rumit.

GitHub releases yang sekarang tidak begitu mudah ditemukan oleh pengguna, berbeda dengan file-file (README, CONTRIBUTING, dll.). Tautan menuju commit log antar versi rilis juga tidak ditampilkan di antarmuka pengguna.

Apakah changelog dapat diuraikan secara otomatis?

Sulit, karena orang-orang mengikuti panduan format dan nama file yang berbeda-beda.

Vandamme adalah sebuah Ruby gem yang diciptakan oleh tim Gemnasium dan mampu menguraikan changelog proyek-proyek open source (tapi tidak semua).

Bagaimana dengan rilis yang dibatalkan (YANKED)?

Rilis bertanda Yanked artinya versi tersebut ditarik karena adanya bug atau masalah kerentanan yang serius. Versi-versi ini harusnya dicatat. Tetapi seringkali tidak. Berikut cara mencatatnya:

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

Tag [YANKED] ditulis sedemikian rupa. Hal ini karena orang-orang harus melihatnya. Selain huruf kapital, dengan menulisnya di dalam kurung siku akan mempermudah penguraian catatan ini secara programatis.

Bolehkah anda menulis ulang sebuah changelog?

Boleh saja. Memperbarui sebuah changelog merupakan ide yang baik. Saya rutin membuat pull request untuk menambahkan versi-versi yang tidak tercatat dalam changelog proyek open source yang tidak dirapikan.

Memperbarui dan mencermati changelog itu penting. Apalagi jika anda lupa untuk mencatat perubahan yang tidak kompatibel pada versi tertentu.

Bagaimana saya dapat berkontribusi?

Dokumen ini bukanlah sesuatu yang mutlak; melainkan sebuah opini yang terbentuk setelah saya mempertimbangkan banyak hal, meliputi informasi dan contoh-contoh yang saya kumpulkan.

Saya ingin komunitas ini mencapai sebuah mufakat. Saya yakin diskusi yang muncul untuk menghasilkan sebuah keputusan adalah sama pentingnya dengan keputusan tersebut.

Jadi, silahkan kirim saran.

Percakapan

Saya berbicara tentang mengapa kontributor dan maintainer seharusnya mencermati changelog di The Changelog podcast, disana saya juga berbicara tentang motivasi di belakang proyek ini.