Keep a Changelog
동료가 git 로그를 changelogs에 덤프하게 내버려 두지 마세요.
# 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
Changelog는 무엇인가요?
Changelog는 프로젝트의 각 버전에 대해 선별된 눈에 띄는 변경사항을 시간 순서대로 정리해둔 파일입니다.
왜 changelog를 유지해야 하나요?
사용자와 기여자가 프로젝트의 각 릴리즈(또는 버전)간에 정확히 어떤 주목할만한 변경사항이 있는지 보기 쉽도록 합니다.
누가 changelog를 필요로 하나요?
사람들이 필요로 합니다. 개발자이든 사용자이든, 소프트웨어의 최종 사용자는 소프트웨어에 무엇이 있는지 관심이 있는 사람입니다. 소프트웨어가 변할 때, 사람들은 왜 그리고 어떻게 바뀌었는지 알고 싶어합니다.
어떻게 좋은 changelog를 만들수 있나요?
가이드 원칙
- Changelogs는 사람을 위한 것입니다. 기계를 위한 것이 아닙니다.
- 모든 단일 버전에 대한 항목이 있어야 합니다.
- 같은 유형의 변경사항은 모아야 합니다.
- 버전과 섹션은 연결할 수 있어야 합니다.
- 최신 버전이 처음에 나옵니다.
- 각 버전의 릴리즈 날짜를 표시해야 합니다.
- 시멘틱 버저닝를 따르는지 언급해 주세요.
변경 유형
-
Added새로운 기능 -
Changed기존 기능의 변경사항 -
Deprecated곧 지워질 기능 -
Removed지금 지워진 기능 -
Fixed버그 픽스 -
Security취약점이 있는 경우
changelog를 관리하는 노력을 어떻게 줄일 수 있나요?
Unreleased 섹션을 가장 위에 두어 다가올 변경사항을 추적할 수 있도록 하세요.
이것은 두 가지 용도로 사용됩니다:
- 사람들이 다음 릴리즈에서 기대하는 변경사항을 확인할 수 있습니다.
- 릴리즈 시점에
Unreleased섹션의 변경사항을 새 릴리즈 섹션으로 이동할 수 있습니다.
changelogs가 안좋게 될 수 있습니까?
네. 여기에 changelog가 쓸모없게 되는 몇가지 경우들이 있습니다.
커밋 로그 차이(Commit log diffs)
커밋 로그 차이를 changelog로 사용하는 것은 안좋은 생각입니다: 머지 커밋, 모호한 타이틀을 가진 커밋, 문서 변경 등 노이즈로 가득차 있습니다.
커밋의 목적은 소스 코드 진화의 단계를 기록하기 위함입니다. 어떤 프로젝트는 커밋을 정리하지만, 어떤 프로젝트는 하지 않습니다.
changelog 기입의 목적은 종종 다수의 커밋 중에서 주목할만한 차이를 최종 사용자에게 명확하게 전달하기 위해 문서화하는 것입니다.
없어질 기능들(Deprecations) 무시하기
사람들이 다른 버전으로 업그레이드 할 때, 언제 어떤 것이 손상될수있는지(breakable) 고통스럽게 분명해야 합니다. 앞으로 사라질 기능들(deprecations)이 나열된 버전으로 업그레이드하고, 더 이상 사용하지 않는 것(deprecated)을 제거한 뒤, 그 사라질 기능들이 정말 없어진 버전으로 업데이트 하는 것이 가능해야 합니다.
아무 작업도 수행하지 않는다면, 없어질 기능들, 제거된 것, 모든 급격한 변화를 changelog에 남기십시오.
날짜를 혼동하는 것
지역 날짜 포맷은 전세계에 걸쳐 다르고 종종 모두에게 직관적인 인간 친화적 날짜 포맷을 찾기 힘듭니다. 2017-07-17 같은 날짜 포맷(연, 월, 일)의 장점은 큰 단위부터 작은 단위의 순서를 따른다는 것입니다. 월과 일의 위치가 뒤바뀐 어떤 포맷과 다르게, 이 포맷은 다른 날짜 포맷과 모호하게 겹치는 부분이 없습니다. 이런 이유와 이 포맷이 ISO standard라는 사실이 changelog 기입을 위해 이 날짜 포맷을 추천하는 이유입니다.
자주 하는 질문
changelog의 표준 포맷이 있나요?
없습니다. GNU changelog 스타일 가이드나 두 문단정도의 GNU NEWS '가이드라인'이 있습니다. 하지만 둘다 부적절하거나 충분하지 않습니다.
이 프로젝트의 목표는 더 나은 changelog 규칙 입니다. 이것은 오픈소스 커뮤니티에서 좋은 용례를 관찰하고 모으는데서 나옵니다.
건강한 비판, 토론 및 개선 제안은 환영합니다.
changelog 파일의 이름을 무엇으로 지어야 하나요?
CHANGELOG.md라고 만드세요. 어떤 프로젝트는 HISTORY, NEWS 또는 RELEASES를 사용합니다.
changelog 파일의 이름이 무슨 상관이냐고 생각하기 쉽겠지만, 왜 굳이 여러분의 사용자가 변경사항을 일관적으로 찾기 힘들도록 만드나요?
깃허브 릴리즈는 어떻게 하나요?
이것은 훌륭한 이니셔티브입니다. 릴리즈는 직접 릴리즈 노트를 추가하거나 어노테이션된 깃 태그 메시지를 가져와서 노트로 바꿔 간단한 깃 태그(예를 들어 v1.0.0 태그 )를 풍부한 릴리즈 노트로 전환시키는데 사용될 수 있습니다.
깃허브 릴리즈는 이동 불가능한 깃허브 컨텍스트 내에서만 표시되는 changelog를 생성합니다. Keep a Changelog 포맷처럼 보이게 만드는 게 가능하지만, 좀 더 복잡해지는 경향이 있습니다.
전형적인 대문자 파일들과 달리(README, CONTRIBUTING, 등), 깃허브 릴리즈의 현재 버전은 최종 사용자가 거의 찾아볼 수 없습니다. 다른 사소한 이슈는 인터페이스가 현재 각 릴리즈 사이에 로그를 커밋할 수 있는 링크를 제공하지 않는 것입니다.
Changelog를 자동으로 파싱할 수 있나요?
사람들이 대단히 다양한 포맷과 파일 이름을 따르기 때문에 어렵습니다.
Vandamme은 Gemnasium 팀에 의해 생성된 루비잼이고 많은(전부는 아니고) 오픈소스 프로젝트의 changelog를 파싱합니다.
삭제된 릴리즈(Yanked release)는 어떻게 하나요?
삭제된(Yanked) 릴리즈는 심각한 버그나 보안 이슈 때문에 소스에서 들어내버린 버전을 말합니다. 대게 이런 버전은 changelog에 아예 나오지도 않지만, 나와야 합니다. 이것이 삭제된 릴리즈를 표시하는 방법입니다:
## [0.0.5] - 2014-12-13 [YANKED]
[YANKED] 태그가 요란한 이유가 있습니다. 사람들이 알아차리는 것이 중요합니다. 대괄호 안에 있기 때문에 프로그래밍적으로 파싱하기에도 용이합니다.
changelog를 다시 써야하나요?
물론입니다. changelog를 개선할 좋은 이유는 항상 있습니다. 저는 정기적으로 changelog가 관리되지 않는 오픈소스에 빠진 릴리즈를 추가하기 위해 pull request를 오픈합니다.
어떤 버전의 급격한 변화에 대해 언급하는 것을 잊은 것을 발견할 수도 있습니다. 이 경우엔 changelog를 업데이트하는 것이 당연히 중요합니다.
어떻게 기여할 수 있나요?
이 문서가 진리는 아닙니다. 이것은 제가 모은 정보와 예제들과 함께 신중하게 고려한 의견입니다.
왜냐하면 우리 커뮤니티가 공감대를 형성하기를 원하기 때문입니다. 저는 최종결과 못지않게 토론도 중요하다고 생각합니다.
그러니 참여를 부탁합니다.
대화
왜 관리자와 기여자가 changelog를 신경써야하는지, 또한 이 프로젝트를 하게된 동기에 대해 이야기하기 위해 The Changelog 팟캐스트에 다녀왔습니다.