Keep a Changelog

동료들이 git 로그를 그대로 changelogs에 올리게 내버려 두지 마세요.

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]

## [1.1.2] - 2024-09-27

### Added

- v1.1 German translation.
- v1.1 Italian translation.
- v1.1 Simplified Chinese translation.
- v1.1 Persian translation.
- v1.1 Polish translation.
- v1.1 Slovenian translation.
- v1.1 Traditional Chinese translation.
- v1.1 Spanish translation.
- v1.1 Brazilian Portuguese translation.
- v1.1 Czech translation.
- v1.1 Romanian translation.
- v1.1 Swedish translation.
- v1.1 Ukrainian translation.
- v1.1 Korean translation.
- v1.1 Indonesian translation.

### Fixed

- Improve French translation.
- Improve Dutch translation.

## [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/v1.1.2...HEAD
[1.1.2]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.1...v1.1.2
[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

Changelog는 무엇인가요?

Changelog는 프로젝트의 각 버전에 대해 주목할 만한 변경 사항들을 시간 순서대로 정리한 파일입니다.

왜 changelog를 유지해야 하나요?

사용자와 기여자가 프로젝트의 각 릴리즈(또는 버전)간에 정확히 어떤 주목할만한 변경 사항이 있는지 알기 쉬워집니다.

누가 changelog를 필요로 하나요?

사람들이 필요로 합니다. 개발자이든 사용자이든, 소프트웨어의 최종 사용자는 소프트웨어에 무엇이 있는지 관심이 있는 사람입니다. 소프트웨어에 변경 사항이 있을 때, 사람들은 왜 그리고 어떻게 바뀌었는지 알고 싶어 합니다.

어떻게 좋은 changelog를 만들수 있나요?

가이드 원칙

  • Changelogs는 사람을 위한 것입니다. 기계를 위한 것이 아닙니다.
  • 모든 단일 버전에 대한 항목이 있어야 합니다.
  • 같은 유형의 변경 사항은 그룹으로 묶어야 합니다.
  • 버전 및 섹션들은 링크를 통해 연결될 수 있어야 합니다.
  • 최신 버전이 처음에 와야 합니다.
  • 각 버전의 릴리즈 날짜를 표시해야 합니다.
  • 프로젝트가 시맨틱 버저닝을 따르는지를 언급해야 합니다.

변경 유형

  • Added 새로운 기능
  • Changed 기존 기능의 변경
  • Deprecated 곧 없어질 기능
  • Removed 없어진 기능
  • Fixed 버그 수정
  • Security 보안 취약점에 관하여

Changelog를 관리하기 위해 필요한 노력을 어떻게 줄일 수 있나요?

Unreleased 섹션을 가장 위에 두어 다가올 변경 사항들을 추적할 수 있도록 하세요.

이것은 두 가지 목적이 있습니다.

  • 사람들이 향후 릴리즈에서 예상되는 변경 사항들을 확인할 수 있습니다.
  • 릴리즈 시점에 Unreleased 섹션의 변경 사항들을 새 릴리즈 버전의 섹션으로 이동할 수 있습니다.

Changelogs가 나빠질 수 있나요?

네. 여기에 changelog가 쓸모없게 되는 몇 가지 경우들이 있습니다.

커밋 로그 차이(Commit log diffs)

커밋 로그의 차이를 changelog로 사용하는 것은 안 좋은 생각입니다. 커밋 로그는 머지 커밋, 모호한 타이틀을 가진 커밋, 문서 변경 등 노이즈로 가득 차 있습니다.

커밋의 목적은 소스 코드 진화의 단계를 기록하기 위함입니다. 어떤 프로젝트는 커밋을 정리하지만, 어떤 프로젝트는 하지 않습니다.

changelog 기재의 목적은 흔히 다수의 커밋에 걸친 주목할만한 차이를 최종 사용자에게 명확하게 전달하기 위해 문서화하는 것입니다.

없어질 기능들(Deprecations) 무시하기

사람들이 다른 버전으로 업데이트 할 때, 언제 어떤 것이 중단될지(break) 극도로 분명해야 합니다. 앞으로 없어질 기능들(deprecations)이 나열된 버전으로 업데이트하고, 더 이상 사용하지 않는 기능(deprecated)을 제거한 뒤, 그 기능들이 정말 삭제된 버전으로 업데이트 하는 것이 가능해야 합니다.

최소한, 앞으로 없어질 기능들, 제거된 것 그리고 모든 급격한 변화(breaking changes)는 changelog에 남기십시오.

혼란스러운 날짜

지역별 날짜 포맷은 전세계에 걸쳐 다양하며 모든 사람이 직관적으로 느낄 수 있는 인간 친화적 날짜 포맷을 찾기 힘든 경우가 많습니다. 2017-07-17 같은 날짜 포맷(연, 월, 일)의 장점은 큰 단위부터 작은 단위의 순서를 따른다는 것입니다. 월과 일의 위치가 뒤바뀐 어떤 포맷과 다르게, 이 포맷은 다른 날짜 포맷과 모호하게 겹치는 부분이 없습니다. 이런 이유와 이 포맷이 ISO standard라는 사실이 changelog 기재에 이 날짜 포맷을 추천하는 이유입니다.

일관성 없는 변경 사항

일부 변경 사항만 언급하는 changelog는 changelog가 없는 것만큼 위험할 수 있습니다. 물론 기록하지 않아도 되는 변경 사항도 많이 있습니다. 예를 들어, 단순히 공백 하나를 삭제한 것은 어떤 경우에도 기록할 필요가 없을 수도 있습니다. 하지만 중요한 변경 사항은 changelog에 명시되어야 합니다. 일관성 없이 변경 사항을 적용하면 사용자들이 changelog가 단일 진실 공급원(Single source of truth)이라고 착각할 수 있습니다. 큰 권한에는 큰 책임이 따릅니다. 좋은 변경 로그는 일관성 있게 업데이트되는 변경 로그를 의미합니다.

자주 하는 질문

Changelog의 표준 포맷이 있나요?

없습니다. GNU changelog 스타일 가이드 또는 두 문단 정도의 GNU NEWS file "가이드라인"이 있습니다. 하지만 둘 다 부적절하거나 불충분합니다.

이 프로젝트의 목표는 더 나은 changelog 규칙 입니다. 이것은 오픈소스 커뮤니티에서 좋은 사례를 관찰하고 모으는 데서 비롯됩니다.

건강한 비판, 토론 및 개선 제안은 환영합니다.

Changelog 파일의 이름을 무엇으로 지어야 하나요?

CHANGELOG.md라고 만드세요. 어떤 프로젝트는 HISTORY, NEWS 또는 RELEASES를 사용합니다.

changelog 파일의 이름이 무슨 상관이냐고 생각하기 쉽겠지만, 최종 사용자가 주목할 만한 변경 사항을 일관적으로 찾기 쉬워집니다.

깃허브 릴리즈는 어떻게 하나요?

이것은 훌륭한 계획입니다. 릴리즈는 직접 릴리즈 노트를 추가하여 간단한 깃 태그(예를 들어 v1.0.0 태그)를 풍부한 릴리즈 노트로 전환하거나, 주석이 달린 깃 태그 메시지를 가져와서 릴리즈 노트로 전환할 수 있습니다.

깃허브 릴리즈는 이식 불가능한 changelog를 생성하며, 이는 깃허브 내에서만 사용자들에게 보여집니다. Keep a Changelog 포맷처럼 보이게 만드는 게 가능하지만, 좀 더 복잡해지는 경향이 있습니다.

일반적인 대문자 파일들(README, CONTRIBUTING 등)과 달리, 깃허브 릴리즈의 현재 버전은 최종 사용자가 쉽게 찾아볼 수 없습니다. 또 다른 사소한 이슈는 깃허브 릴리즈의 인터페이스가 현재 각 릴리스 간의 커밋 로그 링크를 제공하지 않는다는 것입니다.

Changelog를 자동으로 파싱할 수 있나요?

사람들이 매우 다양한 포맷과 파일 이름을 따르기 때문에 어렵습니다.

Vandamme은 Gemnasium 팀에 의해 생성된 Ruby gem이고 전부는 아니지만 많은 오픈소스 프로젝트의 changelog를 파싱합니다.

삭제된 릴리즈(Yanked release)는 어떻게 하나요?

삭제된(Yanked) 릴리즈는 심각한 버그나 보안 이슈 때문에 소스에서 들어내 버린 버전을 말합니다. 이런 버전은 changelog에 나타내지 않는 경우가 않지만, 나타내야 합니다. 이것이 삭제된 릴리즈를 표시하는 방법입니다.

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

사람들이 알아차리는 것이 중요하기 때문에 눈에 띄는 [YANKED] 태그가 있습니다. 대괄호 안에 있기 때문에 프로그래밍적으로 파싱하기에도 용이합니다.

Changelog를 다시 작성한 적이 있나요?

물론입니다. changelog를 개선할 좋은 이유는 항상 있습니다. 저는 정기적으로 changelog가 관리되지 않은 오픈소스에 pull request를 열어서 누락된 릴리즈를 추가합니다.

또한, 어떤 버전의 급격한 변화에 대한 언급을 잊은 걸 발견할 수도 있습니다. 이 경우엔 changelog를 업데이트하는 것이 당연히 중요합니다.

어떻게 기여할 수 있나요?

이 문서가 진리는 아닙니다. 이것은 제가 모은 정보와 예제들과 함께 신중하게 고려한 의견입니다.

이는 우리 커뮤니티가 합의점에 도달하기를 원하기 때문입니다. 저는 최종결과 못지않게 토론도 중요하다고 생각합니다.

그러니 많은 참여 부탁드립니다.

담화

왜 관리자와 기여자가 changelog를 신경써야하는지, 또한 이 프로젝트의 동기에 대해 이야기하기 위해 The Changelog 팟캐스트에 다녀왔습니다.