コンテンツにスキップ

04. リリースノートの作成

このドキュメントは、エンドユーザー向けに、製品のアップデート内容を伝える「リリースノート」の作成プロセスとガイドラインを定めます。

1. リリースノートの目的と対象読者

  • 目的:
    • 今回のバージョンアップで「ユーザーの体験がどのように良くなるか」という価値を、分かりやすく伝えることを最優先とします。
    • 新機能の認知度を高め、ユーザーに利用を促します。
  • 対象読者:
    • エンドユーザー、顧客、プロダクトマネージャーなど、必ずしも技術的な背景を持たない人々。
  • 公開場所:
    • GitHub Releases, 公式ブログ, 製品内の「新着情報」画面など、ユーザーの目に触れやすい場所。

CHANGELOGとの違い

リリースノートは、開発者向けの技術的な03_変更履歴とは、目的と対象読者が明確に異なります。CHANGELOGが「事実の網羅的な記録」であるのに対し、リリースノートは「価値の選択的な伝達」です。

2. リリースノート作成の半自動化プロセス

リリースノートの作成は、手作業による手間を最小限にしつつ、品質を確保するため、以下の半自動化プロセスで行います。

2.1 自動生成の流れ

  1. トリガー:
    • vX.Y.Z形式のGitタグがリモートリポジトリにプッシュされると、CI/CDパイプライン（GitHub Actionsなど）が起動します。
  2. ドラフトの自動作成:
    • CI/CDは、03_変更履歴の管理.mdのプロセスで更新されたCHANGELOG.mdを読み込みます。
    • 最新バージョンのセクション（### Features, ### Bug Fixesなど）の内容を抽出し、GitHub Releasesに新しいリリースのドラフト（下書き）を作成します。このとき、本文には抽出したCHANGELOGの内容が貼り付けられます。
  3. 手動での編集と公開:
    • リリース担当者は、自動生成されたリリースのドラフトを開き、以下のガイドラインに従って内容を編集・洗練させます。
    • 全ての編集が完了したら、「公開」ボタンを押し、正式なリリースノートとして公開します。

3. 良いリリースノートを書くためのガイドライン

自動生成された下書きは、あくまで「素材」です。以下の点を意識して、ユーザーにとって価値のある情報へと昇華させてください。

  • 魅力的なタイトルと概要:
    • バージョンの羅列だけでなく、「〇〇機能が追加されました！」のように、最も伝えたいことをタイトルや冒頭の要約に含めます。
  • ユーザー中心の言葉を使う:
    • 技術的なコミットメッセージを、ユーザーの利益を説明する言葉に「翻訳」します。
    • 悪い例: feat(auth): add multi-factor authentication
    • 良い例: 🚀 新機能: お客様のアカウントをさらに安全にする、多要素認証（MFA）に対応しました！
  • カテゴリ分け:
    • 「新機能」「改善」「バグ修正」のように、変更点を分かりやすく分類します。絵文字を使うと、視覚的に楽しくなります。
  • 視覚的な補助を活用する:
    • UIに関する変更点には、スクリーンショットやGIF動画を積極的に添付します。百聞は一見に如かずです。
  • 専門用語を避ける:
    • どうしても技術用語を使う必要がある場合は、簡単な説明を加えます。
  • 感謝を伝える:
    • バグを報告してくれたユーザーや、コントリビューターへの感謝を記載すると、コミュニティとの良好な関係を築けます。

リリースノートの編集例

自動生成されたドラフト (CHANGELOGより):

### Features

- feat(settings): add notification settings functionality
- feat(ui): implement dark mode toggle

### Bug Fixes

- fix(api): correct validation for article posting

人間が編集した最終的なリリースノート:

## ✨ バージョン 1.1.0 がリリースされました！ ✨

今回のアップデートでは、待望のダークモードと、より柔軟な通知設定機能を追加しました！

### 🚀 新機能 (New Features)

- **ダークモードに対応しました！** 目の疲れを軽減し、集中力を高めるダークモードを、ナビゲーションメニューからいつでも切り替えられます。
  ![ダークモードのスクリーンショット](images/dark-mode.png)
- **通知設定がより細かくできるようになりました。** アカウント設定画面から、メール通知の種類ごとにオン・オフを切り替えられます。

### 🐛 改善とバグ修正 (Improvements & Bug Fixes)

- 特定の状況で記事を投稿した際に、エラーが発生する問題を修正しました。