多くの依存関係があるシステムでは、新しいパッケージのリリースはすぐに悪夢に変わります。 依存関係が強すぎる場合、すべての依存パッケージのバージョンを更新しないとパッケージを更新できません。 依存関係が緩すぎる場合は、常識のないバージョンで問題が発生します。 「依存関係の地獄」とは、あなたが強すぎるとき、またはその逆の場合であり、あまりにも緩い依存関係では、プロジェクトを簡単かつ安全に開発できません。
この問題の解決策として、バージョン番号を割り当てたり増やしたりする方法を指示する簡単な一連のルールを提案します。 システムが機能するためには、まず最初に、オープンAPIを宣言する必要があります。 シンプルで明確なドキュメントである必要があります。 XYZ形式（Major.Minor.Patch）のバージョン番号を検討してください。
APIに影響を与えないエラーを修正する場合、パッチバージョンが増加します。 後方互換性を維持しながらAPIを追加または変更すると、マイナーバージョンが増加します。 後方互換性を維持せずにAPIを変更すると、メジャーバージョンが増加します。
このシステムを「セマンティックバージョニング」と呼びます。 このスキームによれば、バージョン番号とその変更方法は、メインコードと、バージョンからバージョンへの変更方法を意味します。
セマンティックバージョニング仕様
キーワード「MUST」、「MUST NOT」、「SHOULD」、「SHOULD NOT」、「MAY」は、このドキュメントのRFCに従って解釈する必要があります2119。
- セマンティックバージョニングを使用するソフトウェア製品には、オープンAPIが必要です。 このAPIは、コード内またはアプリケーションドキュメントで宣言する必要があります。 APIは正確かつ包括的なものでなければなりません。
- バージョン番号は、XYZで構成されている必要があります。X、Y、およびZは正の数です。 Xはメジャーバージョン、Yはマイナーバージョン、Zはパッチバージョンです。 各要素は1ずつ増加する必要があります。 例：1.9.0-> 1.10.0-> 1.11.0
- メジャーバージョンが増えると、マイナーバージョンとパッチバージョンをリセットする必要があります。 マイナーバージョンがインクリメントされると、パッチバージョンをゼロにリセットする必要があります。 例：1.1.3-> 2.0.0および2.1.7-> 2.2.0。
- パッケージバージョンがリリースされた後、このパッケージに変更を加えないでください。 すべての変更は、新しいバージョンでリリースする必要があります。
- 開発の初期段階では、メジャーバージョンはゼロ（0.yz）です。 この期間中、いつでも何かが変わる可能性があります。 オープンAPIは安定していると見なしてはなりません。
- バージョン1.0.0は、オープンAPIを定義しています。 バージョン番号の変更方法は、このオープンAPIによって異なります。
- パッチバージョンZ（xyZ | x> 0）は、バグ修正に以前のバージョンとの下位互換性がある場合にのみ増やす必要があります。 バグ修正により、不正な動作が排除されます。
- 修正が以前のバージョンと互換性がある場合、マイナーバージョンY（xYz | x> 0）を増やす必要があります。 API要素が非推奨としてマークされている場合は、マイナーバージョンを増やす必要があります。 マイナーバージョンは、重要な新機能または拡張機能でアップグレードされる場合があります。 マイナーバージョンには、パッチバージョンへの変更が含まれる場合があります。 マイナーバージョンが変更されたら、パッチバージョンをリセットする必要があります。
- 以前のバージョンと互換性のない修正が行われた場合、メジャーバージョンX（Xyz | X> 0）を増やす必要があります。 メジャーバージョンには、マイナーバージョンおよびパッチバージョンへの変更が含まれる場合があります。 メジャーバージョンが変更された場合、パッチとマイナーバージョンをリセットする必要があります。
- 予備バージョンは、パッチバージョンの直後にピリオドで区切られたダッシュと識別子で示される場合があります。 識別子には文字[0-9A-Za-z-]を含める必要があります。 プレビューバージョンは、同じ通常バージョンよりも優先順位が低くなっています。 例：1.0.0-alpha、1.0.0-alpha.1、1.0.0-0.3.7、1.0.0-x.7.z.92。
- ビルドバージョンは、パッチまたはプレリリースバージョンの直後にプラス記号とドット区切りの識別子で示される場合があります。 識別子には文字[0-9A-Za-z-]を含める必要があります。 ビルドバージョンは、同じ通常バージョンよりも優先されます。
例：1.0.0 + build.1、1.3.7 + build.11.e0f985a。 - 優先度は、メジャー、マイナー、パッチ、予備、ビルドの各バージョンに分けて計算する必要があります。 メジャー、マイナー、パッチのバージョンには常に数字が含まれます。 予備バージョンとアセンブリバージョンは、ドットで区切られた各識別子を次の方法で比較することによって並べ替える必要があります。
ASCIIで。 数値識別子は、常にアルファベット識別子よりも優先度が低くなります。 例：1.0.0-alpha <1.0.0-alpha.1 <1.0.0-beta.2 <1.0.0-beta.11 <1.0.0-rc.1 <1.0.0-rc.1 + build。 1 <1.0.0 <1.0.0 + 0.3.7 <1.3.7 +ビルド<1.3.7 + build.2.b8f12d7 <1.3.7 + build.11.e0f985a
セマンティックバージョニングを使用する理由
これは新しいアイデアでも革新的なアイデアでもありません。 実際、おそらくあなたはすでに似たようなことをしたでしょう。 問題は、「類似」では十分ではないということです。 正式な仕様がなければ、バージョン番号は依存関係の管理には本質的に役に立ちません。 明確で合理的な柔軟性のある定義を与え、
製品とのユーザーインタラクションを促進します。
セマンティックバージョニングが依存関係の地獄を回避する方法を示す簡単な例。 「Firetruck」というライブラリを検討してください。 彼女はラダーと呼ばれるパッケージにはまっています。 消防車が作成されたとき、ラダーのバージョンは3.1.0でした。 Firetruckは3.1.0で導入されたさまざまな方法を使用するため、ラダーを3.1.0より大きく4.0.0より小さいバージョンに安全にアップグレードできます。 Ladderバージョン3.1.1および3.2.0が利用可能になったので、それらにアップグレードして、既存のソフトウェアと互換性があることを確認できます。
責任ある開発者として、パッケージの互換性を確認する必要があります。 現実は残酷で、私たちはそれで何もできません。 私たちにできることは、Semantic Versioningにパッケージを更新する簡単な方法を提供することです。 それはあなたの時間と神経を節約します。
セマンティックバージョニングのアイデアが気に入った場合は、ここで概説したルールに従う必要があります。 プロジェクトのREADMEファイルにこのドキュメントへのリンクを配置すると、同僚や製品を使用している人たちもセマンティックバージョンコントロールに従うことができます。
よくある質問
初期段階0.yzでバージョン番号を変更するにはどうすればよいですか？
最も簡単な方法は、バージョン0.1.0から開始し、その後の各リリースのバージョン番号を増やすことです。
バージョン1.0.0にアップグレードする時期を知る方法は？
製品がエンドユーザーによって使用され始めた場合、バージョン1.0.0が必要です。 安定したオープンAPIがある場合は、1.0.0にアップグレードする必要があります。 後方互換性が心配な場合は、1.0.0にアップグレードする必要があります。
これは、迅速な開発と迅速な反復を妨げませんか？
ゼロメジャーバージョン、それで十分です。 オープンAPIが毎日変更される場合は、バージョン0.xxであるか、次のメジャーバージョンで作業する必要があります。
わずかな変更でも下位互換性がない場合、すぐにバージョン42.0.0になりますか？
これは責任ある開発と先見性の問題です。 多くの依存関係があるコードでは、小さなバッチで互換性のない変更を加えないでください。 アップグレードコストが高すぎる可能性があります。
APIのドキュメントは手間がかかりすぎます！
他の人が使用することを目的とした製品を作成するプロの開発者として、あなたの責任です。 ソフトウェア管理は、プロジェクトのパフォーマンスを維持するための複雑で非常に重要な部分です。
誤ってメジャーではなくマイナーバージョンを指定した場合はどうすればよいですか？
セマンティックバージョニングが壊れていることを理解したら、問題を修正し、問題を修正して下位互換性を復元する新しいバージョンをリリースする必要があります。
オープンAPIを変更せずに内部依存関係を更新する場合はどうすればよいですか？
これは、オープンAPIに影響を与えない場合に受け入れられます。 パッケージに明らかに依存する製品には、独自の依存関係仕様が必要であり、作成者は競合に気付くでしょう。
古い機能をマークするにはどうすればよいですか？
時代遅れの機能、これは正常であり、しばしば前進するためにそれに頼らなければなりません。 オープンAPIの古い部分としてマークする場合、2つのことを行う必要があります：（1）ドキュメントを更新する、（2）ユーザーがスムーズに再構築できるように、新しい機能と古い機能の両方をサポートする少なくとも1つのリリースをリリースする
著者について
投稿者：Semantic Version Control Tom Preston-Werner 、Gravatarsの作成者およびGitHubの共同設立者。
質問や提案を表現するには、GitHubで質問を作成します 。
githubのこの翻訳
免許
クリエイティブコモンズ-CC BY 3.0
http://creativecommons.org/licenses/by/3.0/