バージョン管理

バージョン戦略の計画から過去のコンテンツの保守まで、ドキュメントの複数バージョンを効果的に管理する方法を学びます。

バージョン戦略

新バージョンを作成するタイミング

以下の場合に新しいドキュメントバージョンを作成：

主要なAPI変更：ユーザーの実装に影響する破壊的変更
重要な機能追加：ワークフローを変更する新機能
プラットフォーム更新：主要なプラットフォームやフレームワークのアップグレード
対象読者の変更：異なるアプローチが必要な異なるユーザータイプ

バージョンライフサイクル

典型的なバージョンライフサイクル：

開発中：積極的に開発中のバージョン
現在/最新：主要サポートバージョン
保守：重要な更新のみ受信
非推奨：更新停止、参照用にアーカイブ
アーカイブ済み：メインナビゲーションから削除、直接リンクでアクセス可能

設定

バージョン定義

project.config.tsでバージョンを定義：

versions: [
  { 
    id: 'v1', 
    name: 'バージョン 1.0', 
    date: new Date('2024-01-01'), 
    isLatest: false 
  },
  { 
    id: 'v2', 
    name: 'バージョン 2.0', 
    date: new Date('2025-01-01'), 
    isLatest: true 
  }
]

ディレクトリ構造

各バージョンは独自のディレクトリを持ちます：

src/content/docs/ja/
├── v1/              # バージョン1.0のコンテンツ
│   ├── guide/
│   └── reference/
└── v2/              # バージョン2.0のコンテンツ
    ├── guide/
    ├── components/
    ├── advanced/
    └── reference/

バージョン間の移行

コンテンツの進化

新しいバージョンを作成する際：

既存コンテンツの評価：何が変更され、何が残るか
新機能の文書化：追加された機能の説明
移行ガイドの作成：バージョン間の変更点を説明
従来のコンテンツの保持：参照用に古いバージョンを維持

移行ガイドの例

---
title: "v1からv2への移行"
description: "バージョン1.0から2.0への移行に必要な変更点"
---

# v1からv2への移行

## 主な変更点

### 新機能
- インタラクティブコンポーネント
- 高度なカスタマイズオプション
- 自動化ツール

### 破壊的変更
- フロントマターの簡素化
- ファイル構造の変更
- 新しい命名規則

## 移行手順

### 1. ファイル構造の更新

古い構造：
    docs/guide/basics.md
    docs/components/buttons.md

新しい構造：
    docs/01-guide/01-basics.mdx
    docs/02-components/01-buttons.mdx

### 2. フロントマターの簡素化

古いフロントマター：
    ---
    title: "基本"
    description: "基本的な使用法"
    order: 1
    category: "guide"
    author: "Author Name"
    pubDate: 2024-01-01
    ---

新しいフロントマター：
    ---
    title: "基本"
    description: "基本的な使用法"
    ---

バージョン切り替え

ユーザーエクスペリエンス

ユーザーがバージョン間を簡単に移動できるようにする：

バージョンセレクター：ヘッダーまたはサイドバーに配置
一貫したURL構造：/ja/v1/guide/、/ja/v2/guide/
クロスバージョンリンク：関連する他のバージョンのコンテンツへのリンク

自動リダイレクト

適切な場合にユーザーをガイド：

// 非推奨バージョンから最新バージョンへのリダイレクト例
if (version === 'v0' && !user.preferences.showDeprecated) {
  redirect(`/ja/v2${currentPath}`);
}

保守戦略

アクティブなバージョン

現在サポートされているバージョンの場合：

定期的な更新：新しい情報や改善を反映
バグ修正：エラーや不正確さの迅速な修正
ユーザーフィードバック：コメントや提案への対応
パフォーマンス最適化：読み込み時間と使いやすさの改善

レガシーバージョン

古いバージョンの場合：

クリティカルな修正のみ：セキュリティや重大なエラーの修正
非推奨通知：ユーザーに新しいバージョンへの移行を促す
アーカイブ計画：いつ完全にアーカイブするかの計画

自動化ツール

バージョン作成スクリプト

新しいバージョンの作成を自動化：

# 新しいバージョンの作成
pnpm create:version sample-docs v3

# 前のバージョンからのコンテンツコピー
pnpm copy:version sample-docs v2 v3

一括更新

複数のバージョンにわたる変更：

# すべてのバージョンでテンプレートを更新
pnpm update:template --all-versions

# 特定のファイルを複数バージョンで更新
pnpm update:cross-version README.md

ベストプラクティス

バージョン命名

一貫した命名規則を使用：

セマンティックバージョニング：v1.0、v1.1、v2.0
明確な識別子：v2024、legacy、beta
説明的な名前：modern、classic、next

コンテンツの一貫性

バージョン間で共通の要素を統一：

ナビゲーション構造：可能な限り類似の構造を維持
用語と概念：一貫した用語の使用
スタイルガイド：同じ文体とフォーマット規則

ユーザーガイダンス

ユーザーが適切なバージョンを選択できるよう支援：

## バージョン選択ガイド

### v2（推奨）
- 最新機能とベストプラクティス
- アクティブサポートと更新
- 新規プロジェクトに推奨

### v1（保守のみ）
- 既存プロジェクト用
- 重要な修正のみ
- 可能な限りv2への移行を推奨

トラブルシューティング

一般的な問題

リンク切れ：バージョン間での参照の更新忘れ
コンテンツの重複：複数バージョンでの同期の問題
ユーザーの混乱：どのバージョンを使用すべきかの不明瞭さ

解決策

自動リンクチェック：定期的なリンク検証
差分ツール：バージョン間の変更追跡
明確なガイダンス：バージョン選択の明確な指針

次のステップ

バージョン管理の基本を理解したら：

コンポーネント概要：利用可能なUIコンポーネントとその使用法
自動化：バージョン管理を含む自動化ツール
デプロイ：複数バージョンのデプロイ戦略