web-dev-qa-db-ja.com

ドキュメントを更新するときに、semverでパッチバージョンを使用しても大丈夫ですか?

たとえば、どうやってsemverを使用するときにソースファイルにドキュメントがないライブラリの1.0をリリースしたばかりで、クラ​​スにJavaDocがないことに気づきました。PATCHバージョンをリリースしても大丈夫ですか? semverの定義を読みましたが、そのトピックについて何も見つかりませんでした

3
roookeee

それはケースに依存し、あなたの個人的な判断にもある程度依存します:

  • パブリックAPIドキュメントをパッケージに追加または変更すると、パッケージの内容が変更されるため、新しいバージョンを作成する必要があります- SemVer spec のルール3を参照してください。

  • ドキュメントの変更のみによってAPIが破損したり、他の重大な変更が導入されたりすることはありません。そのため、メジャーバージョン番号を変更する必要はありません。

  • しかし、新しいドキュメントは既存の機能を追加または変更しますか? Semver仕様のルール7は次のように述べています。

    マイナーバージョンY(x.Y.z | x> 0)は、新しい、下位互換性のある機能がパブリックAPIに導入されている場合はインクリメントする必要があります。

だから、あなたが言及したクラスの欠落しているドキュメントがあなたのライブラリのユーザーにとって何を意味するかを考えてください:

  • 不足しているドキュメントの重要性が低く、クラスのユーザーがクラスの名前、パブリックメンバーの名前、およびコンテキストからクラスの正しい意味を推測できる場合は、PATCH番号のみを増やすことをお勧めします。この場合、ドキュメントの追加はバグ修正と解釈できます(Semverのルール6を参照)。

  • 不足しているドキュメントが、ドキュメントなしではほとんど使用できない機能全体を覆っている場合は、マイナーバージョン番号(PATCH番号だけでなく)を増やすことをお勧めします。ここで、新しいドキュメントは確かにパブリックAPIに機能を導入できます

実際には、状況はそれほど白黒ではない可能性があるので、状況が前者または後者のカテゴリに適している場合は、常識を使用している可能性があります。

5
Doc Brown