バージョン管理

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

バージョン戦略

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

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

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

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

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

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

設定

バージョン定義

apps/<project-name>/src/config/project.config.json の versioning.versions で ID・表示名・リリース日・最新フラグを管理します。sample-docs の例：

{
  "versioning": {
    "versions": [
      {
        "id": "v1",
        "name": "Version 1.0",
        "date": "2024-01-01T00:00:00.000Z",
        "isLatest": false
      },
      {
        "id": "v2",
        "name": "Version 2.0",
        "date": "2025-01-01T00:00:00.000Z",
        "isLatest": true
      }
    ]
  }
}

直接編集する代わりに node scripts/create-version.js sample-docs v3 --interactive を使うと、バックアップ生成・表示名入力・コピー元の選択が自動化され、project.config.json の差分も整形済みで出力されます。

ディレクトリ構造

各バージョンは apps/<project-name>/src/content/docs/<version>/<lang>/ 配下に独自のカテゴリを持ちます：

apps/sample-docs/src/content/docs/
├── v1/ja/01-guide/...
└── v2/ja/
    ├── 01-guide/
    ├── 02-components/
    ├── 03-advanced/
    └── 04-reference/

バージョン間の移行

コンテンツの進化

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

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

移行ガイドの例

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

# v1からv2への移行

## 主な変更点

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

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

## 移行手順

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

古い構造：
    apps/sample-docs/src/content/docs/v1/ja/guide/basics.md
    apps/sample-docs/src/content/docs/v1/ja/components/sidebar.mdx

新しい構造：
    apps/sample-docs/src/content/docs/v2/ja/01-guide/01-basics.mdx
    apps/sample-docs/src/content/docs/v2/ja/02-components/04-sidebar-generation.mdx

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

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

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

バージョン切り替え

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

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

バージョンセレクター：共通ヘッダーに実装済み（project.config.json の isLatest を参照）
一貫したURL構造：/docs/sample-docs/ja/v1/01-guide/... と /docs/sample-docs/v2/ja/01-guide/...
クロスバージョンリンク：関連する他のバージョンのコンテンツへのリンク

自動リダイレクト

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

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

保守戦略

アクティブなバージョン

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

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

レガシーバージョン

古いバージョンの場合：

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

自動化ツール

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

node scripts/create-version.js sample-docs v3
project.config.json を更新し、既存バージョンをコピーして apps/sample-docs/src/content/docs/v3/<lang>/ をまとめて生成します。
--interactive を付けると表示名・コピー元・最新フラグをインタラクティブに決定できます。
--no-copy を付けると空のディレクトリのみ作成し、新規構成を 0 から組み立てられます。

言語追加スクリプト

node scripts/add-language.js sample-docs de --template-lang=ja
言語ディレクトリ生成、カテゴリー翻訳、sites/landing/src/config/projects.config.json の更新、.backups/ へのバックアップ、オプションでのビルドテスト実行をすべて自動化します。

ドキュメント作成スクリプト

node scripts/create-document.js sample-docs ja v2 --interactive
カテゴリ選択やタイトル入力、フロントマター生成を CLI で完結できます。カテゴリ構造を変えた際は scripts/validate-category-structure.js で翻訳キーのズレも検証可能です。

サイドバー更新

pnpm build:sidebar
すべてのアプリケーションを走査して apps/<project>/public/sidebar/sidebar-<lang>-<version>.json を生成します。--projects=sample-docs を付けた pnpm build:sidebar-selective を使うとピンポイントで再生成できます。

ベストプラクティス

バージョン命名

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

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

コンテンツの一貫性

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

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

ユーザーガイダンス

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

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

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

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

トラブルシューティング

一般的な問題

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

解決策

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

次のステップ

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

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