角待ちは対空

おもむろガウェイン

CHANGELOG の書き方

Tech

VS Code の拡張作っている際に CHANGELOG.md が自動生成され、書き方はKeep a Changelogに従えと書かれていたので紹介する。

ここに書かれていることは絶対ではなくただ提案しているだけである。意見がある人は話し合おうという温度感っぽいので、納得いかない場合は issue 立てると良いと思う。

僕自身はなんでもよくてある程度型が欲しかっただけなのでこれからはこれに従って書いていこうと思う。ただまぁ Semantic Versioning もそうだけどちゃんと従おうとすると以上にだるくなってくるので雰囲気従うくらいだと思う。

CHANGELOG の原則

  • 機械的に生成するのではなく人間の手で書く
  • 各セクションへのリンクが容易にできる
  • 1つのバージョンごとに1つのサブセクションを作る
  • リリースは新しいものが上に来るようにする
  • 日付のフォーマットは YYYY-MM-DD で書く
  • Semantic Versioning に従うかは明示的に表明する
  • 各バージョンのセクションは次の原則に従うべき
    • 上記のフォーマットの日付を付与する
    • 以下のようにグループ分けして表記する
      • Added 新機能
      • Changed 既存機能の変更
      • Deprecated 将来的に削除される機能
      • Removed 削除された機能
      • Fixed バグフィックス
      • Security 脆弱性修正のためユーザーにアップデートを促す場合

という原則の元作ると以下のようになる。

# Change Log
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/)
and this project adheres to [Semantic Versioning](http://semver.org/).

## [Unreleased]
### Added
- zh-CN and zh-TW translations from @tianshuo.
- de translation from @mpbzh.
- it-IT translation from @roalz.
- sv translation from @magol.
- tr-TR translation from @karalamalar.
- fr translation from @zapashcanon.

### Changed
- Start versioning based on the current English version at 0.3.0 to help
translation authors keep things up-to-date.
- Fix typos in zh-CN translation.
- Fix typos in pt-BR translation.

## [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](http://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/v0.3.0...HEAD
[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

Unreleased

Unreleased セクションを作って一番上に書いておくことを推奨している。これによって

  • ユーザーが将来的な変更を見ることができる
  • 自分が CHANGELOG を更新する際、ただ移動すればいいだけになる
    • それにより CHANGELOG の更新作業が楽になる

ファイル名は何が良いか

CHANGELOG.md が良い。既存のものはバラバラなので統一しようと言う趣旨。

[YANKED]

深刻なバグだったり脆弱性修正のためユーザーにアップグレードを促したい場合は ## 0.0.5 - 2014-12-13 [YANKED] のように [YANKED] をつける。