Documenter & semantic versioning

Documenter, like any good Julia package は semantic versioning (SemVer) に従います。そのため、パッケージが現在 v1.x のライフサイクルにあるため、Documenter の変更は、文書化された動作に依存するパッケージの既存の使用を壊すべきではありません。^[1]

しかし、Documenterは比較的複雑であり、破壊的変更が何を構成するのかが時々不明確です。たとえば、HTMLテーマのCSSクラスを変更することは許可されていますか？ユーザーが@raw htmlブロック内のCSSクラスに依存していた場合はどうなりますか？彼らのHTMLが正しくレンダリングされなくなった場合、それは破壊的変更ですか？LaTeXコンパイラを完全に変更することは破壊的変更ですか？それが、pdflatexでのみ機能する機能を使用している数式ブロックのためにどこかでPDFビルドを壊す場合はどうなりますか？

このページは、Documenter SemVerの保証が何であるかおよび何でないかを明確にすることを目的としており、ユーザーへの情報提供と開発者へのガイダンスを兼ねています。

Documenter's API guarantees

以下のAPIおよび動作は変更されないことが保証されています：

• Julia API（公開されたDocumenter関数とその文書化された引数）に関する標準的な約束。要するに、Documenter APIの公開され、文書化された部分のみを使用するmake.jlは常に動作し続けるべきです（つまり、ビルドは完了するべきです）。公開APIにはすべてのエクスポートされた関数と型が含まれますが、それに限定されるわけではありません – マニュアルの「リファレンス」セクションで公開されたJulia APIのリストを参照してください。

• すべての文書化された Documenter の動作。例えば、Documenter が determines remote repository links is documented する方法や、HTML ビルドによって生成されるファイルとその構造。文書化されていないエッジケースの動作は変わる可能性がありますが、文書化されている内容に従ってのみ変わります。

What is not covered by SemVer

原則として、前のセクションでカバーされていないものは、定義上、公開APIの一部ではなく、現在の動作を維持することが保証されていません。

ただし、いくつかのことを明示的に述べる価値があります。特に、現在APIの一部ではないが、将来的に（何らかの形で）追加されるべきものが含まれますが、公開APIとしてコミットする前に慎重な検討が必要です。

• ドキュメンターの内部に何らかの形でフックする場合は常に注意が必要です。これには、追加のビルドステップやレンダラーを追加するなど、内部の明らかに拡張可能な部分にフックすることが含まれます。ここでの長期的な目標は、クリーンなプラグインAPIを作成することですが、現在の内部をそのまま維持することは難しいでしょう。

• 生成されたドキュメントのHTML、TeX、またはファイル構造（明示的に文書化されていない限り）。これにはHTMLテーマのCSSが含まれ、そのためカスタムCSSのオーバーライドはいつでも機能しなくなる可能性があります。ただし、ここには時間とともに文書化されるべき多くの事実上の保証があります（例：カスタムテーマ用）。

• HTML UIの外観や操作感、生成されたPDFは、マイナーバージョンごとに大きく変わる可能性があります。

• 明示的に実験的とマークされたものは、安定性が保証されていません（上記の注意を参照してください）。

Documenter = "~1.X"