release-changelog

リリース変更履歴スキル

安定版 Paperclip リリースのユーザー向け変更履歴を作成します。

バージョン管理モデル

Paperclip は**カレンダーバージョニング（calver）**を使用します。

• 安定版リリース：YYYY.MDD.P（例：2026.318.0）
• Canary リリース：YYYY.MDD.P-canary.N（例：2026.318.1-canary.0）
• Git タグ：安定版は vYYYY.MDD.P、Canary は canary/vYYYY.MDD.P-canary.N

メジャー／マイナー／パッチのバージョンアップはありません。安定版のバージョンは、リリース予定日（UTC）と、その日の次の安定版パッチ枠から決まります。

出力：

• releases/vYYYY.MDD.P.md
• Cases が有効な場合、(caseType, key) をキーにアップサートされた release Case。本文には変更履歴の内容を含むドキュメントリビジョンを設定します

重要なルール：

• 2026.318.1-canary.0 などの Canary リリースがあっても、変更履歴ファイル名は releases/v2026.318.1.md のままです
• semver のバージョンアップ種別からバージョンを決めないでください
• Canary の変更履歴ファイルは作成しないでください

チャンネルのプロセス — ソースコミットとファイルの場所

安定版は十分に検証されたベータ版を昇格させるため、変更履歴には master の先端ではなく、ベータ版のソースコミットを記載します。

• リリースのソースは、最新の beta/v<beta-version> タグが指すコミットです（以下では {beta-src}）。次のコマンドで解決します。

  git fetch origin --tags
  npm view paperclipai dist-tags   # the beta dist-tag names the version
  git rev-parse 'beta/v{beta-version}^{commit}'
  

• {beta-src} 以降の master 上のコミットは次のリリースに含まれます。絶対に含めないでください。「今後の予定」セクションの材料であり、変更履歴には含めません。

• 検証期間中、ファイルは release-notes/v{beta-version} ブランチ上の releases/beta/v{beta-version}.md に置きます（master 向けの PR）。ベータ版の公開時にリリースワークフローが生成済みのひな形を含むブランチをプッシュするため、そのブランチで作業し、ひな形をその場で書き換えてください。ブランチが存在しない場合（自動化導入前にベータ版が作成された場合）は、origin/master から作成し、ひな形を用意してください。

  ./scripts/draft-stable-notes.sh {beta-version}
  

• 安定版のディスパッチ前に、PR を master にマージする必要があります。安定版の事前チェックは master からファイルを読み込むため、ファイルがないと失敗します。

• この手順では、自分で releases/vYYYY.MDD.P.md を作成しないでください。安定版のリリース後、ワークフローが正規化 PR を作成し、ベータ版のバージョンを含むファイル名をそのファイル名に変更します。

• 修正リリースの例外（candidate/release-* ブランチからのパッチリリース）：この場合、変更履歴は候補ブランチに直接 releases/vYYYY.MDD.P.md として置き、チェリーピックした修正とともにコミットします。

ステップ 0 — 冪等性の確認

何かを作成する前に、変更履歴がすでに存在するか確認します。

ls releases/beta/v{beta-version}.md 2>/dev/null   # soak-window home
ls releases/vYYYY.MDD.P.md 2>/dev/null            # canonicalized / fix path
git ls-remote origin 'refs/heads/release-notes/v{beta-version}'

生成されたひな形だけが含まれる release-notes/v{beta-version} ブランチは通常の開始状態であり、競合ではありません。その場で書き換えてください。

存在する場合：

1. まず読みます
2. レビュアーに提示します
3. そのまま使うか、再生成するか、特定のセクションを更新するかを確認します
4. 説明なく上書きしてはいけません

ステップ 1 — 安定版の範囲を決定する

最後の安定版タグとベータ版のソースコミットを特定します。

git tag --list 'v*' --sort=-version:refname | head -1
beta_src="$(git rev-parse 'beta/v{beta-version}^{commit}')"
git log v{last}..${beta_src} --oneline --no-merges

変更履歴の範囲は常に v{last}..{beta-src} です。..HEAD や ..origin/master にしてはいけません。

安定版のバージョンは、次のいずれかから決まります。

• メンテナーからの明示的な依頼
• ./scripts/release.sh stable --date YYYY-MM-DD --print-version
• doc/RELEASING.md ですでに合意されているリリース計画

Canary タグやプレリリースのサフィックスから変更履歴のバージョンを決めないでください。API の意図からメジャー／マイナー／パッチのバージョンアップを決めないでください。calver では日付と同日内の安定版枠を使用します。

ステップ 2 — 元データを収集する

次からリリースデータを収集します。

1. 最後の安定版タグ以降の Git コミット
2. .changeset/*.md ファイル
3. 利用可能な場合は gh を使って取得したマージ済み PR

便利なコマンド：

git log v{last}..{beta-src} --oneline --no-merges
git log v{last}..{beta-src} --format="%H %s" --no-merges
ls .changeset/*.md | grep -v README.md
gh pr list --state merged --search "merged:>={last-tag-date}" --json number,title,body,labels

ステップ 3 — 破壊的変更を検出する

次を確認します。

• 破壊的なマイグレーション
• API フィールド／エンドポイントの削除または変更
• 設定キーの名前変更または削除
• BREAKING: または BREAKING CHANGE: を示すコミット

主なコマンド：

git diff --name-only v{last}..{beta-src} -- packages/db/src/migrations/
git diff v{last}..{beta-src} -- packages/db/src/schema/
git diff v{last}..{beta-src} -- server/src/routes/ server/src/api/
git log v{last}..{beta-src} --format="%s" | rg -n 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true

破壊的変更が検出された場合は、目立つように明記してください。アップグレード手順とともに、「破壊的変更」セクションに必ず記載する必要があります。

ステップ 4 — ユーザー向けに分類する

次の変更履歴セクションを継続して使用します。

• Breaking Changes
• Highlights
• Improvements
• Fixes
• 必要に応じて Upgrade Guide

ユーザーに実質的な影響がない限り、純粋に内部的なリファクタリング、CI の変更、ドキュメントのみの変更は除外します。

ガイドライン：

• 関連するコミットをまとめて、ユーザー向けの 1 つの項目にします
• ユーザーの視点で記述します
• ハイライトは短く、具体的にまとめます
• 破壊的変更については、アップグレード時に必要な対応を明記します
• 最初の草稿から、安定版として十分な深さで記述します。ベータ版向けに作成した草稿は、そのまま安定版の変更履歴として公開されます。そのため、草稿を書き始めた時点で、直前の安定版のファイルが記述密度の基準になります。準備期間中も、生成された骨組み程度の密度のままにしないでください。骨組みに含まれる入れ子の PR 概要は書き直すための素材であり、その形式を維持するものではありません。
• 繰り返しではなく、差分を記述します。記述を始める前に、直前の安定版の変更履歴（releases/v<last-stable>.md）を確認します。前のリリースですでに機能が紹介されている場合、今回のリリースでは変更点のみを記載します。たとえば、デフォルトの切り替え、堅牢性の強化、機能の完成などです。「前回のリリースでは X を導入し、今回はそれをデフォルトにします」のように、前のリリースを踏まえて記述し、あたかも今回初めて登場した機能であるかのように説明しないでください。前のリリースで大きく取り上げたテーマについて、後続の作業のために再び大きく取り上げることは避け、Improvements に分類します。

PR とコントリビューターのインライン表記

箇条書きの項目がマージ済みのプルリクエストに明確に対応する場合、項目の末尾に次の形式で帰属情報をインラインで追加します。

- **Feature name** — Description. ([#123](https://github.com/paperclipai/paperclip/pull/123), @contributor1, @contributor2)

ルール：

• 特定のマージ済み PR に確実にたどり着ける場合にのみ、PR リンクを追加します。PR の特定には、マージコミットのメッセージ（Merge pull request #N from user/branch）を使用します。
• PR を作成したコントリビューターを記載します。実名やメールアドレスではなく、GitHub のユーザー名を使用してください。
• 1 つの項目に複数の PR が貢献している場合は、すべて記載します：([#10](url), [#12](url), @user1, @user2)。
• PR 番号やコントリビューターを確実に特定できない場合は、推測せず、帰属情報の括弧書きを省略します。
• 外部 PR を伴わないコアメンテナーのコミットは、括弧書きを省略できます。

ステップ 5 — ファイルを書く

ファイルパスは Channel Process セクションにあるベータ版のキーを使ったものです （releases/beta/v{beta-version}.md）が、内容には予定されている安定版のバージョンを記載します。次のコマンドで解決してください。 ./scripts/release.sh stable --date {planned-promotion-date} --print-version （昇格日は通常、ベータ版の公開日から 3 日間の検証期間を経た日です）。昇格日が後ろにずれた場合、ディスパッチ時にバージョンが再解決されます。ベータ版のキーを使ったファイル名であれば問題ないため、その際にタイトルを更新してください。

変更履歴の冒頭行は、# Paperclip {version} （波括弧なし）の形式の H1 にしてください。例：# Paperclip v2026.618.0。必ず Paperclip のプレフィックスと、バージョンの v を含めてください。

テンプレート：

# Paperclip vYYYY.MDD.P

> Released: YYYY-MM-DD

## Breaking Changes

## Highlights

## Improvements

## Fixes

## Upgrade Guide

## Contributors

Thank you to everyone who contributed to this release!

@username1, @username2, @username3

空のセクションは省略してください。ただし、Highlights、Improvements、Fixes は通常、含めてください。

Contributors セクションは必ず含めてください。リリース範囲内でコミットを作成したすべての人を、実名やメールアドレスではなく、GitHub ユーザー名で @ メンションしてください。GitHub ユーザー名の確認方法：

1. マージコミットのメッセージからユーザー名を抽出します：git log v{last}..{beta-src} --oneline --merges — ブランチのプレフィックス（例：from username/branch）から GitHub ユーザー名を特定できます。
2. [email protected] のような noreply メールアドレスでは、@ より前の部分がユーザー名です。
3. ユーザー名が曖昧な貢献者については、gh api users/{guess} または PR ページを確認してください。

貢献者のメールアドレスは絶対に公開しないでください。 @username のみを使用してください。

ボットアカウント（例：lockfile-bot、dependabot）は一覧から除外してください。 特定の人物も一覧から除外してください。Contributors セクションでクレジットするのは、コミュニティの貢献者のみです。正式な除外リスト（ここに記載し、Discord スキルはこのリストを参照します）： cryppadotta、forgottendev、devinfoley、sockmonster、scotttong、 nguyenm7、nickyleach、tonio-alucema

貢献者は GitHub ユーザー名のアルファベット順（大文字小文字を区別しない）に並べてください。

除外後に貢献者が残らない場合は、このセクションを省略し、言及もしないでください。

ステップ 5b — リリースケースを Upsert する

releases/vYYYY.MDD.P.md を作成した後、実行環境に Paperclip API のコンテキストがある場合は、トップレベルのリリースケースを作成または更新してください。API の仕様については skills/paperclip/references/cases.md を参照してください。API が 403 Cases are disabled を返した場合は、Cases を有効にする必要があることを報告し、変更履歴ファイルだけを作成してください。

リクエスト：

POST /api/companies/:companyId/cases
{
  "caseType": "release",
  "key": "paperclip-release:vYYYY.MDD.P",
  "title": "Paperclip vYYYY.MDD.P release",
  "summary": "Stable Paperclip release notes for vYYYY.MDD.P.",
  "status": "in_progress",
  "fields": {
    "schema_version": 1,
    "version": "vYYYY.MDD.P",
    "release_date": "YYYY-MM-DD",
    "release_patch": 0,
    "stable": true,
    "channels": ["changelog", "blog_post", "tweet_storm"],
    "artifacts": {
      "changelog_path": "releases/vYYYY.MDD.P.md",
      "github_release_url": null
    },
    "verification": {
      "typecheck": "unknown",
      "tests": "unknown",
      "build": "unknown",
      "smoke": "unknown"
    },
    "notes": null
  }
}

このフィールドスキーマでは、文字列、数値、ブール値、配列、オブジェクト、null という、すべての汎用フィールド値の型を意図的に使用しています。実行をまたいでもキーを変えず、アップサートごとにオブジェクト全体を送信してください。フィールドは置き換えられ、ディープマージされないためです。

次に、変更履歴をケース本文ドキュメントに書き込みます。

PUT /api/cases/:releaseCaseId/documents/body
{
  "title": "Paperclip vYYYY.MDD.P changelog",
  "format": "markdown",
  "body": "<contents of releases/vYYYY.MDD.P.md>",
  "changeSummary": "Initial stable changelog"
}

既存の本文ドキュメントを更新する場合は、まずケースを取得し、最新の baseRevisionId を渡してください。409 stale_base_revision が発生した場合は、再取得して意図的にマージし、1 回だけ再試行してください。

ステップ 6 — リリース前にレビューする

引き渡す前に、次の点を確認してください。

1. H1 見出しが # Paperclip {version}（例：# Paperclip v2026.618.0）で、安定版のバージョンのみを記載していること
2. タイトルにもファイル名にも -canary の表記がないこと
3. 破壊的変更にアップグレード手順があること
4. release ケースが存在すること、または Cases を利用できなかった理由を説明していること
5. ドラフトを人間による承認のために提示すること

このスキルでは、何も公開しません。安定版の変更履歴アーティファクトを準備するだけです。