メインコンテンツにスキップ

リリースプロセス

Docusaurusがどのようにバージョン管理、リリース、および破壊的変更を処理するかを見てみましょう。

情報

このトピックは、特にアップグレードが難しい可能性がある高度にカスタマイズされたサイトにとって重要です。

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

Docusaurusのバージョン管理は、major.minor.patchスキームに基づいており、セマンティックバージョニングを尊重します。

セマンティックバージョニングを尊重することは、複数の理由で重要です。

  • パブリックAPIのみを使用している限り、簡単なマイナーバージョンアップグレードが保証されます。
  • フロントエンドエコシステムの慣例に従います。
  • 新しいメジャーバージョンは、破壊的変更を徹底的に文書化する機会です。
  • 新しいメジャー/マイナーバージョンは、ブログ記事を通じて新機能を伝える機会です。
注意

Docusaurus 2.0のリリースには非常に長い時間がかかりました。今後は、Docusaurusはより定期的に新しいメジャーバージョンをリリースします。実際には、2〜4か月ごとに新しいメジャーバージョンがリリースされると予想できます。

メジャーバージョン番号は神聖なものではありませんが、それでも破壊的な変更をまとめて、メジャーバージョンを頻繁にリリースすることを避けています。

メジャーバージョン​

majorバージョン番号は、破壊的変更が発生するたびにインクリメントされます。

新しいメジャーバージョンがリリースされるたびに、以下を公開します。

  • 機能のハイライト、メジャーなバグ修正、破壊的変更、およびアップグレード手順を掲載したブログ記事。
  • 詳細な変更履歴エントリ
ヒント

破壊的変更と見なすものを明確に理解するために、パブリックAPIサーフェスセクションをお読みください。

マイナーバージョン​

minorバージョン番号は、後方互換性のある重要な変更が発生するたびにインクリメントされます。

新しいマイナーバージョンがリリースされるたびに、以下を公開します。

  • 機能のハイライトと主要なバグ修正のリストを掲載したブログ記事
  • 詳細な変更履歴エントリ
ヒント

パブリックAPIサーフェスのみを使用している場合は、すぐにアップグレードできるはずです！

パッチバージョン​

patchバージョン番号は、バグ修正リリースでインクリメントされます。

新しいパッチバージョンがリリースされるたびに、以下を公開します。

  • 詳細な変更履歴エントリ

バージョン​

Docusaurusチームは通常、同時に2つのメジャーバージョンに取り組んでいます。

  • Docusaurus 2：docusaurus-v2ブランチにある安定版バージョン
  • Docusaurus 3：mainブランチにある次期バージョン
注意

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

安定版​

安定版（v2、docusaurus-v2）は、ほとんどのDocusaurusユーザーに推奨されます。

次のバージョンに対応できないユーザー向けに、mainからdocusaurus-v2への後方互換性のある機能、バグ、およびセキュリティ修正を定期的にgit cherry-pickでバックポートしています。

情報

新しい安定版がリリースされた後、以前の安定版は主要なセキュリティ問題のみを対象として3か月間のみサポートを受け続けます。それ以外の場合、すべての機能は凍結され、重大でないバグは修正されません。

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

次期バージョン​

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

mainブランチは、コアチームおよび外部からの貢献を含む、すべてのプルリクエストのデフォルトターゲットブランチです。

このバージョンは、最新のDocusaurus機能をできるだけ早く使用したい早期導入者に推奨されます。バグを報告したり、フィードバックを提供したりして、私たちを助けるのにも良い方法です。

次期バージョンを使用するには3つの方法があります。

  • alpha、beta、またはrcプレリリースを使用する
  • 最新のプレリリースの場合は@next npm distタグを使用する
  • 最新の機能を使用する場合はcanaryリリースを使用する
ヒント

次期バージョンは、当社のすべての自動テストに合格しており、Docusaurusサイト自体で使用されています。比較的に安全なので、ぜひ試してみてください。

警告

次期バージョンでは破壊的な変更が発生する可能性があります。詳細なアップグレード手順は、変更履歴とプルリクエストで確認できます。

betaおよびrc（リリース候補）段階では、主要な破壊的変更の導入を避けています。

パブリックAPIサーフェス​

Docusaurusは、セマンティックバージョニングを尊重することを約束します。これは、DocusaurusのパブリックAPIで変更が発生し、後方互換性が損なわれる場合は常に、majorバージョン番号をインクリメントすることを意味します。

ヒント

Docusaurusは、minorバージョン間でパブリックAPIの後方互換性を保証します。内部APIを使用しない限り、minorバージョンアップグレードは簡単であるはずです。

パブリックAPIサーフェスとしてカウントされるものを説明します。

コアパブリックAPI​

✅ 当社のパブリックAPIには以下が含まれます。

  • Docusaurus設定
  • DocusaurusクライアントAPI
  • Docusaurus CLI
  • プリセットオプション
  • プラグインオプション
  • プラグインライフサイクルAPI
  • テーマ設定
  • コアプラグインのルートコンポーネントのprops
  • @docusaurus/types TypeScript型
    • 型をより厳密にする（型チェックが壊れる可能性がある）自由はまだ保持しています。

❌ 当社のパブリックAPIは以下を除外します。

  • Docusaurus設定のfuture
  • experimental_またはunstable_で始まるすべての機能
  • v<MajorVersion>_（v6_ v7_など）で始まるすべての機能
ヒント

テーマ以外のAPIの場合、文書化されたAPIはすべてパブリック（かつ安定）と見なされ、文書化されていないAPIはすべて内部と見なされます。

APIが「安定」であるとは、他の変更を加えることなくDocusaurusインストールのパッチまたはマイナーバージョンをインクリメントした場合、docusaurus startまたはdocusaurus buildを実行してもエラーが発生しないことを意味します。

テーマのパブリックAPI​

Docusaurusには非常に柔軟なテーマシステムがあります。

  • カスタムCSSを使用できます
  • 任意のReactテーマコンポーネントをスウィズルできます

このシステムは、暗黙のうちに非常に大きなAPIサーフェスも作成します。Docusaurusを迅速に移動して改善できるように、後方互換性を保証することはできません。

✅ 当社のテーマのパブリックAPIには以下が含まれます。

ヒント

このパブリックAPIを使用してサイトのカスタマイズを達成できない場合があります。

この場合、カスタマイズのユースケースを報告していただければ、公開APIをどのように拡張するか検討します。

❌ 当社の公開テーマAPIは、以下を除外します。

注意

安全なコンポーネントをスウィズルする場合、@docusaurus/theme-common（/internalサブパスなし）から文書化されていないAPIをインポートするコンポーネントに遭遇する可能性があります。

これらのAPIについては後方互換性を維持していますが（そのため「安全」とマークされています）、直接の使用は推奨しません。