チェンジロギングガイドライン

1. 目的

このガイドラインは、ドキュメントのチェンジロギングとバージョニングのルールを定義します。目的は、ユーザーとプログラマーがドキュメントの歴史を理解しやすくすることです。

2. 急速な決定のルール

以下の質問を使用して、変更を決定します。

ユーザーまたはプログラマーの機能が変更されたか?
既存のビジネスルールまたは動作が変更されたか?
フロントエンド、バックエンド、データベース、または SaaS アプリケーションが変更されたか?
既存のドキュメントのバージョンを読まないと、ユーザーが誤った決定を下す可能性があるか?

少なくとも 1 つの質問に「はい」と回答すると、変更を次のドキュメントのリリースに追加し、チェンジロギングに記載する必要があります。

何が変更されたのかを簡単に説明できるか?
  → それほど重要ではないので、Git コミットだけに留める。

データ、画面、API、ビジネスルール、または統合が変更されたか?
  → ドキュメントの新しいバージョンを作成する。

古い統合が機能しなくなり、変更が必要になったか?
  → バイキング チェンジ; メジャー バージョンを上げる。

3. 変更の分類

種類	例	チェンジロギング / バージョン?
編集	タイポ、文法、表のフォーマット	なし; Git コミットだけに留める。
ドキュメントの欠落	機能が実行されているが、ドキュメントが存在しない	通常はなし; 重要な更新の場合にのみ注釈を追加する。
新機能	Xendit、新製品、インボイスダウンロード、新しい通知	はい、カテゴリ `Added`。
動作の変更	7 日間のグレースパリオドが 14 日間のグレースパリオドに変更された	はい、カテゴリ `Changed`。
バグの修正	Webhook のリトライが以前はメールを複数回送信した	はい、カテゴリ `Fixed`。
技術的変更	Redis/BullMQ、メールプロバイダー、モニタリング	はい、カテゴリ `Technical` である場合、オペレーション / メンテナンスに影響がある。
廃止	エンドポイントはまだ機能しているが、将来は停止される	はい、カテゴリ `Deprecated`。
削除	エンドポイントまたは機能が利用できなくなった	はい、カテゴリ `Removed`。
バイキングチェンジ	JWT のクレームが削除された、API の URL が変更された、ライセンス ID のフォーマットが変更された	はい、メジャーバージョンを上げる。

4. バージョニングのルール

ドキュメントのバージョニングは vMAJOR.MINOR の形式を使用します。

変更	例	バージョン
基準値の初期化	最初の承認されたドキュメントのスナップショット	`v1.0`
相互運用性のある機能/ルール/変更	エンドポイントまたはペイメントゲートウェイを追加する	`v1.0 → v1.1`
次の相互運用性のある変更	ドキュメントのキューまたは管理フローの追加	`v1.1 → v1.2`
バイキングチェンジ	エンドポイント/ペイロードが互換性がない	`v1.x → v2.0`

小さな変更は 1 つのドキュメントリリースに集められることがよくあります。タイプまたはマークダウンフォーマットの変更だけではバージョンを上げる必要はありません。

5. チェンジロギングのフォーマット

以下のカテゴリを使用する場合は、内容がある場合にのみ使用する。

## v1.1 — YYYY-MM-DD

### Added
- 新しい機能または機能。

### Changed
- 動作、ビジネス ルール、UI、API、またはアーキテクチャが変更された。

### Fixed
- 修正されたバグまたは不一致。

### Deprecated
- まだ利用可能ですが、将来は停止される部分。

### Removed
- すでに利用できなくなった部分。

### Technical
- オペレーションとメンテナンスのために内部の変更。

重要な各アイテムは、影響を説明するようにすることが望ましい。

### Added
- Xendit をペイメント ゲートウェイとして統合しました。
  - ユーザーへの影響: 追加の支払いオプションが利用可能になりました。
  - プログラマーへの影響: Xendit の Webhook と新しい環境変数の実装が必要になりました。

6. 歴史の保存

アーティファクト	機能
Git コミット	ファイルまたは行ごとの最も詳細な技術的歴史。
`11-changelog/changelog.md`	チェンジロギングのすべてのリリースの概要。
`11-changelog/changelog-guidelines.md`	このバージョニングガイドラインの決定のルール。
`versions/vX.Y/`	ドキュメントのすべてのスナップショットが保存されているウェブサイトのドキュメントのバージョニング用に使用される。
Git タグ `docs-vX.Y`	ドキュメントのバージョニングの公式のスナップショットのソース。

7. ドキュメントリリースのチェックリスト

変更のカテゴリと新しいバージョンを決定する。
全ての影響を受けるドキュメントを更新する。
changelog.md に人間が読めるサマリーを追加する。
バージョニングされたドキュメントポータルの場合、versions/vX.Y/ のスナップショットを作成する。
変更がレビューされ承認された後、Git タグ docs-vX.Y を作成する。

チェンジロギング ガイドライン