Skip to main content

リリース過程

ここでは、Docusaurusがバージョン管理、リリース、破壊的変更についてどのように扱うのかを説明します。

情報

本トピックは、アップグレードに困難を伴いうる高度にカスタマイズがされたサイトにとって特に重要です。

セマンティックバージョニング​

Docusaurusのバージョン表記は、「(メジャー).(マイナー).(パッチ)」という方式に従っており、セマンティックバージョニングを遵守しています。

セマンティックバージョニングを遵守することは、次に挙げるいくつかの理由により重要です。

  • It guarantees simple minor version upgrades, as long as you only use the public API
  • It follows front-end ecosystem conventions
  • A new major version is an opportunity to thoroughly document breaking changes
  • A new major/minor version is an opportunity to communicate new features through a blog post
メモ

Docusaurus 2.0のリリースには、長大な時間を要しました。 今後、Docusaurusは 新しいメジャーバージョンをよりこまめにリリースします。 実際のところ、2～4ヶ月ごとに新しいメジャーバージョンを期待できます。

Major version numbers are not sacred, but we still group breaking changes together and avoid releasing major versions too often.

メジャーバージョン​

メジャーバージョン番号は、破壊的変更がなされるごとに増加します。

新しいメジャーバージョンがリリースされるたびに、次のものを掲載します。

  • 新機能紹介、主要なバグ修正、破壊的変更、アップグレード手順に関するブログ記事
  • 包括的な変更履歴の記載
ヒント

公開APIの項目に目を通し、何が破壊的変更とされるのかをよく理解してください。

マイナーバージョン​

マイナーバージョン番号は、後方互換性を持つ重要な変更がなされるごとに増加します。

新しいマイナーバージョンがリリースされるたびに、次のものを掲載します。

  • 新機能紹介、主要なバグ修正に関するブログ記事
  • 包括的な変更履歴の記載
ヒント

公開APIしか使っていないのでしたら、すぐにアップグレードできるはずです！

パッチバージョン​

パッチバージョン番号は、バグ修正のリリース時に増加します。

新しいパッチバージョンがリリースされるたびに、次のものを掲載します。

  • 包括的な変更履歴の記載

バージョン​

Docusaurusチームは、現在次の2つのメジャーバージョンの開発に同時に取り組んでいます。

  • Docusaurus 2: 安定版（docusaurus-v2ブランチ上）
  • Docusaurus 3: 次期版（mainブランチ上）
メモ

docusaurus-v2ブランチは、バージョン2の最初のリリース候補版がリリースされる直前に作成されます。

安定版​

安定版（バージョン2・docusaurus-v2上）は、大半のDocusaurusユーザに推奨されます。

私たちは、後方互換性のある機能、バグやセキュリティの修正をmainからdocusaurus-v2へ、git cherry-pickを利用して定期的にバックポートし、次期版に対応していないプロジェクトにも行き届くようにしています。

情報

新しい安定版がリリースされた後、直前の安定版は3ヶ月間主要なセキュリティ問題についてのサポートのみ受け付けます。 その他、すべての機能の開発は停止し、重大でないバグは修正されません。

その期間内に新しい安定版へアップグレードすることを推奨します。

次期版​

次期版（バージョン3・main上）はDocusaurusチームが現在取り組んでいるバージョンです。

mainブランチは、コアチーム及び外部からの貢献を含む全プルリクエストの既定のターゲットブランチです。

本バージョンはDocusaurusの最新機能をいち早く利用してみたいアーリーアダプタ（訳注：初期採用層・人柱）に推奨されます。 また、バグを報告したりフィードバックを提供することでも、私たちの開発を支援することができます。

次期版を使うには、次の3つの方法があります。

  • alpha・beta・rcのついたプレリリース版を利用
  • 最新のプレリリース版を利用するために@nextというnpmディストリビューションタグをつける
  • 最新中の最新機能を利用するためにCanaryリリースを利用
ヒント

次期版は全ての自動テストをクリアしており、Docusaurusのサイト自体で使用されています。 比較的安全です。ご遠慮なくお試しください。

警告

破壊的変更は次期版で行われる場合があります。詳細なアップグレード手順は、変更履歴とプルリクエストにて記載されます。

betaやrc（リリース候補）の段階では、大規模な破壊的変更の導入は極力しないようにします。

公開API​

Docusaurusは、セマンティック・バージョニングの尊重を約束します。 すなわち、Docusaurusの公開APIに変更が発生し、それにより後方互換性が損なわれるたびに、メジャーバージョン番号を増加させます。

ヒント

Docusaurusは、マイナーバージョン間の公開APIの後方互換性を担保しています。 内部APIを使用しない限り、 マイナー バージョンのアップグレードは容易なはずです。

以下では、何が公開APIに含まれるのかについて概要を説明します。

コア公開API​

公開APIには以下のものが含まれます。

  • Docusaurusの設定
  • DocusaurusクライアントAPI
  • Docusaurus CLI
  • 設定オプション
  • プラグイン
  • プラグインライフサイクルAPI
  • テーマ設定
  • コアプラグインルートコンポーネントのプロパティ
  • @docusaurus/types TypeScript型定義
    • 私たちは引き続き型をより厳格化する自由を有します(型チェックを破る可能性があります)。

❌ Our public API excludes:

  • Docusaurus config future
  • All features prefixed by experimental_ or unstable_
  • All features prefixed by v<MajorVersion>_ (v6_ v7_, etc.)
ヒント

テーマ以外のAPIでは、文書化されたAPIは全て公開（すなわち安定）と、また文書化されていないものは全て内部とみなされます。

APIが「安定」しているということは、Docusaurusのパッチまたはマイナーバージョンを上げた場合、それ以外の変更を加えていないならばdocusaurus startやdocusaurus buildを実行してもエラーが発生しないということを意味します。

テーマ公開API​

Docusaurusには、次のような特長を持つ非常に柔軟なテーマ設定システムがあります。

  • カスタムCSSが利用可能
  • 任意のReactテーマコンポーネントをスウィズリング可能

このシステムはまた、暗黙的に非常に大きなAPIを形成しています。 Docusaurusを高速に動作できるようにするため、私たちは後方互換性を保証することはできません。

✅ テーマ公開APIには以下のものが含まれます。

ヒント

この公開APIだけでは、サイトのカスタマイズを実現することができない場合があります。

この場合、 カスタマイズのユースケース を報告してください。公開APIを拡張する方法について検討します。

❌ 公開テーマAPIには、次のものは含まれません。

  • DOMの構造
  • ハッシュ接尾辞がつくCSSモジュールのクラス名（通常 [class*='myClassName'] セレクタで対象となるもの）
  • スウィズリングが安全でない、もしくは禁止されているReactコンポーネント
  • @docusaurus/theme-common/internalからインポートされたReactコンポーネント
  • テーマの厳密な視覚的外観
メモ

安全なコンポーネントをスウィズリングするとき、@docusaurus/theme-commonから文書化されていない API を（/internalサブパスなしで）インポートするコンポーネントに出会う場合があります。

私たちは、これらのAPIの後方互換性を維持していますが（それゆえ、それらは「安全」と表記されています）、直接の利用を推奨しているわけではありません。