変更履歴を記録する
友達にGitログを変更履歴に移させないでください。
# 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
変更履歴とは何ですか？
変更履歴とは、プロジェクトの各バージョンに対する注目に値する変更点の時系列順に並べられたリストを含むファイルです。
なぜ変更履歴を記録するのですか？
プロジェクトの各リリース（またはバージョン）の間で、どのような注目すべき変更が行われたのかをユーザーおよびコントリビューターが正確に把握しやすくするためです。
誰が変更履歴を必要としますか？
人々です。消費者であろうと開発者であろうと、ソフトウェアのエンドユーザーはソフトウェアの内容を気にする人間です。ソフトウェアに変更があるとき、人々は変更の理由や方法を知りたいのです。
良い変更履歴を作るには？
基本理念
- 変更履歴は機械のためではなく人間のためにあります。
- バージョンごとに作成する必要があります。
- 同じ種類の変更をグループ化する必要があります。
- バージョンとセクションはリンク可能である必要があります。
- 最新バージョンは先頭にきます。
- 各バージョンのリリース日を表示されます。
- Semantic Versioning に従っているかどうか言及してください。
変更の種類
-
Added新機能について。 -
Changed既存機能の変更について。 -
Deprecated間もなく削除される機能について。 -
Removed今回で削除された機能について。 -
Fixedバグ修正について。 -
Security脆弱性に関する場合。
変更履歴のメンテナンスに必要な労力を減らすにはどうすればよいですか？
今後の変更を追跡するには Unreleased セクションを上部に配置します。
これには2つの目的があります。
- 人々は、今後のリリースでどのような変更が予想されるのかを確認することができます。
- リリース時には、
Unreleasedセクションにある変更を 新しいリリースバージョンのセクションに移動することができます。
変更履歴は悪くなる可能性がありますか？
はい。いくつかの方法があります。
コミットログの差分
変更履歴としてコミットログの差分を使用することはよくない考えです。それはノイズに満ちています。 マージコミット、あいまいな表題のコミット、ドキュメントの変更などがあります。
コミットの目的はソースコードの進化における一歩を文書化することです。 コミットをクリーンアップするプロジェクトもあれば、そうでないプロジェクトもあります。
変更履歴エントリの目的は、しばしば複数のコミットにまたがって注目すべき違いを文書化し、 それらをエンドユーザーに明確に伝えることです。
非推奨の無視
人々があるバージョンから別のバージョンにアップグレードするとき、いつ何かが壊れるのは痛いほど明らかです。 廃止予定をリストアップしたバージョンにアップグレードし、廃止予定のものを削除してから、 廃止予定が削除されるバージョンにアップグレードすることが可能です。
あなたが他に何もしないのであれば、変更履歴に非推奨、削除、破壊的変更を列挙してください。
分かりにくい日付
地域の日付形式は世界中で異なり、誰にとっても直感的でヒューマンフレンドリーな日付形式を見つけるのは困難です。 2017-07-17 のように形式化された日付の利点は、年、月、日のように最大から最小の単位の順序に従うということです。 この形式は、月と日の位置を切り替える地域の形式とは異なり、他の日付形式とあいまいに重なり合うこともありません。 これらの理由、およびこの日付形式が ISO standard であるという事実が、それが変更履歴エントリに推奨される日付形式である理由です。
よくある質問と回答
変更履歴の標準的な書式がありますか？
実はありません。 GNU changelog style guide 、 もしくは two-paragraph-long GNU NEWS file "guideline" があります。 どちらも不十分であり不適切です。
このプロジェクトは より良い変更履歴の規約 になることを目指しています。 それはオープンソースコミュニティの良い習慣を観察し、それらを集めることから来ます。
健全な批判、議論、そして改善のための提案を 歓迎しています。
変更履歴ファイルにはどのような名前をつけるべきですか？
CHANGELOG.md と呼びます。いくつかのプロジェクトでは HISTORY や NEWS 、 RELEASES が使われています。
あなたの変更履歴ファイルの名前はそれほど重要でないと考えることは容易ですが、 なぜエンドユーザーが一貫して注目の変更を見つけることを難しくするのですか？
GitHubリリースはどうですか？
素晴らしい主導権です。 Releases は手動でリリースノートを追加することによって、 単純なGitタグ(例えば v1.0.0 という名前のタグ)をリッチなリリースノートに変換するために使用することができます。
Githubリリースは、Githubのコンテキスト内でのみユーザーに表示できる移植性のない変更履歴を作成します。 それらをKeep a Changelogの書式のように見せることは可能ですが、もう少し複雑になる傾向があります。
Githubリリースの現在のバージョンも、典型的な大文字のファイル(README や CONTRIBUTINGなど) とは異なり、おそらくエンドユーザーにはあまり発見できません。 もう一つの目立たない問題は、インターフェースが現在各リリース間のコミット履歴へのリンクを提供していないということです。
変更履歴を自動的に解析できますか？
人々は大きく異なるフォーマットやファイル名に従うので、難しいです。
Vandamme はGemnasiumチームによって作成されたRuby gemであり、 （全てではないが）多くのオープンソースプロジェクトの変更履歴を解析します。
ヤンクリリースについてはどうですか？
ヤンクリリースは、深刻なバグやセキュリティの問題のために 引っ張られなければならなかったバージョンです。 多くの場合、これらのバージョンは変更履歴に表示されません。表示しないべきである。 次のように表示すべきである。
## [0.0.5] - 2014-12-13 [YANKED]
[YANKED] は大きな理由です。それに気付くことは人々にとって重要です。 大括弧で囲まれているので、プログラムで解析するのも簡単です。
変更履歴を書き換える必要がありますか？
もちろんです。変更履歴を改善するためには、常にもっともな理由があります。 メンテナンスされていない変更履歴のあるオープンソースプロジェクトに 不足しているリリースを追加するためのプルリクエストが常に開かれています。
バージョンのノートにある破壊的変更への対応を忘れたことを発見するかもしれません。 この場合、変更履歴を更新することは明らかに重要です。
どうやって貢献できますか？
この文書は 真実 ではありません。 私が集めた情報と例と共に、慎重に考えられた私の意見です。
私たちのコミュニティが合意に達することを望んでいるからです。 私は議論が最終結果と同じくらい重要であると思います。
なので 協力 してください。
座談
私は The Changelog podcast で、メンテナーやコントリビューターがなぜ変更履歴を気にすべきなのか、 そしてこのプロジェクトの背後にある動機について話しました。