@asagiri-design/labels-config 0.2.2 → 0.3.0

package/docs/RELEASE_FLOW.md

@@ -0,0 +1,436 @@
+# npm Publish 更新フローガイド
+
+このドキュメントでは、`@boxpistols/labels-config` パッケージの npm への公開フローを説明します。
+
+## 📦 3つのリリース方法
+
+OIDC 対応後、以下の3つのリリース方法があります：
+
+| フロー | トリガー | バージョン | 用途 | 自動/手動 |
+|--------|---------|-----------|------|----------|
+| **auto-release** | main へマージ | patch のみ | 日常の開発 | ✅ 自動 |
+| **manual-release** | Actions UI | 選択可能 | 重要なリリース | 🎯 手動 |
+| **publish** | GitHub Release | 手動設定 | 特別なリリース | 🏷️ 手動 |
+
+---
+
+## 🔄 方法1: 自動リリース（推奨・メインフロー）
+
+### トリガー条件
+
+- **ブランチ**: `main`
+- **変更パス**: `src/**` または `package.json`
+- **除外**: コミットメッセージに `[skip ci]` または `[no release]` が含まれる場合
+
+### フロー
+
+```
+PR作成 → レビュー → main にマージ
+  ↓
+auto-release.yml 起動
+  ↓
+パッチバージョン自動更新 (例: 0.2.0 → 0.2.1)
+  ↓
+npm run build
+  ↓
+npm publish --provenance --access public
+  ↓
+git push --follow-tags
+  ↓
+✅ 公開完了
+```
+
+### 実際の操作
+
+```bash
+# 1. feature ブランチで作業
+git checkout -b feature/awesome-feature
+# コード変更
+git add .
+git commit -m "feat: add awesome feature"
+git push origin feature/awesome-feature
+
+# 2. PR を作成してレビュー
+gh pr create --title "Add awesome feature" --body "..."
+
+# 3. main にマージ（GitHub UI または CLI）
+gh pr merge --squash
+
+# 4. 自動的に実行される（何もする必要なし！）
+# ✅ 約2-3分後に npm に公開される
+```
+
+### リリースをスキップする場合
+
+```bash
+# ドキュメント更新のみの場合
+git commit -m "docs: update README [skip ci]"
+
+# 依存関係更新のみの場合
+git commit -m "chore: update dependencies [no release]"
+```
+
+### 確認方法
+
+```bash
+# GitHub Actions の実行状況を確認
+gh run list --workflow=auto-release.yml
+
+# 最新の npm バージョンを確認
+npm view @boxpistols/labels-config version
+```
+
+---
+
+## 🎯 方法2: 手動リリース（バージョン指定）
+
+### 用途
+
+- **minor**: 新機能を追加したとき（0.2.0 → 0.3.0）
+- **major**: 破壊的変更があるとき（0.3.0 → 1.0.0）
+- **prerelease**: ベータ版をリリースしたいとき（0.2.0 → 0.2.1-beta.0）
+- **patch**: 自動リリースを使わず手動で管理したいとき（0.2.0 → 0.2.1）
+
+### フロー
+
+```
+GitHub Actions タブ
+  ↓
+Manual Release を選択
+  ↓
+Run workflow をクリック
+  ↓
+バージョンタイプを選択 (patch/minor/major/prerelease)
+  ↓
+実行
+  ↓
+バージョン更新 → ビルド → npm publish → GitHub Release 作成
+  ↓
+✅ 完了
+```
+
+### 実際の操作（GitHub UI）
+
+1. リポジトリの **Actions** タブを開く
+2. 左サイドバーから **"Manual Release"** を選択
+3. **"Run workflow"** ボタンをクリック
+4. バージョンタイプを選択：
+   - `patch`: バグ修正（0.2.0 → 0.2.1）
+   - `minor`: 新機能（0.2.0 → 0.3.0）
+   - `major`: 破壊的変更（0.2.0 → 1.0.0）
+   - `prerelease`: ベータ版（0.2.0 → 0.2.1-beta.0）
+5. **"Run workflow"** をクリック
+
+### 実際の操作（gh CLI）
+
+```bash
+# minor バージョンをリリース
+gh workflow run manual-release.yml -f version_type=minor
+
+# major バージョンをリリース
+gh workflow run manual-release.yml -f version_type=major
+
+# prerelease (beta) をリリース
+gh workflow run manual-release.yml -f version_type=prerelease
+
+# 実行状況を確認
+gh run watch
+```
+
+### ベータ版の利用方法
+
+```bash
+# ベータ版をインストール
+npm install @boxpistols/labels-config@beta
+
+# 特定のベータバージョンをインストール
+npm install @boxpistols/labels-config@0.2.1-beta.0
+```
+
+---
+
+## 🏷️ 方法3: GitHub Release トリガー
+
+### 用途
+
+- 重要なマイルストーンリリース
+- リリースノートを詳細に記述したい場合
+- 特別なバージョン（例: v1.0.0）
+
+### フロー
+
+```
+GitHub Release 作成
+  ↓
+publish.yml 起動
+  ↓
+npm run build
+  ↓
+npm publish --provenance --access public
+  ↓
+npm run build:umd (CDN用)
+  ↓
+✅ 完了
+```
+
+### 実際の操作（GitHub UI）
+
+1. リポジトリページ → **Releases**
+2. **"Create a new release"** をクリック
+3. タグを作成（例: `v0.3.0`）
+4. リリースタイトルと詳細を入力
+5. **"Publish release"** をクリック
+
+### 実際の操作（gh CLI）
+
+```bash
+# シンプルなリリース
+gh release create v0.3.0 \
+  --title "Release v0.3.0" \
+  --notes "新機能追加"
+
+# 自動生成されたリリースノートを使用
+gh release create v0.3.0 \
+  --title "Release v0.3.0" \
+  --generate-notes
+
+# ドラフトリリース（後で公開）
+gh release create v0.3.0 \
+  --draft \
+  --title "Release v0.3.0" \
+  --notes "..."
+```
+
+---
+
+## 🔐 OIDC 認証フロー（内部動作）
+
+すべてのフローで共通して以下の認証が自動的に行われます：
+
+```
+GitHub Actions 実行
+  ↓
+permissions: id-token: write が設定されている
+  ↓
+GitHub が一時的な OIDC トークンを発行
+  ↓
+npm が GitHub の署名を検証
+  ↓
+Trusted Publisher 設定を確認
+  ↓
+認証成功
+  ↓
+npm publish 実行
+  ↓
+provenance (出所証明) が自動生成
+  ↓
+✅ パッケージ公開完了
+```
+
+### 従来方式との比較
+
+| 項目 | 従来（NPM_TOKEN） | 新方式（OIDC） |
+|------|------------------|---------------|
+| トークン保存 | GitHub Secrets に保存 | 不要 |
+| 有効期限 | 最大90日 | ジョブ実行時のみ（数分） |
+| ローテーション | 手動で90日ごと | 自動（毎回新規発行） |
+| 漏洩リスク | トークンが盗まれると悪用可能 | リスクほぼゼロ |
+| Provenance | 手動設定が必要 | 自動生成 |
+| 管理コスト | 高い | ほぼゼロ |
+
+---
+
+## 💡 推奨される運用フロー
+
+### 日常の開発フロー
+
+```bash
+# ✅ 推奨：自動リリースを活用
+git checkout -b feature/new-feature
+# コード変更
+git commit -m "feat: add new feature"
+git push
+# PR 作成・マージ → 自動的にパッチバージョンがリリース
+```
+
+### 新機能リリース（minor バージョンアップ）
+
+```bash
+# 1. main にマージ（自動でパッチバージョンがリリース）
+# 2. その後、手動で minor バージョンをリリース
+gh workflow run manual-release.yml -f version_type=minor
+# → 0.2.5 → 0.3.0
+```
+
+### 破壊的変更（major バージョンアップ）
+
+```bash
+# 1. main にマージ
+# 2. major バージョンをリリース
+gh workflow run manual-release.yml -f version_type=major
+# → 0.3.0 → 1.0.0
+```
+
+### ベータ版でのテスト
+
+```bash
+# 1. prerelease でベータ版をリリース
+gh workflow run manual-release.yml -f version_type=prerelease
+# → 0.3.0 → 0.3.1-beta.0
+
+# 2. ベータ版でテスト
+npm install @boxpistols/labels-config@beta
+
+# 3. 問題なければ正式リリース
+gh workflow run manual-release.yml -f version_type=minor
+# → 0.3.1-beta.0 → 0.4.0
+```
+
+---
+
+## 🔍 トラブルシューティング
+
+### エラー: "403 Forbidden" または "OIDC authentication failed"
+
+**原因**: npm で Trusted Publisher が正しく設定されていない
+
+**解決方法**:
+1. [npmjs.com](https://www.npmjs.com/) で Trusted Publisher 設定を確認
+2. Organization、Repository、Workflow、Job 名が正確に一致しているか確認
+3. 設定の詳細は [NPM_SETUP.md](./NPM_SETUP.md) を参照
+
+### エラー: "Provenance generation failed"
+
+**原因**: ワークフローの `permissions` 設定が不足している
+
+**解決方法**:
+- ワークフローファイルに以下が含まれているか確認：
+  ```yaml
+  permissions:
+    contents: write  # または read
+    id-token: write  # OIDC に必須
+  ```
+
+### 自動リリースがスキップされる
+
+**原因**: コミットメッセージに除外キーワードが含まれている
+
+**確認方法**:
+```bash
+git log -1 --pretty=%B
+```
+
+**解決方法**:
+- `[skip ci]` または `[no release]` を含まないコミットメッセージを使用
+
+### バージョンが更新されない
+
+**原因**: ワークフローが実行されていない、または失敗している
+
+**確認方法**:
+```bash
+# ワークフローの実行履歴を確認
+gh run list --workflow=auto-release.yml --limit 5
+
+# 失敗したワークフローのログを確認
+gh run view <run-id> --log-failed
+```
+
+### npm に公開されたか確認
+
+```bash
+# 最新バージョンを確認
+npm view @boxpistols/labels-config version
+
+# パッケージ情報を確認
+npm view @boxpistols/labels-config
+
+# provenance を確認
+npm view @boxpistols/labels-config --json | jq '.dist.integrity'
+```
+
+---
+
+## 📊 バージョニング戦略
+
+### Semantic Versioning (SemVer)
+
+このパッケージは [SemVer](https://semver.org/) に従っています：
+
+- **MAJOR** (1.0.0): 破壊的変更（API の変更など）
+- **MINOR** (0.1.0): 後方互換性のある新機能
+- **PATCH** (0.0.1): 後方互換性のあるバグ修正
+
+### 推奨されるバージョンアップ基準
+
+| 変更内容 | バージョンタイプ | 例 |
+|----------|----------------|-----|
+| バグ修正 | patch | 0.2.0 → 0.2.1 |
+| 新しいテンプレート追加 | minor | 0.2.0 → 0.3.0 |
+| 新しい CLI コマンド追加 | minor | 0.2.0 → 0.3.0 |
+| API の破壊的変更 | major | 0.2.0 → 1.0.0 |
+| 設定ファイルフォーマット変更 | major | 0.2.0 → 1.0.0 |
+| ドキュメント更新のみ | なし（[skip ci]） | - |
+| 依存関係更新のみ | patch または [skip ci] | 0.2.0 → 0.2.1 |
+
+---
+
+## 🎯 クイックリファレンス
+
+### 通常の開発
+
+```bash
+# PR をマージするだけ
+gh pr merge --squash
+# → 自動でパッチバージョンがリリース
+```
+
+### 新機能リリース
+
+```bash
+# GitHub Actions UI から Manual Release (minor) を実行
+# または
+gh workflow run manual-release.yml -f version_type=minor
+```
+
+### 破壊的変更リリース
+
+```bash
+# GitHub Actions UI から Manual Release (major) を実行
+# または
+gh workflow run manual-release.yml -f version_type=major
+```
+
+### ベータ版リリース
+
+```bash
+gh workflow run manual-release.yml -f version_type=prerelease
+```
+
+### リリースをスキップ
+
+```bash
+git commit -m "docs: update [skip ci]"
+```
+
+### リリース状況の確認
+
+```bash
+# ワークフロー実行状況
+gh run list --workflow=auto-release.yml --limit 5
+
+# npm での最新バージョン
+npm view @boxpistols/labels-config version
+```
+
+---
+
+## 📚 関連ドキュメント
+
+- [npm Trusted Publishers (OIDC) セットアップガイド](./NPM_SETUP.md)
+- [GitHub Actions ワークフロー](./.github/workflows/)
+- [npm package provenance](https://docs.npmjs.com/generating-provenance-statements)
+
+---
+
+**すべてのリリースは自動化されています。トークン管理は不要です 🎉**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asagiri-design/labels-config",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Terminal-first label management system for GitHub repositories using gh CLI - No token required",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
@@ -43,11 +43,7 @@
     "lint": "eslint src --fix",
     "cli": "tsx src/cli.ts",
     "prepublishOnly": "npm run build",
-    "version": "node -e \"const fs=require('fs');const v=require('./package.json').version;fs.writeFileSync('src/version.ts','export const version = \\''+v+'\\'\\n')\" && git add src/version.ts",
-    "release:patch": "npm version patch -m 'Release v%s [skip ci]' && npm publish --access public && git push --follow-tags",
-    "release:minor": "npm version minor -m 'Release v%s [skip ci]' && npm publish --access public && git push --follow-tags",
-    "release:major": "npm version major -m 'Release v%s [skip ci]' && npm publish --access public && git push --follow-tags",
-    "release:beta": "npm version prerelease --preid=beta -m 'Release v%s [skip ci]' && npm publish --access public --tag beta && git push --follow-tags"
+    "version": "node -e \"const fs=require('fs');const v=require('./package.json').version;fs.writeFileSync('src/version.ts','export const version = \\''+v+'\\'\\n')\" && git add src/version.ts"
   },
   "keywords": [
     "labels",