ユニバーサルドキュメンテーション更新ツール

最新のリリースタグ以降のgit変更を分析し、それに応じて更新すべきドキュメンテーションファイルを更新します。

概要

git履歴を使用してリリース関連の変更を特定し、README.md、CHANGELOG.md、および関連するドキュメンテーションフォルダを更新します。ユーザーの明示的な承認、正確な編集、およびリポジトリ固有のドキュメンテーション構造に焦点を当てたワークフローを保つようにしてください。

使用時期

このスキルは以下の場合に使用してください:

• リリースノートまたはUnreleasedチェンジログ更新を準備する場合
• 機能が統合された後、README.mdまたはドキュメンテーションを同期する場合
• PRまたはリリース前に最後のリリース以降の変更内容を確認する場合

前提条件

開始する前に、以下の条件が満たされていることを確認してください:

# gitリポジトリであることを確認
git rev-parse --git-dir

# gitタグが存在することを確認
git tag --list | head -5

# ドキュメンテーションファイルが存在することを確認
test -f README.md || echo "README.md not found"
test -f CHANGELOG.md || echo "CHANGELOG.md not found"

タグが存在しない場合は、このスキルが比較対象として少なくとも1つのリリースタグが必要であることをユーザーに通知してください。

手順

フェーズ1: 最新リリースバージョンの検出

目標: 比較対象となる最新リリースバージョンを特定する。

アクション:

1. 比較ベースラインを検出して表示します:

LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null)

if [ -z "$LATEST_TAG" ]; then
    echo "No git tags found. This skill requires at least one release tag."
    echo "Please create a release tag first (e.g., git tag -a v1.0.0 -m 'Initial release')"
    exit 1
fi

CURRENT_BRANCH=$(git branch --show-current)
VERSION=$(echo "$LATEST_TAG" | sed -E 's/^[^0-9]*([0-9]+\.[0-9]+\.[0-9]+).*/\1/')

echo "Latest release tag: $LATEST_TAG"
echo "Version detected: $VERSION"
echo "Comparing: $LATEST_TAG -> $CURRENT_BRANCH"

フェーズ2: git差分分析の実行

目標: 最後のリリースと現在のブランチ間のすべての変更を分析する。

アクション:

1. コミット範囲と統計情報を取得します:

# タグとHEAD間のコミット数を取得
COMMIT_COUNT=$(git rev-list --count ${LATEST_TAG}..HEAD 2>/dev/null || echo "0")
echo "Commits since $LATEST_TAG: $COMMIT_COUNT"

# ファイル変更の統計情報を取得
git diff --stat ${LATEST_TAG}..HEAD

2. 分析用のコミットメッセージを抽出します:

# 範囲内のすべてのコミットメッセージを取得
COMMITS=$(git log ${LATEST_TAG}..HEAD --pretty=format:"%h|%s|%b" --reverse)

# レビュー用にコミットを表示
echo "$COMMITS"

3. 詳細なファイル変更を取得します:

# 変更されたファイルのリストを取得
CHANGED_FILES=$(git diff --name-only ${LATEST_TAG}..HEAD)

# クイック分類用に追加/変更/削除ステータスを表示
git diff --name-status ${LATEST_TAG}..HEAD

4. ファイルパスに基づいてコンポーネント領域を特定します:

# どのコンポーネント/領域が変更されたかを検出
echo "$CHANGED_FILES" | grep -E "^plugins/" | cut -d'/' -f2 | sort -u

フェーズ3: ドキュメンテーション構造の発見

目標: プロジェクト内のすべての関連するドキュメンテーション場所を特定する。

アクション:

1. 標準ドキュメンテーションフォルダを検索します:

# 一般的なドキュメンテーション場所をチェック
DOC_FOLDERS=()

[ -d "docs" ] && DOC_FOLDERS+=("docs/")
[ -d "documentation" ] && DOC_FOLDERS+=("documentation/")
[ -d "doc" ] && DOC_FOLDERS+=("doc/")

# プラグイン固有のドキュメンテーションを検索
for plugin_dir in plugins/*/; do
    if [ -d "${plugin_dir}docs" ]; then
        DOC_FOLDERS+=("${plugin_dir}docs/")
    fi
done

echo "Documentation folders found:"
printf '  - %s\n' "${DOC_FOLDERS[@]}"

2. 既存のドキュメンテーションファイルを特定します:

# 標準docファイルをチェック
DOC_FILES=()

[ -f "README.md" ] && DOC_FILES+=("README.md")
[ -f "CHANGELOG.md" ] && DOC_FILES+=("CHANGELOG.md")
[ -f "CONTRIBUTING.md" ] && DOC_FILES+=("CONTRIBUTING.md")
[ -f "docs/GUIDE.md" ] && DOC_FILES+=("docs/GUIDE.md")

echo "Documentation files found:"
printf '  - %s\n' "${DOC_FILES[@]}"

フェーズ4: チェンジログ更新の生成

目標: Keep a Changelog標準に従ったカテゴリ化されたチェンジログエントリを作成する。

アクション:

1. 従来型コミットのセマンティクスを使用してコミットを解析し、Added、Changed、Fixed、Removed、SecurityなどのKeep a Changelogセクションにマッピングします。

2. 既存のCHANGELOG.mdを読み込んで構造を理解してから、Keep a Changelogフォーマットに従って新しいエントリを生成します。

詳細なbashコマンドとチェンジログテンプレートについては、references/examples.mdを参照してください。

フェーズ5: README.mdの更新

目標: 関連する高レベルの変更でメインREADMEを更新する。

アクション:

1. 現在のREADME.mdを読み込んで構造を理解する
2. 更新が必要なセクション(フィーチャーリスト、スキル/エージェント、セットアップ手順、バージョン参照)を特定する
3. Editツールを使用して更新を適用: 構造を保持し、トーンを保つ、バージョン番号を更新する

フェーズ6: ドキュメンテーションフォルダの更新

目標: 関連するドキュメンテーション内の変更をdocs/フォルダに伝播する。

アクション:

1. 見つかった各ドキュメンテーションフォルダについて、変更されたコードを参照するファイルを確認する
2. 変更されたファイルをそのドキュメンテーションにマップする
3. 更新を生成: 新しいフィーチャードキュメントを追加、APIリファレンスを更新、古い例を修正する

詳細な発見パターンと更新戦略については、references/examples.mdを参照してください。

フェーズ7: レビュー用に変更を提示

目標: 変更を適用する前にユーザーに何が更新されるかを表示する。

アクション:

1. 提案されている変更の概要を提示します:

## Proposed Documentation Updates

### Version Information
- Previous release: $LATEST_TAG
- Current branch: $CURRENT_BRANCH
- Commits analyzed: $COMMIT_COUNT

### Files to Update
- [ ] CHANGELOG.md - Add new version section with categorized changes
- [ ] README.md - Update [specific sections]
- [ ] docs/[specific files] - Update documentation

### Summary of Changes
**Added**: N new features
**Changed**: N modifications
**Fixed**: N bug fixes
**Breaking**: N breaking changes

2. AskUserQuestion経由でユーザーに確認を求めます:

• どのファイルを更新するかを確認する
• いずれかの変更を変更すべきかどうかを質問する
• 進行の承認を得る

フェーズ8: ドキュメンテーション更新の適用

目標: 承認された更新を書き込み、正しく着地したことを確認する。

アクション:

1. CHANGELOG.mdを更新します:

# 現在のチェンジログを読み込む
CURRENT_CHANGELOG=$(cat CHANGELOG.md)

# 新しいセクションを前に追加
cat > CHANGELOG.md << 'EOF'
# Changelog

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

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
[New content goes here]

[Rest of existing changelog]
EOF

2. Editツールを使用してREADME.mdを更新します:

• 特定のセクションに対して対象を絞った編集を行う
• 全体的な構造を保持する
• 必要に応じてバージョン番号を更新する

3. ドキュメンテーションファイルを更新します:

# 更新が必要な各ドキュメンテーションファイルについて
# Editツールを使用して正確な変更を行う

4. 適用された変更を検証します:

# 編集後もキーファイルが存在することを確認
test -f CHANGELOG.md && echo "CHANGELOG.md present"
test -f README.md && echo "README.md present"

# markdownファイルの変更範囲をレビュー
git diff --stat -- '*.md'

# 実際に書き込まれたコンテンツをスポットチェック
git diff -- '*.md' | sed -n '1,240p'

5. リポジトリがドキュメンテーションまたはmarkdown検証コマンドを既に定義している場合、完了する前に実行してください。

例

例1: 機能開発後の更新

ユーザーリクエスト: 「追加した新しい機能のドキュメントを更新してください」

出力:

• 最新タグ: v2.4.1 → 現在のブランチ: develop
• 5つのコミットを分析
• 新しいSpring Boot Actuatorスキル用のCHANGELOGエントリが生成
• README.mdスキルリストが更新

例2: リリースドキュメンテーションの準備

ユーザーリクエスト: 「v2.5.0リリース用のドキュメンテーションを準備してください」

出力:

• v2.4.1以降47個のコミットを分析
• 15個の機能、8個の修正、3個の破壊的変更を検出
• 完全なCHANGELOG.md [2.5.0]セクションを生成
• README.mdとプラグインドキュメントを更新

例3: 増分同期

ユーザーリクエスト: 「ドキュメントを同期してください、いくつか変更を加えました」

出力:

• 2つのコミットを分析
• github-issue-workflowスキル変更に対する焦点を絞ったCHANGELOG更新
• README.mdやプラグインドキュメント更新は不要

詳細なセッショントランスクリプトとトラブルシューティングについては、references/examples.mdを参照してください。

ベストプラクティス

1. 書き込み前に確認、書き込み後に検証: まずプランを表示してから、編集後の最終的な差分を確認する
2. Keep a Changelogに従う: 一貫したチェンジログフォーマットを維持する
3. 適切に分類する: 正しいカテゴリ(Added、Changed、Fixed等)を使用する
4. 具体的にする: チェンジログエントリにプラグイン/コンポーネント名を含める
5. 構造を保持する: 既存のドキュメンテーション構造とスタイルを維持する
6. コミットを参照する: 有用な場合、追跡可能性のためにコミットハッシュを含める
7. 破壊的変更を処理する: マイグレーション注記付きで破壊的変更を明確に強調する
8. バージョン参照を更新する: ドキュメンテーション全体でバージョン番号を一貫して保つ

制約と警告

1. gitタグが必須: このスキルはリポジトリに少なくとも1つのリリースタグがある場合にのみ機能します
2. 読み取り専用分析: このスキルは変更を分析しますが、書き込み前に確認を求めます
3. 手動レビューが必須: 生成されたチェンジログエントリは精度についてレビューする必要があります
4. 従来型コミット: 従来型コミットフォーマットを使用するプロジェクトで最適に動作します
5. タグを作成しない: このスキルはドキュメントを更新しますがリリースタグを作成しません
6. 自動コミットなし: ドキュメンテーション変更は準備されますが自動的にコミットされません
7. プロジェクト固有のパターン: 一部のプロジェクトは尊重すべきカスタムチェンジログフォーマットを有している場合があります
8. ファイルパス: すべてのファイルパスはクロスプラットフォーム互換性のためにフォワードスラッシュ(Unixスタイル)を使用します