バージョニング戦略

このドキュメントは、MixSeek-Core のバージョニング戦略とリリースプロセスについて説明します。

バージョン体系

MixSeek-Core は PEP 440 に準拠したバージョニングを採用しています。

バージョン形式

MAJOR.MINOR.PATCH[PRE-RELEASE]

例：

0.1.0a1 - Alpha リリース（バージョン 0.1.0 の 1 番目のアルファ版）
0.2.0b2 - Beta リリース（バージョン 0.2.0 の 2 番目のベータ版）
0.2.0rc1 - Release Candidate（バージョン 0.2.0 のリリース候補版）
1.0.0 - 正式リリース

リリースステージ

ステージ	形式	安定性	セキュリティ	破壊的変更
Alpha	`0.x.ya*`	低	なし	あり
Beta	`0.x.yb*`	中	最善努力	あり
RC	`0.x.yrc*`	高	最善努力	なし
Stable	`x.y.z`	高	保証	1.0.0 以上のみ

開発サイクル

Alpha 段階（0.x.ya*）

状況: 開発中、実験的機能の追加

リリース頻度: 2週間ごと

特徴:

破壊的変更が頻繁に発生
API 設計が不安定
セキュリティ保証なし
バグ修正のみの運用ではない

例:

0.1.0a1 → 0.1.0a2 → 0.2.0a1 → 0.2.0a2 → ...

Beta 段階（0.x.yb*）

状況: 機能はほぼ完成、テスト・洗練中

条件:

主要機能が実装完了
複数エンジニアでのテスト完了
API がほぼ安定

例:

0.3.0b1 (機能完成版) → 0.3.0b2 (バグ修正) → 0.3.0rc1

Release Candidate（0.x.yrc*）

状況: 本番環境テスト前の最終確認

条件:

Beta での問題が解決
本番環境でのテスト予定
API が確定

リリース頻度: 問題発見時のみ

Stable（1.0.0+）

状況: 本番環境対応版

条件:

RC での全問題が解決
本番環境で十分なテスト実施
セキュリティ対応体制確立
サポート体制確立

破壊的変更: MAJOR バージョン更新のみ

バージョン更新ルール

パッチバージョン更新（0.1.0 → 0.1.1）

条件:

バグ修正のみ
API 変更なし
破壊的変更なし

コマンド:

# Alpha 版の場合 (0.1.0a1 → 0.1.1a1)
$ uv run cz bump --prerelease alpha --increment PATCH --yes

# Stable 版の場合 (0.1.0 → 0.1.1)
$ uv run cz bump --increment PATCH --yes

マイナーバージョン更新（0.1.0 → 0.2.0）

条件:

新機能追加
Alpha/Beta/RC 段階では破壊的変更を含む場合あり
1.0.0 以上では破壊的変更なし

コマンド:

# Alpha 版の場合 (0.1.0a1 → 0.2.0a1)
$ uv run cz bump --prerelease alpha --increment MINOR --yes

# Stable 版の場合 (0.1.0 → 0.2.0)
$ uv run cz bump --increment MINOR --yes

メジャーバージョン更新（0.x.x → 1.0.0）

条件:

メジャー機能の完成
API の安定化
本番環境対応
セキュリティ保証の開始

コマンド:

# Alpha 版の場合 (0.1.0a1 → 1.0.0a1)
$ uv run cz bump --prerelease alpha --increment MAJOR --yes

# Stable 版の場合 (0.x.x → 1.0.0)
$ uv run cz bump --increment MAJOR --yes

リリーススケジュール

標準リリースサイクル

フェーズ	期間	バージョン	リリース頻度
Alpha	0.1.0 - 0.9.x	0.x.ya*	2 週間ごと
Beta	-	0.x.yb*	必要に応じて
RC	-	0.x.yrc*	必要に応じて
Stable	1.0.0+	x.y.z	月 1 回程度

リリース日時

リリース決定: 毎週金曜日
リリース実施: 翌月曜日
公式発表: リリース当日

commitizen による自動更新

動作概要

現在 Alpha 版のため、--prerelease alpha オプションが必須です。

# Alpha 版のビルド番号をインクリメント (0.1.0a1 → 0.1.0a2)
$ uv run cz bump --prerelease alpha --yes

実行時に以下が自動で行われます：

コミット解析: Conventional Commits 形式のコミットメッセージを解析
バージョン決定: コミットタイプに基づいて自動的にバージョン更新レベルを決定
- feat: → MINOR バージョン更新（stable 版）/ ビルド番号更新（prerelease 版）
- fix: → PATCH バージョン更新（stable 版）/ ビルド番号更新（prerelease 版）
- feat!:, fix!: → MAJOR バージョン更新（破壊的変更）
- 注: --prerelease alpha 使用時は、コミットタイプに関わらずビルド番号のみインクリメント（0.1.0a1 → 0.1.0a2）
ファイル更新:
- pyproject.toml: version フィールド更新
- CHANGELOG.md: Conventional Commits から自動生成
Git 操作:
- 変更をコミット（メッセージ: release: bump version to x.x.x）
- 注釈付きタグ作成（タグ名: vx.x.x）

設定ファイル（`pyproject.toml`）

[tool.commitizen]
name = "cz_conventional_commits"
version = "0.1.0a1"
version_files = [
    "pyproject.toml:version"
]
tag_format = "v$version"
update_changelog_on_bump = true
annotated_tag = true
bump_message = "release: bump version to $new_version"
changelog_file = "CHANGELOG.md"
changelog_incremental = true
version_scheme = "pep440"

ドライラン（テスト実行）

変更を適用する前に確認したい場合：

# Alpha 版の場合
$ uv run cz bump --prerelease alpha --dry-run --yes

手動でのバージョン制御

自動判定を上書きしたい場合：

# Alpha 版でマイナーバージョン強制更新 (0.1.0a1 → 0.2.0a1)
$ uv run cz bump --prerelease alpha --increment MINOR --yes

# Alpha 版でパッチバージョン強制更新 (0.1.0a1 → 0.1.1a1)
$ uv run cz bump --prerelease alpha --increment PATCH --yes

# Alpha 版でメジャーバージョン強制更新 (0.1.0a1 → 1.0.0a1)
$ uv run cz bump --prerelease alpha --increment MAJOR --yes

# Alpha 版から正式版へ昇格 (0.1.0a1 → 0.1.0)
$ uv run cz bump --yes

CHANGELOG.md との連携

CHANGELOG 自動生成

重要: CHANGELOG.md は commitizen により Conventional Commits から自動生成されます。手動編集は不要です。

生成ロジック

commitizen は以下のルールで CHANGELOG を生成します：

feat: コミット → Feat セクション
fix: コミット → Fix セクション
docs: コミット → Docs セクション
refactor: コミット → Refactor セクション
test: コミット → Test セクション
BREAKING CHANGE → BREAKING CHANGES セクション

例: Conventional Commits から CHANGELOG 生成

コミット履歴:

$ git log --oneline
abc1234 feat: add multi-agent orchestration framework
def5678 feat(cli): add mixseek exec command
ghi9012 fix: resolve memory leak in agent cleanup
jkl3456 docs: update getting-started guide

commitizen 実行:

# Alpha 版の場合（ビルド番号のみインクリメント）
$ uv run cz bump --prerelease alpha --yes
# → 0.1.0a1 → 0.1.0a2

# Stable 版または Alpha → Stable 昇格の場合
$ uv run cz bump --yes
# → 0.1.0a1 → 0.2.0 (feat: コミットがあるため MINOR バージョン更新)

生成された CHANGELOG.md:

## v0.2.0 (2025-12-18)

### Feat

- add multi-agent orchestration framework
- **cli**: add mixseek exec command

### Fix

- resolve memory leak in agent cleanup

### Docs

- update getting-started guide

## v0.1.0a1 (2025-12-04)

### Feat

- Initial alpha release
- Multi-agent orchestration framework with Leader/Member agent hierarchy
- ...

Conventional Commits によるバージョン制御

このプロジェクトでは Conventional Commits が必須です。

バージョンアップルール

コミットタイプ	Stable 版（1.0.0+）	Prerelease 版（0.x.ya*）
`feat:`	MINOR バージョン更新	build 番号更新
`fix:`	PATCH バージョン更新	build 番号更新
`feat!:`, `fix!:`	MAJOR バージョン更新	build 番号更新
`docs:`, `refactor:`, `test:`	影響なし	影響なし

例: Alpha 版（現在）

# 現在のバージョン: 0.1.0a1

$ git commit -m "feat: new agent integration system"
$ uv run cz bump --prerelease alpha --yes
# → 0.1.0a1 → 0.1.0a2 (build 番号のみインクリメント)

$ git commit -m "fix: memory leak in processing"
$ uv run cz bump --prerelease alpha --yes
# → 0.1.0a2 → 0.1.0a3 (build 番号のみインクリメント)

# マイナーバージョンアップを強制したい場合
$ uv run cz bump --prerelease alpha --increment MINOR --yes
# → 0.1.0a3 → 0.2.0a1

例: Stable 版（1.0.0 以降）

# 現在のバージョン: 1.2.3

$ git commit -m "feat: new agent integration system"
$ uv run cz bump --yes
# → 1.2.3 → 1.3.0 (MINOR バージョン更新)

$ git commit -m "fix: memory leak in processing"
$ uv run cz bump --yes
# → 1.3.0 → 1.3.1 (PATCH バージョン更新)

$ git commit -m "feat!: redesigned API structure"
$ uv run cz bump --yes
# → 1.3.1 → 2.0.0 (MAJOR バージョン更新)

トラブルシューティング

commitizen が動作しない場合

# 1. インストール確認
$ uv run cz version

# 2. 設定ファイル確認
$ grep -A 20 "\[tool.commitizen\]" pyproject.toml

# 3. ドライラン確認
$ uv run cz bump --dry-run --yes

Conventional Commits フォーマットエラー

# エラー例: commitizen がバージョンを決定できない
# 原因: Conventional Commits 形式に従っていないコミットメッセージ

# ✅ 正しい形式
$ git commit -m "feat: add new feature"
$ git commit -m "fix: resolve bug"

# ❌ 間違った形式
$ git commit -m "Add new feature"  # タイプがない
$ git commit -m "feat add feature"  # コロンがない
$ git commit -m "Feat: add feature"  # 大文字（小文字を使用）

プレリリース版の作成方法

Beta 版や Release Candidate 版を作成する場合：

# Alpha リリース作成
$ uv run cz bump --prerelease alpha --yes
# → 0.1.0 → 0.2.0a1

# Beta リリース作成
$ uv run cz bump --prerelease beta --yes
# → 0.2.0a1 → 0.2.0b1

# Release Candidate 作成
$ uv run cz bump --prerelease rc --yes
# → 0.2.0b1 → 0.2.0rc1

# プレリリースを正式版に昇格
$ uv run cz bump --yes
# → 0.2.0rc1 → 0.2.0

バージョニング戦略

バージョン体系

バージョン形式

リリースステージ

開発サイクル

Alpha 段階（0.x.ya*）

Beta 段階（0.x.yb*）

Release Candidate（0.x.yrc*）

Stable（1.0.0+）

バージョン更新ルール

パッチバージョン更新（0.1.0 → 0.1.1）

マイナーバージョン更新（0.1.0 → 0.2.0）

メジャーバージョン更新（0.x.x → 1.0.0）

リリーススケジュール

標準リリースサイクル

リリース日時

commitizen による自動更新

動作概要

設定ファイル（pyproject.toml）

ドライラン（テスト実行）

手動でのバージョン制御

CHANGELOG.md との連携

CHANGELOG 自動生成

生成ロジック

例: Conventional Commits から CHANGELOG 生成

Conventional Commits によるバージョン制御

バージョンアップルール

例: Alpha 版（現在）

例: Stable 版（1.0.0 以降）

トラブルシューティング

commitizen が動作しない場合

Conventional Commits フォーマットエラー

プレリリース版の作成方法

関連リンク

設定ファイル（`pyproject.toml`）