変更履歴を記録する

友達がGit記録を変更履歴に丸写しするのを止めさせよう。

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

変更履歴とは何ですか？

変更履歴とは、事業の各版に対する注目に値する変更点を 時系列順に並べた一覧を含むファイルです。

なぜ変更履歴を記録するのですか？

事業の各リリース（または各版）の間で、 どのような注目すべき変更が行われたのかを利用者および貢献者が正確に把握しやすくするためです。

誰が変更履歴を必要としますか？

全員が必要とします。 消費者であろうと開発者であろうと、ソフトウェアの末端利用者はソフトウェアの内容を気にします。 ソフトウェアに変更があるとき、人々は変更の理由や方法を知りたいのです。

良い変更履歴を作るには？

基本理念

  • 変更履歴は機械のためではなく人間のためにあります。
  • 版ごとに作成する必要があります。
  • 同じ種類の変更をまとめる必要があります。
  • 版と節はリンク可能である必要があります。
  • 最新版は先頭にきます。
  • 各版のリリース日を表示されます。
  • Semantic Versioning に従っているかどうか言及してください。

変更の種類

  • Added 新機能について。
  • Changed 既存機能の変更について。
  • Deprecated 間もなく削除される機能について。
  • Removed 今回で削除された機能について。
  • Fixed 不具合修正について。
  • Security 脆弱性に関する場合。

変更履歴の維持管理に必要な労力を減らすにはどうすればよいですか？

今後の変更を追跡するには Unreleased 節を上部に配置します。

これには2つの目的があります。

  • 人々は、今後のリリースでどのような変更が予想されるのかを確認することができます。
  • リリース時には、 Unreleased 節にある変更を 新しいリリース版の節に移動することができます。

変更履歴が害悪になる可能性はありますか？

はい、ありえます。

変更履歴を役立たずにしてしまう幾つかの行為をここに述べます。

コミット記録の差分

変更履歴としてコミット記録の差分を使用することはよくない考えです。それは雑音に満ちています。 コミット、あいまいな表題のコミット、文書の変更などがあります。

コミットの目的はソースコードの進化における一歩を文書化することです。 合併コミットを一掃する事業もあれば、そうでない事業もあります。

変更履歴項目の目的は、しばしば複数のコミットにまたがって注目すべき違いを文書化し、 それらを末端利用者に明確に伝えることです。

非推奨の無視

人々がある版から別の版に増強するとき、いつ何かが壊れるのは痛いほど明らかです。 廃止予定を洗い出した版に増強し、廃止予定のものを削除してから、 廃止予定が削除される版に増強することが可能です。

あなたが他に何もしないのであれば、変更履歴に非推奨、削除、破壊的変更を列挙してください。

分かりにくい日付

地域の日付形式は世界中で異なり、 誰にとっても直感的で親しみやすい日付形式を見つけるのは困難です。 2017-07-17 のように形式化された日付の利点は、 年、月、日のように最大から最小の単位の順序に従うということです。 この形式は、月と日の位置を切り替える地域の形式とは異なり、 他の日付形式とあいまいに重なり合うこともありません。 これらの理由、およびこの日付形式が 国際標準 であるという事実が、 それが変更履歴項目に推奨される日付形式である理由です。

一貫性のない変更

変更履歴に全ての変更点を記載しないことは、変更履歴がないのと同じくらい危険です。 たしかに記載しないでもよい変更は多くあります—— 例えば、空白を1つ削除したことはどんな場合でも記録する必要はないかもしれません—— が、重要な変更は全実例において記載すべきです。 変更を一貫して適用しないせいで、変更履歴こそ真実が記された唯一の情報源である という勘違いが生じる可能性があります。 そして可能性は現実になりえます。 大いなる力には大いなる責任が伴います—— 良い変更履歴を作るというのは更新が一貫した変更履歴を作るということを意味します。

よくある質問と回答

変更履歴の標準的な書式がありますか？

実はありません。 GNU changelog style guide 、もしくは two-paragraph-long GNU NEWS file という 「指針」があります。 しかしどちらも不十分であり不適切です。

この事業は より良い変更履歴の規約 になることを目指しています。 それはオープンソース団体の良い習慣を観察し、それらを集めることから来ます。

健全な批判、議論、そして改善のための提案を 歓迎しています。

変更履歴ファイルにはどのような名前をつけるべきですか？

CHANGELOG.md という名前にしましょう。 いくつかの事業では HISTORY や NEWS 、 RELEASES という名前が使われています。

あなたの変更履歴ファイルの名前はそれほど重要でないと考えることは容易ですが、 しかし末端利用者が注目に値する変更を一貫して見つけることを難しくする理由はありません。

GitHubリリースはどうですか？

極めて先駆的です。 Releases に手動でリリース告知を追加することによって、 単純なGitタグ（例えば v1.0.0 という名前の標識）を素敵なリリース告知に変換するために使用できます。

GitHub Releasesは、GitHubの文脈内でのみ利用者に表示できる移植性のない変更履歴を作成します。 それらをKeep a Changelogの書式のように見せることは可能ですが、もう少し複雑になる傾向があります。

GitHub Releasesの現在の版も、典型的な大文字のファイル （README や CONTRIBUTINGなど） とは異なり、おそらく末端利用者が見付けるのは簡単ではないでしょう。 もう一つ目立たない問題として、現在、各リリース間のコミット履歴への リンクが提供されていないということがあります。

変更履歴を自動的に解析できますか？

人々によって形式やファイル名は大きく異なるため、難しいです。

Vandamme はGemnasiumチームが作成したRuby gemであり、 （全てではありませんが）多くのオープンソース事業の変更履歴を解析できます。

リリース引き戻しについてはどうですか？

リリース引き戻し (yanked releases) とは、深刻な不具合や安全上の問題のために リリースを引き戻さ (yank) なれなければならなかった版です。 これらの変更はしばしば変更履歴に記載さえされませんが，必ず記載すべきです。 次のように表示すればよいでしょう。

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

[YANKED] が仰々しいのには訳があります。 利用者が引き戻しに気付くことが重要だからです。 角括弧で囲まれているので、プログラムで解析するのも簡単です。

変更履歴を書き換える必要がありますか？

もちろんです。変更履歴を改善するためには、常にもっともな理由があります。 維持管理されていない変更履歴のあるオープンソース事業に、 不足している資源を追加するためのプルリクエストが常に開かれています。

版の告知にある破壊的変更への対応を忘れたことを発見するかもしれません。 この場合、変更履歴を更新することは明らかに重要です。

どうやって貢献できますか？

この文書は 真実 ではありません。 私が集めた情報と例と共に、慎重に考えられた私の意見です。

私たち一同が合意に達することを望んでいるからです。 私は議論が最終結果と同じくらい重要であると思います。

なので 協力 してください。

座談

私は The Changelog podcast で、 管理者や貢献者がなぜ変更履歴を気にすべきなのか、 そしてこの事業の背後にある動機について話しました。