Added latest version of submission
This commit is contained in:
parent
2bfa091eb8
commit
0c87f14be6
GPG key ID:
AD914585C9406B6A
4 changed files with 417 additions and 262 deletions
3
.gitignore
vendored
3
.gitignore
vendored
|
|
@ -1,3 +0,0 @@
|
|||
index.html
|
||||
*.html
|
||||
ledger.svg
|
||||
3
build.sh
3
build.sh
|
|
@ -1,3 +0,0 @@
|
|||
#!/bin/sh
|
||||
rm -rf index.html
|
||||
docker run --rm -v $(pwd):/data cleverthis/bikeshed:latest bikeshed spec /data/index.bs /data/index.html
|
||||
417
clever_semantic_versioning.html
Normal file
417
clever_semantic_versioning.html
Normal file
|
|
@ -0,0 +1,417 @@
|
|||
<!DOCTYPE html>
|
||||
|
||||
<html dir="ltr" lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8"/>
|
||||
<meta content="width=device-width, initial-scale=1, shrink-to-fit=no" name="viewport"/>
|
||||
<title>Clever Semantic Versioning</title>
|
||||
<link href="https://www.w3.org/submissions/2024/SUBM-semantic-versioning-20241127/" rel="canonical"/>
|
||||
<link href="https://www.w3.org/StyleSheets/TR/2021/W3C-Member-SUBM" rel="stylesheet"/>
|
||||
</head>
|
||||
<body class="h-entry">
|
||||
<div class="head">
|
||||
<p class="logos">
|
||||
<a class="logo" href="https://www.w3.org/"><img alt="W3C" crossorigin="" height="48" src="https://www.w3.org/StyleSheets/TR/2021/logos/W3C" width="72"/>
|
||||
</a>
|
||||
<a class="logo" href="https://www.w3.org/submissions/"><img alt="W3C Member Submission" crossorigin="" height="48" src="https://www.w3.org/Icons/member_subm.png" width="211"/>
|
||||
</a>
|
||||
</p>
|
||||
<h1 class="title" id="title">Clever Semantic Versioning</h1>
|
||||
<p id="w3c-state"><a href="https://www.w3.org/standards/types#SUBM">W3C Member Submission</a> <time class="dt-published" datetime="2024-11-27">27 November 2024</time></p>
|
||||
<details open="">
|
||||
<summary>More details about this document</summary>
|
||||
<dl>
|
||||
<dt>This version:</dt>
|
||||
<dd>
|
||||
<a class="u-url" href="https://www.w3.org/submissions/2024/SUBM-semantic-versioning-20241127/">https://www.w3.org/submissions/2024/SUBM-semantic-versioning-20241127/</a>
|
||||
</dd>
|
||||
<dt>Latest published version:</dt>
|
||||
<dd>
|
||||
<a href="https://www.w3.org/submissions/semantic-versioning/">https://www.w3.org/submissions/semantic-versioning/</a>
|
||||
</dd>
|
||||
<dt class="editor">Editor:
|
||||
</dt>
|
||||
<dd class="editor p-author h-card vcard"><a class="p-name fn u-url url" href="https://JeffreyFreeman.me">Jeffrey Phillips Freeman</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Jeffrey.Freeman@CleverThis.com">Jeffrey.Freeman@CleverThis.com</a>
|
||||
</dd><dt>Author:
|
||||
</dt>
|
||||
<dd><a class="p-name fn u-url url" href="https://JeffreyFreeman.me">Jeffrey Phillips Freeman</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Jeffrey.Freeman@CleverThis.com">Jeffrey.Freeman@CleverThis.com</a>
|
||||
</dd>
|
||||
<dd><a class="p-name fn u-url url" href="https://Kyle.Hird.u.CleverThis.com">Kyle Hird</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Kyle.Hird@CleverThis.com">Kyle.Hird@CleverThis.com</a>
|
||||
</dd><dt>Contributor:
|
||||
</dt>
|
||||
<dd><a class="p-name fn u-url url" href="https://JeffreyFreeman.me">Jeffrey Phillips Freeman</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Jeffrey.Freeman@CleverThis.com">Jeffrey.Freeman@CleverThis.com</a>
|
||||
</dd>
|
||||
<dd><a class="p-name fn u-url url" href="https://Kyle.Hird.u.CleverThis.com">Kyle Hird</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Kyle.Hird@CleverThis.com">Kyle.Hird@CleverThis.com</a>
|
||||
</dd>
|
||||
<dd><a class="p-name fn u-url url" href="https://Brent.Edwards.u.CleverThis.com">Brent Edwards</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Brent.Edwards@CleverThis.com">Brent.Edwards@CleverThis.com</a>
|
||||
</dd>
|
||||
<dd><a class="p-name fn u-url url" href="https://Rui.Hu.u.CleverThis.com">Rui Hu</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Rui.Hu@CleverThis.com">Rui.Hu@CleverThis.com</a>
|
||||
</dd>
|
||||
<dd><a class="p-name fn u-url url" href="https://Stanislav.Hejny.u.CleverThis.com">Stanislav Hejny</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Stanislav.Hejny@CleverThis.com">Stanislav.Hejny@CleverThis.com</a>
|
||||
</dd>
|
||||
<dd><a class="p-name fn u-url url" href="https://Luis.Mendes.u.CleverThis.com">Luis Mendes</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Luis.Mendes@CleverThis.com">Luis.Mendes@CleverThis.com</a>
|
||||
</dd>
|
||||
<dd><a class="p-name fn u-url url" href="https://Madeline.Pace.u.CleverThis.com">Madeline Pace</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:madeline.pace@CleverThis.com">madeline.pace@CleverThis.com</a>
|
||||
</dd>
|
||||
<dd><a class="p-name fn u-url url" href="https://Josi.Rosenfeld.u.CleverThis.com">Josi Rosenfeld</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Josi.Rosenfeld@CleverThis.com">Josi.Rosenfeld@CleverThis.com</a>
|
||||
</dd>
|
||||
<dd><a class="p-name fn u-url url" href="https://Bilal.Benmahria.u.CleverThis.com">Bilal Ben Mahria</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Bilal.Benmahria@CleverThis.com">Bilal.Benmahria@CleverThis.com</a>
|
||||
</dd>
|
||||
<dd><a class="p-name fn u-url url" href="https://Hamza.Khyari.u.CleverThis.com">Hamza Khyari</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Hamza.Khyari@CleverThis.com">Hamza.Khyari@CleverThis.com</a>
|
||||
</dd>
|
||||
<dd><a class="p-name fn u-url url" href="https://Aditya.Chhabra.u.CleverThis.com">Aditya Chhabra</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Aditya.Chhabra@CleverThis.com">Aditya.Chhabra@CleverThis.com</a>
|
||||
</dd>
|
||||
<dd><a class="p-name fn u-url url" href="https://Adnaan.Nazir.u.CleverThis.com">Adnaan Nazir</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Adnaan.Nazir@CleverThis.com">Adnaan.Nazir@CleverThis.com</a>
|
||||
</dd>
|
||||
<dd><a class="p-name fn u-url url" href="https://Aleena.Umair.u.CleverThis.com">Aleena Umair</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Aleena.Umair@CleverThis.com">Aleena.Umair@CleverThis.com</a>
|
||||
</dd>
|
||||
<dd><a class="p-name fn u-url url" href="https://Eugen.Thaci.u.CleverThis.com">Eugen Thaci</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Eugen.Thaci@CleverThis.com">Eugen.Thaci@CleverThis.com</a>
|
||||
</dd>
|
||||
<dt>Feedback:</dt>
|
||||
<dd>
|
||||
<a href="https://git.cleverthis.com/cleverthis/semantic-versioning/semantic-versioning">GitLab Clever</a> (
|
||||
<a href="https://git.cleverthis.com/cleverthis/semantic-versioning/semantic-versioning/-/merge_requests">pull requests</a>,
|
||||
<a href="https://git.cleverthis.com/cleverthis/semantic-versioning/semantic-versioning/-/issues/new">new issue</a>,
|
||||
<a href="https://git.cleverthis.com/cleverthis/semantic-versioning/semantic-versioning/-/issues">open issues</a>)
|
||||
</dd>
|
||||
</dl>
|
||||
</details>
|
||||
<p class="copyright" data-fill-with="copyright"><a href="https://www.w3.org/policies/#copyright">Copyright</a> © 2024
|
||||
<a href="https://www.CleverThis.com">CleverThis, Inc.</a>.
|
||||
<abbr title="CleverThis, Inc.">CleverThis</abbr><sup>®</sup>
|
||||
<a href="https://www.w3.org/policies/#Legal_Disclaimer">liability</a>,
|
||||
<a href="https://www.w3.org/policies/#W3C_Trademarks">trademark</a> and
|
||||
<a href="https://www.w3.org/copyright/document-license/" rel="license" title="W3C Document License">W3C Document License</a> rules apply.<br/>
|
||||
|
||||
<a href="http://creativecommons.org/licenses/by-sa/4.0/" rel="license"><img alt="CC0" src="https://licensebuttons.net/l/by-sa/4.0/80x15.png" width="80" height="15"></a>
|
||||
In addition, as of March 1, 2024, the editors have made this specification available under the
|
||||
<a href="http://creativecommons.org/licenses/by-sa/4.0/" rel="license">CC BY-SA 4.0</a>,
|
||||
which is available at http://creativecommons.org/licenses/by-sa/4.0/. Parts of this work may be from another specification document. If so, those parts are instead cov>
|
||||
</p>
|
||||
<hr title="Separator for header"/>
|
||||
</div>
|
||||
<section class="introductory" id="abstract">
|
||||
<h2>Abstract</h2>
|
||||
<p>
|
||||
Clever Semantic Versioning is a specification for versioning software and related artifacts. It ensures versions are predictable and meaningful by adding semantics to versioning. Unlike the widely known specification at SemVer.org, it extends versioning beyond APIs, refining its scope to address gaps and ambiguities, making it more suited to modern development workflows.
|
||||
</p>
|
||||
</section>
|
||||
<section>
|
||||
<h2>Status of This Document</h2>
|
||||
<p><em>This section describes the status of this
|
||||
document at the time of its publication. A list of current <abbr title="World Wide Web Consortium">W3C</abbr>
|
||||
publications can be found
|
||||
in the <a href="https://www.w3.org/TR/"><abbr title="World Wide Web Consortium">W3C</abbr> technical reports index</a> at
|
||||
https://www.w3.org/TR/.</em></p>
|
||||
<p>
|
||||
By publishing this document, <abbr title="World Wide Web Consortium">W3C</abbr> acknowledges that the
|
||||
<a href="https://www.w3.org/submissions/2024/SUBM-semantic-versioning-20241127/">Submitting Members</a> have made a formal Submission request to <abbr title="World Wide Web Consortium">W3C</abbr> for discussion. Publication of this document by
|
||||
<abbr title="World Wide Web Consortium">W3C</abbr> indicates no endorsement of its content by <abbr title="World Wide Web Consortium">W3C</abbr>, nor that <abbr title="World Wide Web Consortium">W3C</abbr> has, is, or will be allocating any resources to the issues addressed by it. This document is not the product of a chartered <abbr title="World Wide Web Consortium">W3C</abbr> group, but is published as potential input to the
|
||||
<a href="https://www.w3.org/policies/process/"><abbr title="World Wide Web Consortium">W3C</abbr> Process</a>. A
|
||||
<a href="https://www.w3.org/submissions/2024/02/Comment/"><abbr title="World Wide Web Consortium">W3C</abbr> Team Comment</a> has been published in conjunction with this Member Submission. Publication of acknowledged Member Submissions at the <abbr title="World Wide Web Consortium">W3C</abbr> site is one of the benefits of
|
||||
<a href="https://www.w3.org/Consortium/Prospectus/Joining">
|
||||
<abbr title="World Wide Web Consortium">W3C</abbr> Membership</a>. Please consult the requirements associated with Member Submissions of
|
||||
<a href="https://www.w3.org/policies/patent-policy/#sec-submissions">section 3.3 of the <abbr title="World Wide Web Consortium">W3C</abbr> Patent Policy</a>. Please consult the complete
|
||||
<a href="https://www.w3.org/submissions/">list of acknowledged <abbr title="World Wide Web Consortium">W3C</abbr> Member Submissions</a>.
|
||||
</p>
|
||||
</section>
|
||||
<nav id="toc">
|
||||
<h2 class="introductory" id="table-of-contents">Table of Contents</h2>
|
||||
<ol class="toc" role="directory">
|
||||
<li><a href="#overview"><span class="secno">1</span> <span class="content">Overview</span></a>
|
||||
<li><a href="#semantic-versioning-specification"><span class="secno">2</span> <span class="content">Clever Semantic Versioning Specification</span></a>
|
||||
<ol class="toc">
|
||||
<li><a href="#version-classes"><span class="secno">2.1</span> <span class="content">Version Classes</span></a>
|
||||
<ol class="toc">
|
||||
<li><a href="#api-versioning"><span class="secno">2.1.1</span> <span class="content">API Versioning</span></a>
|
||||
<li><a href="#ui-versioning"><span class="secno">2.1.2</span> <span class="content">UI Versioning</span></a>
|
||||
<li><a href="#dataset-versioning"><span class="secno">2.1.3</span> <span class="content">Dataset Versioning</span></a>
|
||||
<li><a href="#schema-versioning"><span class="secno">2.1.4</span> <span class="content">Schema Versioning</span></a>
|
||||
<li><a href="#hybrid-versioning"><span class="secno">2.1.5</span> <span class="content">Hybrid Versioning</span></a>
|
||||
</ol>
|
||||
<li><a href="#dependent-artifact-versioning"><span class="secno">2.2</span> <span class="content">Dependent Artifact Versioning</span></a>
|
||||
<li><a href="#backus"><span class="secno"><strong>3</strong></span> <span class="content"><strong>Backus-Naur Form</strong></span></a>
|
||||
<li><a href="#acknowledgments"><span class="secno"><strong>4</strong></span> <span class="content"><strong>Acknowledgments</strong></span></a>
|
||||
<!--
|
||||
<li><a href="#conformance"><span class="secno"></span> <span class="content"> Conformance</span></a>
|
||||
<li><a href="#references"><span class="secno"></span> <span class="content">References</span></a>
|
||||
<ol class="toc">
|
||||
<li><a href="#normative"><span class="secno"></span> <span class="content">Normative References</span></a>
|
||||
</ol>
|
||||
-->
|
||||
</ol>
|
||||
</ol>
|
||||
</nav>
|
||||
|
||||
<h2 class="heading settled" data-level="1" id="overview"><span class="secno">1. </span><span class="content">Overview</span><a class="self-link" href="#overview"></a></h2>
|
||||
|
||||
<p>Given a version number MAJOR.MINOR.PATCH-EXTRA+META, increment the: </p><ol>
|
||||
<li data-md="">
|
||||
<p><em>MAJOR</em> when making backward incompatible changes </p>
|
||||
<li data-md="">
|
||||
<p><em>MINOR</em> when adding functionality in a backward compatible manner.</p>
|
||||
<li data-md="">
|
||||
<p><em>PATCH</em> when making backward compatible bug fixes.</p>
|
||||
<li data-md="">
|
||||
<p><em>EXTRA</em> for pre-releases or other additional versioning parameters.</p>
|
||||
</li></ol><div class="note" role="note">The EXTRA version follows a natural ordering (specified below) and <em>MAY</em> contain alphanumeric characters, dots, and additional dashes.</div>
|
||||
<div class="note" role="note"> The META version consists of metadata, which is non-ordered and does not increment. </div>
|
||||
|
||||
<h2 class="heading settled" data-level="2" id="semantic-versioning-specification"><span class="secno">2. </span><span class="content">Clever Semantic Versioning Specification</span><a class="self-link" href="#semantic-versioning-specification"></a></h2><section id="bnf-grammar">
|
||||
<div class="container"></div>
|
||||
</section><p>The key words "<em>MUST</em>", "<em>MUST NOT</em>", "<em>REQUIRED</em>", "<em>SHALL</em>", "<em>SHALL NOT</em>", "<em>SHOULD</em>","<em>SHOULD NOT</em>", "<em>RECOMMENDED</em>","<em>NOT RECOMMENDED</em>", "<em>MAY</em>", and "<em>OPTIONAL</em>" in this document are to be interpreted as described in <a href="https://www.rfc-editor.org/info/bcp14">BCP 14</a> <a href="https://datatracker.ietf.org/doc/html/rfc2119">[RFC2119]</a> <a href="https://datatracker.ietf.org/doc/html/rfc8174">[RFC8174]</a> when, and only when, they appear in all capitals, as shown here.</p><ol class="algorithm">
|
||||
<li>A normal version number <em>MUST</em> take the form <code>X.Y.Z</code> where <code>X</code>, <code>Y</code>, and <code>Z</code> are non-negative integers, and <em>MUST NOT</em> contain leading zeroes. <code>X</code> is the major version, <code>Y</code> is the minor version, and <code>Z</code> is the patch version. <code>X</code>, <code>Y</code>, and <code>Z</code> <em>MUST</em> be representable in a thirty-two-bit unsigned integer, i.e. strictly less than 4,294,967,296.
|
||||
<li>Once a versioned package has been released, the contents of that version <em>MUST NOT</em> be modified. Any modifications <em>MUST</em> be released as a new version.
|
||||
<li>Major version zero <code>(0.y.z)</code> is for initial development. Anything <em>MAY</em> change at any time. The artifact <em>SHOULD NOT</em> be considered stable.
|
||||
<li>Version <code>1.0.0</code> defines the artifact. The way in which the version number is incremented after this release is dependent on the version class of the component.
|
||||
<li>Patch version <code>Z</code> <code>(x.y.Z | x > 0)</code> <em>MUST</em> be incremented if only backward compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect documented behavior or improves performance characteristics while adding no new functionality.
|
||||
<li>Minor version <code>Y</code> <code>(x.Y.z | x > 0)</code> <em>MUST</em> be incremented if new, backward compatible functionality is introduced to the component. It <em>MUST</em> be incremented if any public functionality is marked as deprecated and it <em>MUST</em> be incremented if new functionality is exposed publicly through the versioned component. It <em>MAY</em> include patch level changes. Patch version <em>MUST</em> be reset to 0 when minor version is incremented. The minor version <em>MUST NOT</em> increment if the major version is eligible to be incremented at this time.
|
||||
<li>Major version <code>X</code> <code>(X.y.z | X > 0)</code> <em>MUST</em> be incremented if any backward incompatible changes are introduced to the component being versioned. It <em>MAY</em> also include minor and patch and minor level changes. Patch and minor versions <em>MUST</em> be reset to 0 when major version is incremented.
|
||||
<li>Extra version <em>MAY</em> be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers <em>MUST</em> comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers <em>MUST NOT</em> be empty. Numeric identifiers <em>MUST NOT</em> include leading zeroes. Extra versions have a lower precedence than the associated normal version. An extra version containing only purely numeric identifiers represents a subversion and will follow the same format and rules as a normal version (see dependent version class below). Any other extra version indicates a pre-release and that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version.
|
||||
<li>Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or extra version. Identifiers <em>MUST</em> comprise only ASCII alphanumerics and hyphens <code>[0-9A-Za-z-]</code>. Identifiers <em>MUST NOT</em> be empty. Build metadata <em>MUST</em> be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence.
|
||||
<li>A version number <em>MUST</em> be no longer than 255 characters, including extra version and build metadata.
|
||||
<li>Precedence refers to how versions are compared to each other when ordered.
|
||||
<ol>
|
||||
<li>Precedence <em>MUST</em> be calculated by separating the version into major, minor, patch and extra identifiers in that order (Build metadata does not figure into precedence).
|
||||
<li>Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Major, minor, and patch versions are always compared numerically.
|
||||
<li>When major, minor, and patch are equal, an extra version has lower precedence than a normal version.
|
||||
<li>Precedence for two extra versions with the same major, minor, and patch version <em>MUST</em> be determined by comparing each dot separated identifier from left to right until a difference is found as follows:
|
||||
<ol>
|
||||
<li>Identifiers consisting of only digits are compared numerically.
|
||||
<li>Identifiers with letters or hyphens are compared lexically in ASCII sort order.
|
||||
<li>Numeric identifiers always have lower precedence than non-numeric identifiers.
|
||||
<li>A larger set of extra identifiers fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal.
|
||||
</ol>
|
||||
</ol>
|
||||
<li>Select the subcategory below that best describes the artifact. They are ordered in descending priority, so pick the first category that matches your software type.
|
||||
</ol><div class="example" id="example-0b4ebba9">
|
||||
<a class="self-link" href="#example-0b4ebba9"></a> Example versions without the optional EXTRA or META components:
|
||||
<p><code>1.9.0</code>, <code>1.10.0</code>, <code>1.11.0</code></p>
|
||||
</div><div class="example" id="example-6ad88135">
|
||||
<a class="self-link" href="#example-6ad88135"></a> Example versions utilizing the optional EXTRA component but without META:
|
||||
<p><code>1.0.0-alpha</code>, <code>1.0.0-alpha.1</code>, <code>1.0.0-0.3.7</code>, <code>1.0.0-x.7.z.92</code>, <code>1.0.0-x-y-z</code></p>
|
||||
</div><div class="example" id="example-e4a8ca33">
|
||||
<a class="self-link" href="#example-e4a8ca33"></a> Example versions utilizing the optional EXTRA and META components:
|
||||
<p><code>1.0.0-alpha+001</code>, <code>1.0.0+20130313144700</code>, <code>1.0.0-beta+exp.sha.5114f85</code>, <code>1.0.0+21AF26D3117B344092BD</code></p>
|
||||
</div><div class="example" id="example-2c118789">
|
||||
<a class="self-link" href="#example-2c118789"></a> Example version precedence:
|
||||
<p><code>1.0.0-alpha</code> < <code>1.0.0-alpha.1</code> < <code>1.0.0-alpha.beta</code> < <code>1.0.0-beta</code> < <code>1.0.0-beta.2</code> < <code>1.0.0-beta.11</code> < <code>1.0.0-rc.1</code> < <code>1.0.0</code> < <code>2.0.0-alpha</code> < <code>2.0.0</code> < <code>2.1.0</code> < <code>2.1.1</code></p>
|
||||
</div><h3 class="heading settled" data-level="2.1" id="version-classes"><span class="secno">2.1. </span><span class="content">Version Classes</span><a class="self-link" href="#version-classes"></a></h3><p>While the general meaning of a PATCH, MINOR, and MAJOR version are defined in the specification above the specific interpretation is not always clear depending on the class of resources you happen to be versioning. An API, Schema, or even an application would all interpret when to increment a version a bit differently. Therefore we have tried to define explicitly versioning rules for the various classes of resources of interest. Any class not covered in this specification is technically not covered by it, but it is still recommended that the general principles outlined in the specification above be adhered to when possible.</p>
|
||||
<div class="advisement"> When picking a version class we only care about <strong>exposed</strong> components. Internal APIs, internal data, and dependencies <em>SHOULD NOT</em> affect versioning. The exposed components being versioned, and the versioning class being used, <em>SHOULD</em> always be explicitly stated by the project owners. </div>
|
||||
<p>When an artifact covers several exposed components that are either of different versioning classes, or just make sense to version separately then they <em>SHOULD</em> always be versioned separately. The overall artifact version can be determined by the hybrid versioning class mentioned below.</p>
|
||||
<h4 class="heading settled" data-level="2.1.1" id="api-versioning"><span class="secno">2.1.1. </span><span class="content">API Versioning</span><a class="self-link" href="#api-versioning"></a></h4>
|
||||
<p>When versioning software with a public API such as libraries, and web endpoints it <em>MUST</em> match the following criteria:</p>
|
||||
<ol>
|
||||
<li data-md="">
|
||||
<p>The resource <em>MUST</em> declare a public API.</p>
|
||||
<li data-md="">
|
||||
<p>The API <em>MUST</em> be declared as code or specification documentation.</p>
|
||||
</ol>
|
||||
<p>For any artifact of this type the meaning of incrementing the components of a version are as follows:</p>
|
||||
<ul>
|
||||
<li data-md="">
|
||||
<p><em>PATCH</em> - An internal fix to bring behavior in compliance with the documented expected behavior for the public API; this <em>SHOULD NOT</em> implement changes to the public API signatures.</p>
|
||||
<li data-md="">
|
||||
<p><em>MINOR</em> -If new functionality is added to the public API in a backward compatible way, including new information in return values. <mar>k Additionally, if any public functionality is marked as deprecated, but remains available to maintain backward compatibility, the MINOR version <em>MUST</em> be incremented.</p>
|
||||
<li data-md="">
|
||||
<p><em>MAJOR</em> - Any change to the public API that breaks backward compatibility.</p>
|
||||
</ul>
|
||||
<p>This specification guarantees backward compatibility with <a href="https://semver.org/">SemVer.org</a> version 2.0 and only version 2.0. However, forward compatibility with future versions is not guaranteed. Implementers <em>SHOULD</em> ensure their systems are designed with this limitation in mind.</p>
|
||||
<h4 class="heading settled" data-level="2.1.2" id="ui-versioning"><span class="secno">2.1.2. </span><span class="content">UI Versioning</span><a class="self-link" href="#ui-versioning"></a></h4><p>When versioning User Interfaces which <em>MAY</em> have any nature of input whether it be command-line, GUI, or some other interface, the following paradigm <em>SHOULD</em> be used. The following criteria <em>MUST</em> be satisfied:</p><ol>
|
||||
<li data-md="">
|
||||
<p>The resource <em>MUST</em> have a user interface of some kind, of which both command-line and GUI are acceptable.</p>
|
||||
</ol><p>For any artifact of this type the meaning of incrementing the components of a version are as follows:</p><ul>
|
||||
<li data-md="">
|
||||
<p><em>PATCH</em> - An internal fix to bring behavior in compliance with the documented expected behavior for the UI; this <em>SHOULD</em> implement no changes to the user interface of any kind.</p>
|
||||
<li data-md="">
|
||||
<p><em>MINOR</em> - Any backward compatible changes to the UI. Backward compatible means while new entries and elements can be added the existing ones <em>SHOULD</em> retain their same name, exist somewhere within the same menu items and menu structure, and behave consistently as they have in the past (or fixed according to the documented and expected behavior). This applies to all language variants of the interface.</p>
|
||||
<li data-md="">
|
||||
<p><em>MAJOR</em> - Any change to any of the interface in any language, that breaks backward compatibility.</p>
|
||||
</ul><h4 class="heading settled" data-level="2.1.3" id="dataset-versioning"><span class="secno">2.1.3. </span><span class="content">Dataset Versioning</span><a class="self-link" href="#dataset-versioning"></a></h4><p> When versioning datasets, the schema (see <a href="#schema-versioning">Schema Versioning</a> below) <em>MAY</em> be versioned alongside the dataset or separately. A dataset <em>MAY</em> include such things as a RDBMS database, a Semantic Web Knowledge Graph, or an XML file. Such Datasets <em>MUST</em> describe the following:</p><ol>
|
||||
<li data-md="">
|
||||
<p>Public structured data for which access is being provided.</p>
|
||||
</ol><p>For any artifact of this type the meaning of incrementing the components of a version are as follows:</p><div class="advisement"> Anytime the underlying schema experiences an increase in any of its version's parts then the dataset <em>MUST</em> at least increment its version corresponding part, or a more significant part. </div><ul>
|
||||
<li data-md="">
|
||||
<p><em>PATCH</em> - Additional rows / instances have been added to your dataset. This <em>MUST</em> also be incremented when incremented on the schema.</p>
|
||||
<li data-md="">
|
||||
<p><em>MINOR</em> - Additional, backward compatible, information is provided about existing rows/individuals. This <em>MUST</em> increment when MINOR is incremented in the underlying schema.</p>
|
||||
<li data-md="">
|
||||
<p><em>MAJOR</em> - Non-backward compatible changes to the data or underlying schema. This <em>MUST</em> be incremented when MAJOR is incremented in the underlying schema.</p>
|
||||
</ul>
|
||||
<div class="advisement">
|
||||
Backward compatibility for datasets may depend on the specific use case. In general, a dataset change is considered backward compatible if it does not alter existing data structures, remove information, or require modifications to existing queries consuming the dataset.
|
||||
</div>
|
||||
<h4 class="heading settled" data-level="2.1.4" id="schema-versioning"><span class="secno">2.1.4. </span><span class="content">Schema Versioning</span><a class="self-link" href="#schema-versioning"></a></h4><p>When versioning schemas for reading or interacting with datasets—such as RDBMS Schemas, Semantic Web Ontologies, and XML Schemas—the schema <em>MUST</em> describe the following:</p><ol>
|
||||
<li data-md="">
|
||||
<p>Public structured data whose schema is being defined.</p>
|
||||
<li data-md="">
|
||||
<p>You are versioning the schema independently of the dataset or you are versioning the schema and not the dataset.</p>
|
||||
</ol><p>For any artifact of this type the meaning of incrementing the components of a version are as follows:</p><ul>
|
||||
<li data-md="">
|
||||
<p><em>PATCH</em> - Additional or improved validation, indexing, and other backward compatible improvements that do not introduce new data. Also data's structure and typing is unchanged except for bugs contrary to the documented expected behavior.</p>
|
||||
<li data-md="">
|
||||
<p><em>MINOR</em> - Additions only to the schema allowing access to new underlying data while not changing the structure of historical data.</p>
|
||||
<li data-md="">
|
||||
<p><em>MAJOR</em> - Any changes to the structure of the data preventing backward compatible access to historical data.</p>
|
||||
</ul><h4 class="heading settled" data-level="2.1.5" id="hybrid-versioning"><span class="secno">2.1.5. </span><span class="content">Hybrid Versioning</span><a class="self-link" href="#hybrid-versioning"></a></h4><p>When versioning artifacts that contain multiple resources that <em>SHOULD</em> be versioned separately, which is required when you have public interfaces that represent two or more of the version classes listed here, then you <em>MUST</em> use hybrid versioning. To use Hybrid Versioning the following criteria <em>MUST</em> be met.</p><ol>
|
||||
<li data-md="">
|
||||
<p>The artifact <em>MUST</em> include two or more publicly exposed components that can be defined by one of the versioning classes outlined here.</p>
|
||||
<li data-md="">
|
||||
<p>The exposed components <em>MUST</em> be of either different versioning classes, or are versioned separately.</p>
|
||||
</ol><p>When versioning an artifact with multiple hybrid versions each versioned public component receives an independent version according to the rules of its versioning class. In addition the overall artifact gets an additional version, this version will increment one of its parts depending on the <em>most significant</em> version change across all its other interfaces, incrementing at most one version step. The specific parts of the version behave as follows:</p><ul>
|
||||
<li data-md="">
|
||||
<p><em>META</em> - This will be dropped or assigned at the package maintainers discretion. Never expect it to be an ordered value.</p>
|
||||
<li data-md="">
|
||||
<p><em>EXTRA</em> - Increment this when the most significant version change among your other components was an EXTRA version increase. This field <em>MAY</em> not reset when a higher position resets. It will always be, at a minimum, the lowest value, if any, after reset, from all its subcomponents.</p>
|
||||
<li data-md="">
|
||||
<p><em>PATCH</em> - Increment this when the most significant version change among your other components was a PATCH version increase.</p>
|
||||
<li data-md="">
|
||||
<p><em>MINOR</em> - Increment this when the most significant version change among your other components was a MINOR version increase.</p>
|
||||
<li data-md="">
|
||||
<p><em>MAJOR</em> - Increment this when the most significant version change among your other components was a MAJOR version increase.</p>
|
||||
</ul><div class="example" id="example-68c1c732">
|
||||
<!--
|
||||
<a class="self-link" href="#example-68c1c732"></a> Example hybrid version jumps based on the version changes in its other components.
|
||||
<p><code>1.0.0-alpha</code> -> <code>1.0.0-beta</code> if <code>2.6.7-alpha</code> -> <code>2.6.7-beta</code>, <code>1.8.3+102</code> -> <code>1.8.3+111</code></p>
|
||||
<p><code>1.0.0-alpha</code> -> <code>1.0.1-beta</code> if <code>2.6.7-alpha</code> -> <code>2.6.7-beta</code>, <code>1.8.3+102</code> -> <code>1.8.4</code></p>
|
||||
<p><code>1.0.0-alpha</code> -> <code>1.1.0</code> if <code>2.6.7-alpha</code> -> <code>2.6.7</code>, <code>1.8.3+102</code> -> <code>1.10.3</code></p>
|
||||
<p><code>1.0.0-alpha</code> -> <code>1.1.0</code> if <code>2.6.7-alpha</code> -> <code>2.6.7+112</code>, <code>1.8.3+102</code> -> <code>1.10.3+113</code></p>
|
||||
<head>
|
||||
-->
|
||||
<p>Example hybrid version jumps based on the version changes in its other components:</p>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Versioning Table</title>
|
||||
<style>
|
||||
body {
|
||||
font-family: Arial, sans-serif;
|
||||
}
|
||||
table {
|
||||
width: 100%;
|
||||
border-collapse: collapse;
|
||||
margin: 20px 0;
|
||||
font-size: 1em;
|
||||
text-align: left;
|
||||
background-color: white;
|
||||
}
|
||||
th, td {
|
||||
border: 1px solid black;
|
||||
padding: 12px;
|
||||
}
|
||||
th {
|
||||
background-color: #e0e0e0;
|
||||
font-weight: bold;
|
||||
}
|
||||
tr:nth-child(even) {
|
||||
background-color: #f7f7f7;
|
||||
}
|
||||
code {
|
||||
padding: 2px 5px;
|
||||
border-radius: 4px;
|
||||
font-family: "Courier New", monospace;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th> Composite Artifact </th>
|
||||
<th> Component 1</th>
|
||||
<th> Component 2</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>1.0.0-alpha → 1.0.0-beta</code></td>
|
||||
<td><code>2.6.7-alpha → 2.6.7-beta</code></td>
|
||||
<td><code>1.8.3+102 → 1.8.3+111</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>1.0.0-alpha → 1.0.1-beta</code></td>
|
||||
<td><code>2.6.7-alpha → 2.6.7-beta</code></td>
|
||||
<td><code>1.8.3+102 → 1.8.4</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>1.0.0-alpha → 1.1.0</code></td>
|
||||
<td><code>2.6.7-alpha → 2.6.7</code></td>
|
||||
<td><code>1.8.3+102 → 1.10.3</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>1.0.0-alpha → 1.1.0</code></td>
|
||||
<td><code>2.6.7-alpha → 2.6.7+112</code></td>
|
||||
<td><code>1.8.3+102 → 1.10.3+113</code></td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
</body>
|
||||
</div><h3 class="heading settled" data-level="2.2" id="dependent-artifact-versioning"><span class="secno">2.2. </span><span class="content">Dependent Artifact Versioning</span><a class="self-link" href="#dependent-artifact-versioning"></a></h3><p>On occasion you have software that needs to be versioned relative to the to the version against which it is written. Example projects and schema-extensions are good examples of this. Such software <em>SHOULD</em> have the following criteria:</p><ol>
|
||||
<li data-md="">
|
||||
<p>Its version only makes sense relative to the base projects version.</p>
|
||||
<li data-md="">
|
||||
<p>The version of the base project will always be treated as a more significant digit than the version of this project.</p>
|
||||
</ol><p>When using this versioning paradigm the <em>EXTRA</em> field is used to embed this projects encoding. The <em>EXTRA</em> field effectively embeds a second version that follows all the same rules as a standalone normal version. The fully expanded format for a version with this paradigm would now be <code>MAJOR_BASE.MINOR_BASE.PATCH_BASE</code> which expands to:</p><pre>MAJOR_BASE.MINOR_BASE.PATCH_BASE-MAJOR.MINOR.PATCH+META_BASE
|
||||
</pre><p>For any artifact of this type the meaning of incrementing the components of a version entirely depend on the versioning class itself.</p><div class="example" id="example-a0a09200">
|
||||
<a class="self-link" href="#example-a0a09200"></a> Example Dependent Artifact Versioning:
|
||||
<p><code>1.2.3-4.5.6</code> > <code>1.2.2-5.6.7</code></p>
|
||||
</div>
|
||||
<section>
|
||||
<h2 class="heading settled" id="backus" data-level="3"><span class="secno">3. </span><span class="content">Backus–Naur Form</span><a class="self-link" href="#backus"></a></h2>
|
||||
<div class="highlight">
|
||||
<pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;" tabindex="0">
|
||||
<valid semver> ::= <version core>
|
||||
| <version core> "-" <extra>
|
||||
| <version core> "+" <build>
|
||||
| <version core> "-" <extra> "+" <build>
|
||||
|
||||
<version core> ::= <major> "." <minor> "." <patch>
|
||||
<major> ::= <numeric identifier>
|
||||
<minor> ::= <numeric identifier>
|
||||
<patch> ::= <numeric identifier>
|
||||
<extra> ::= <dot-separated extra identifiers>
|
||||
<dot-separated extra identifiers> ::= <extra identifier>
|
||||
| <extra identifier> "." <dot-separated extra identifiers>
|
||||
<build> ::= <dot-separated build identifiers>
|
||||
<dot-separated build identifiers> ::= <build identifier>
|
||||
| <build identifier> "." <dot-separated build identifiers>
|
||||
<extra identifier> ::= <alphanumeric identifier>
|
||||
| <numeric identifier>
|
||||
<build identifier> ::= <alphanumeric identifier>
|
||||
| <digits>
|
||||
<alphanumeric identifier> ::= <non-digit>
|
||||
| <non-digit> <identifier characters>
|
||||
| <identifier characters> <non-digit>
|
||||
| <identifier characters> <non-digit> <identifier characters>
|
||||
<numeric identifier> ::= "0"
|
||||
| <positive digit>
|
||||
| <positive digit> <digits>
|
||||
<identifier characters> ::= <identifier character>
|
||||
| <identifier character> <identifier characters>
|
||||
<identifier character> ::= <digit>
|
||||
| <non-digit>
|
||||
<non-digit> ::= <letter>
|
||||
| "-"
|
||||
<digits> ::= <digit>
|
||||
| <digit> <digits>
|
||||
<digit> ::= "0"
|
||||
| <positive digit>
|
||||
<positive digit> ::= "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
|
||||
<letter> ::= "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J"
|
||||
| "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T"
|
||||
| "U" | "V" | "W" | "X" | "Y" | "Z" | "a" | "b" | "c" | "d"
|
||||
| "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n"
|
||||
| "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x"
|
||||
| "y" | "z"
|
||||
</pre>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<h2 class="heading settled" data-level="4" id="acknowledgments"><span class="secno">4. </span><span class="content">Acknowledgments</span><a class="self-link" href="#acknowledgments"></a></h2><p>We would like to give special thanks to the <a href="https://SemVer.org">SemVer project</a> for providing an early open-source version of the SemVer specification that highly influenced the development of this specification.</p><p>We would also like to thank the <a href="https://CleverThis.com">CleverThis</a> company and the <a href="https://CleverLibre.org">CleverLibre</a> non-profit organization for donating resources and staff for the completion of this specification. With particular thanks to <a href="https://JeffreyFreeman.me">Jeffrey Phillips Freeman</a> for his leadership in this initiative.</p>
|
||||
<!-- <h2 class="no-num no-ref heading settled" id="references"><span class="content">References</span><a class="self-link" href="#references"></a></h2> -->
|
||||
</section>
|
||||
<script src="https://www.w3.org/scripts/TR/2021/fixup.js"></script>
|
||||
</body>
|
||||
</html>
|
||||
256
index.bs
256
index.bs
|
|
@ -1,256 +0,0 @@
|
|||
<pre class='metadata'>
|
||||
Title: Semantic Versioning
|
||||
H1: v3.0.0, W3C Draft, 30 March 2024
|
||||
Shortname: Semantic Versioning
|
||||
Abstract: Semantic Versioning is a specification for versioning of software and related artifacts. It ensures versions are predictable and meaningful adding semantics to versioning.
|
||||
Date: 2024-03-30
|
||||
Level: 3
|
||||
Status: LS
|
||||
Complain About: accidental-2119 on, broken-links on, missing-example-ids on
|
||||
Markup Shorthands: css no, markdown yes
|
||||
Ignored Terms: h1, h2, h3, h4, h5, h6, xmp
|
||||
Inline Github Issues: false
|
||||
URL: https://semantic-versioning.org
|
||||
Canonical URL: https://semantic-versioning.org
|
||||
Logo: https://semantic-versioning.org/images/logo.png
|
||||
ED: https://semantic-versioning.org
|
||||
Issue Tracking: CleverThis GitLab https://git.cleverthis.com/cleverthis/semantic-versioning/semantic-versioning/-/issues
|
||||
Work Status: exploring
|
||||
Repository: https://git.cleverthis.com/cleverthis/semantic-versioning/semantic-versioning/
|
||||
Repository: https://git.cleverthis.com/cleverthis/semantic-versioning/semantic-versioning-w3c/
|
||||
Editor: Jeffrey Phillips Freeman, CleverThis https://CleverThis.com, Jeffrey.Freeman@CleverThis.com, https://JeffreyFreeman.me
|
||||
!Author: <a class="p-name fn u-url url" href="https://JeffreyFreeman.me">Jeffrey Phillips Freeman</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Jeffrey.Freeman@CleverThis.com">Jeffrey.Freeman@CleverThis.com</a>
|
||||
!Author: <a class="p-name fn u-url url" href="https://Kyle.Hird.u.CleverThis.com">Kyle Hird</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Kyle.Hird@CleverThis.com">Kyle.Hird@CleverThis.com</a>
|
||||
!Contributor: <a class="p-name fn u-url url" href="https://JeffreyFreeman.me">Jeffrey Phillips Freeman</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Jeffrey.Freeman@CleverThis.com">Jeffrey.Freeman@CleverThis.com</a>
|
||||
!Contributor: <a class="p-name fn u-url url" href="https://Kyle.Hird.u.CleverThis.com">Kyle Hird</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Kyle.Hird@CleverThis.com">Kyle.Hird@CleverThis.com</a>
|
||||
!Contributor: <a class="p-name fn u-url url" href="https://Brent.Edwards.u.CleverThis.com">Brent Edwards</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Brent.Edwards@CleverThis.com">Brent.Edwards@CleverThis.com</a>
|
||||
!Contributor: <a class="p-name fn u-url url" href="https://Rui.Hu.u.CleverThis.com">Rui Hu</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Rui.Hu@CleverThis.com">Rui.Hu@CleverThis.com</a>
|
||||
!Contributor: <a class="p-name fn u-url url" href="https://Stanislav.Hejny.u.CleverThis.com">Stanislav Hejny</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Stanislav.Hejny@CleverThis.com">Stanislav.Hejny@CleverThis.com</a>
|
||||
!Contributor: <a class="p-name fn u-url url" href="https://Luis.Mendes.u.CleverThis.com">Luis Mendes</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Luis.Mendes@CleverThis.com">Luis.Mendes@CleverThis.com</a>
|
||||
!Contributor: <a class="p-name fn u-url url" href="https://madeline.pace.u.CleverThis.com">Madeline Pace</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:madeline.pace@CleverThis.com">madeline.pace@CleverThis.com</a>
|
||||
!Contributor: <a class="p-name fn u-url url" href="https://Josi.Rosenfeld.u.CleverThis.com">Josi Rosenfeld</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Josi.Rosenfeld@CleverThis.com">Josi.Rosenfeld@CleverThis.com</a>
|
||||
!Contributor: <a class="p-name fn u-url url" href="https://Bilal.Benmahria.u.CleverThis.com">Bilal Ben Mahria</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Bilal.Benmahria@CleverThis.com">Bilal.Benmahria@CleverThis.com</a>
|
||||
!Contributor: <a class="p-name fn u-url url" href="https://Hamza.Khyari.u.CleverThis.com">Hamza Khyari</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Hamza.Khyari@CleverThis.com">Hamza.Khyari@CleverThis.com</a>
|
||||
!Contributor: <a class="p-name fn u-url url" href="https://Aditya.Chhabra.u.CleverThis.com">Aditya Chhabra</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Aditya.Chhabra@CleverThis.com">Aditya.Chhabra@CleverThis.com</a>
|
||||
!Contributor: <a class="p-name fn u-url url" href="https://Adnaan.Nazir.u.CleverThis.com">Adnaan Nazir</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Adnaan.Nazir@CleverThis.com">Adnaan.Nazir@CleverThis.com</a>
|
||||
!Contributor: <a class="p-name fn u-url url" href="https://Aleena.Umair.u.CleverThis.com">Aleena Umair</a> (<a class="p-org org" href="https://CleverThis.com">CleverThis</a>) <a class="u-email email" href="mailto:Aleena.Umair@CleverThis.com">Aleena.Umair@CleverThis.com</a>
|
||||
</pre>
|
||||
|
||||
# Overview
|
||||
|
||||
Given a version number
|
||||
```
|
||||
MAJOR.MINOR.PATCH-EXTRA+META
|
||||
```
|
||||
, increment the:
|
||||
|
||||
1. *MAJOR* version when you make backwards incompatible changes
|
||||
1. *MINOR* version when you add functionality in a backward compatible manner
|
||||
1. *PATCH* version when you make backward compatible bug fixes
|
||||
1. *EXTRA* version when you make a new prerelease, or other extra versioning parameters
|
||||
|
||||
<div class="note">
|
||||
EXTRA Has a natural ordering, specified below, may contain any alphanumeric characters, in addition to dots, and additional dashes
|
||||
</div>
|
||||
|
||||
<div class="note">
|
||||
META metadata is non-ordered, this does not increment
|
||||
</div>
|
||||
|
||||
|
||||
# Semantic Versioning Specification
|
||||
|
||||
The keywords "*MUST*", "*MUST NOT*", "*REQUIRED*", "*SHALL*", "*SHALL NOT*", "*SHOULD*","*SHOULD NOT*", "*RECOMMENDED*", "*MAY*", and "*OPTIONAL*" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
|
||||
|
||||
<ol class="algorithm">
|
||||
<li>A normal version number *MUST* take the form `X.Y.Z` where `X`, `Y`, and `Z` are non-negative integers, and *MUST NOT* contain leading zeroes. `X` is the major version, `Y` is the minor version, and `Z` is the patch version. `X`, `Y`, and `Z` *MUST* be representable in a thirty-two-bit unsigned integer, i.e. strictly less than 4,294,967,296.</li>
|
||||
|
||||
<li>Once a versioned package has been released, the contents of that version *MUST NOT* be modified. Any modifications *MUST* be released as a new version.</li>
|
||||
|
||||
<li>Major version zero `(0.y.z)` is for initial development. Anything *MAY* change at any time. The artifact *SHOULD NOT* be considered stable.</li>
|
||||
|
||||
<li>Version `1.0.0` defines the artifact. The way in which the version number is incremented after this release is dependent on the version class of the component.</li>
|
||||
|
||||
<li>Patch version `Z` `(x.y.Z | x > 0)` *MUST* be incremented if only backward compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect documented behavior or improves performance characteristics while adding no new functionality.</li>
|
||||
|
||||
<li>Minor version `Y` `(x.Y.z | x > 0)` *MUST* be incremented if new, backward compatible functionality is introduced to the component. It *MUST* be incremented if any public functionality is marked as deprecated and it *MUST* be incremented if new functionality is exposed publicly through the versioned component. It *MAY* include patch level changes. Patch version *MUST* be reset to 0 when minor version is incremented. The minor version *MUST NOT* increment if the major version is eligible to be incremented at this time.</li>
|
||||
|
||||
<li>Major version `X` `(X.y.z | X > 0)` *MUST* be incremented if any backward incompatible changes are introduced to the component being versioned. It *MAY* also include minor and patch and minor level changes. Patch and minor versions *MUST* be reset to 0 when major version is incremented.</li>
|
||||
|
||||
<li>Extra version *MAY* be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers *MUST* comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers *MUST NOT* be empty. Numeric identifiers *MUST NOT* include leading zeroes. Extra versions have a lower precedence than the associated normal version. An extra version containing only purely numeric identifiers represents a subversion and will follow the same format and rules as a normal version (see dependent version class below). Any other extra version indicates a pre-release and that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version.</li>
|
||||
|
||||
<li>Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers *MUST* comprise only ASCII alphanumerics and hyphens `[0-9A-Za-z-]`.Identifiers *MUST NOT* be empty. Build metadata *MUST* be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence.</li>
|
||||
|
||||
<li>A version number *MUST* be no longer than 255 characters, including extra version and build metadata.</li>
|
||||
|
||||
<li>Precedence refers to how versions are compared to each other when ordered.</li>
|
||||
|
||||
<ol>
|
||||
|
||||
<li>Precedence *MUST* be calculated by separating the version into major, minor, patch and extra identifiers in that order (Build metadata does not figure into precedence).</li>
|
||||
|
||||
<li>Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Major, minor, and patch versions are always compared numerically.</li>
|
||||
|
||||
<li>When major, minor, and patch are equal, an extra version has lower precedence than a normal version.</li>
|
||||
|
||||
<li>Precedence for two extra versions with the same major, minor, and patch version *MUST* be determined by comparing each dot separated identifier from left to right until a difference is found as follows:</li>
|
||||
|
||||
<ol>
|
||||
|
||||
<li>Identifiers consisting of only digits are compared numerically.</li>
|
||||
|
||||
<li>Identifiers with letters or hyphens are compared lexically in ASCII sort order.</li>
|
||||
|
||||
<li>Numeric identifiers always have lower precedence than non-numeric identifiers.</li>
|
||||
|
||||
<li>A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal.</li>
|
||||
|
||||
</ol>
|
||||
|
||||
</ol>
|
||||
|
||||
<li>Select the subcategory below that best describes the artifact. They are ordered in descending priority, so pick the first category that matches your software type.</li>
|
||||
</ol>
|
||||
|
||||
<div class="example">
|
||||
Example versions without the optional EXTRA or META components:
|
||||
|
||||
`1.9.0`, `1.10.0`, `1.11.0`
|
||||
</div>
|
||||
|
||||
<div class="example">
|
||||
Example versions utilizing the optional EXTRA component but without META:
|
||||
|
||||
`1.0.0-alpha`, `1.0.0-alpha.1`, `1.0.0-0.3.7`, `1.0.0-x.7.z.92`, `1.0.0-x-y-z`
|
||||
</div>
|
||||
|
||||
<div class="example">
|
||||
Example versions utilizing the optional EXTRA and META components:
|
||||
|
||||
`1.0.0-alpha+001`, `1.0.0+20130313144700`, `1.0.0-beta+exp.sha.5114f85`, `1.0.0+21AF26D3117B344092BD`
|
||||
</div>
|
||||
|
||||
<div class="example">
|
||||
Example version precedence:
|
||||
|
||||
`1.0.0-alpha` < `1.0.0-alpha.1` < `1.0.0-alpha.beta` < `1.0.0-beta` < `1.0.0-beta.2` < `1.0.0-beta.11` < `1.0.0-rc.1` < `1.0.0` < `2.0.0-alpha` < `2.0.0` < `2.1.0` < `2.1.1`
|
||||
</div>
|
||||
|
||||
## Version Classes
|
||||
|
||||
While the general meaning of a PATCH, MINOR, and MAJOR version are defined in the specification above the specific interpretation is not always clear depending on the class of resources you happen to be versioning. An API, Schema, or even an application would all interpret when to bump a version a bit differently. Therefore we have tried to define explicitly versioning rules for the various classes of resources of interest. Any class not covered in this specification is technically not covered by it, but it is still recommended the general principles outlined in the specification above still be adhered to when possible.
|
||||
|
||||
<div class="advisement">
|
||||
When picking a version class we only care about **exposed** components. Internal APIs, internal data, and dependencies shouldn't affect versioning. The exposed components being versions, and the versioning class being used, should always be explicitly stated by the project owners.
|
||||
</div>
|
||||
|
||||
When a artifact covers several exposed components that are either of different versioning classes, or just make sense to version separately then they should always be versioned separately. The overall artifact version can be determined by the hybrid versioning class mentioned below.
|
||||
|
||||
### API Versioning
|
||||
|
||||
When, versioning software with a public API such as libraries, and web endpoints it must match the following criteria:
|
||||
|
||||
1. The resource *MUST* declare a public API.
|
||||
1. The API must be declared as code or specification documentation.
|
||||
|
||||
For any artifact of this type the meaning of incrementing the components of a version are as follows:
|
||||
|
||||
* *PATCH* - An internal fix to bring behavior in compliance with the documented expected behavior for the public API; this should implement no changes to the public API signatures.
|
||||
* *MINOR* - If new functionality is added to the public API in a backwards compatible way, including new information in the return values.
|
||||
* *MAJOR* - Any change to the public API that breaks backwards compatibility.
|
||||
|
||||
### UI Versioning
|
||||
|
||||
When versioning User Interfaces which may have any nature of input whether it be command-line, GUI, or some other interface, the following paradigm should be used. The following criteria must be satisfied:
|
||||
|
||||
1. The resource must have a user interface of some kind, both command-line and GUI are acceptable.
|
||||
|
||||
For any artifact of this type the meaning of incrementing the components of a version are as follows:
|
||||
|
||||
* *PATCH* - An internal fix to bring behavior in compliance with the documented expected behavior for the UI; this should implement no changes to the user interface of any kind.
|
||||
* *MINOR* - Any backwards compatible changes to the UI. Backwards compatible means while new entries and elements can be added the existing ones should retain their same name, exist somewhere within the same menu items and menu structure, and behave consistently as they have in the past (or fixed according to the documented and expected behavior). This applies to all language variants of the interface.
|
||||
* *MAJOR* - Any change to any of the interface in any language, that breaks backwards compatibility.
|
||||
|
||||
### Dataset Versioning
|
||||
|
||||
When, versioning datasets which may have the schema versioned alongside or separately. A dataset may include such things as a RDBMS database, a Semantic Web Knowledge Graph, or an XML file. Such Datasets must describe the following:
|
||||
|
||||
1. Public structured data for which access is being provided.
|
||||
|
||||
For any artifact of this type the meaning of incrementing the components of a version are as follows:
|
||||
|
||||
<div class="advisement">
|
||||
Anytime the underlying schema experiences an increase in any of its version's parts then the dataset must at least increment its version corresponding part, or a more significant part.
|
||||
</div>
|
||||
|
||||
* *PATCH* - Additional rows / instances have been added to your dataset. This *MUST* also be incremented when incremented on the schema.
|
||||
* *MINOR* - Additional, backwards compatible, information is provided about existing rows/individuals. This *MUST* increment when MINOR is incremented in the underlying schema (see schema versioning below).
|
||||
* *MAJOR* - Non-backwards compatible changes to the data or underlying schema. This *MUST* be incremented when MAJOR is incremented in the underlying schema.
|
||||
|
||||
### Schema Versioning
|
||||
|
||||
When, versioning schemas for reading or interacting with data sets, for example, RDBMS Schema, Semantic Web Ontologies, and XML Schemas. Such schemas must describe the following:
|
||||
|
||||
1. Public structured data whose schema is being defined.
|
||||
1. You are versioning the schema independently of the dataset or you are versioning the schema and not the dataset.
|
||||
|
||||
For any artifact of this type the meaning of incrementing the components of a version are as follows:
|
||||
|
||||
* *PATCH* - Additional or improved validation, indexing, and other backwards compatible improvements that do not introduce new data. Also data's structure and typing is unchanged except for bugs contrary to the documented expected behavior.
|
||||
* *MINOR* - Additions only to the schema allowing access to new underlying data while not changing the structure of historic data.
|
||||
* *MAJOR* - Any changes to the structure of the data preventing bachwards-compatible access to historic data.
|
||||
|
||||
### Hybrid Versioning
|
||||
|
||||
When, versioning artifacts that contain multiple resources that should be versioned separate, which is required when you have public interfaces that represent 2 or more of the version classes listed here, then you must use hybrid versioning. To use Hybrid Versioning the following criteria must be met.
|
||||
|
||||
1. The artifact must include 2 or more publicly exposed components that can be defined by one of the versioning classes outlined here.
|
||||
1. The exposed components must be of either different versioning classes, or are versioned separately.
|
||||
|
||||
Each versioned public component receives a version that is independent and according to the rules of it's versioning class. In addition the overall artifact gets an additional version, this version will increment one of its parts depending on the *most significant* version change across all its other interfaces. Bumping at most one version step. The specific parts of the version behave as follows:
|
||||
|
||||
|
||||
* *META* - This will be dropped or assigned at the package maintainers discretion. Never expect it to be an ordered value.
|
||||
* *EXTRA* - Increment this when the most significant version bump among your other components was a bump to the EXTRA version. This field may not reset when a higher position resets. It will always be, at a minimum, the lowest value, if any, after reset, from all its subcomponents.
|
||||
* *PATCH* - Increment this when the most significant version bump among your other components was a bump to the PATCH version.
|
||||
* *MINOR* - Increment this when the most significant version bump among your other components was a bump to the MINOR version.
|
||||
* *MAJOR* - Increment this when the most significant version bump among your other components was a bump to the MAJOR version.
|
||||
|
||||
<div class="example">
|
||||
Example hybrid version jumps based on the version changes in its other components.
|
||||
|
||||
`1.0.0-alpha` -> `1.0.0-beta` if `2.6.7-alpha` -> `2.6.7-beta`, `1.8.3+102` -> `1.8.3+111`
|
||||
|
||||
`1.0.0-alpha` -> `1.0.1-beta` if `2.6.7-alpha` -> `2.6.7-beta`, `1.8.3+102` -> `1.8.4`
|
||||
|
||||
`1.0.0-alpha` -> `1.1.0` if `2.6.7-alpha` -> `2.6.7`, `1.8.3+102` -> `1.10.3`
|
||||
|
||||
`1.0.0-alpha` -> `1.1.0` if `2.6.7-alpha` -> `2.6.7+112`, `1.8.3+102` -> `1.10.3+113`
|
||||
</div>
|
||||
|
||||
## Dependent Artifact Versioning
|
||||
|
||||
On occasion you have software that needs to be versioned relative to the version it is written against. Example projects, and schema-extensions are good examples of this. Such software should have the following criteria.
|
||||
|
||||
1. Its version only makes sense relative to the base projects version.
|
||||
1. The version of the base project will always be treated as a more significant digit than the version of this project. Such that.
|
||||
|
||||
When using this versioning paradigm the *EXTRA* field is used to embed this projects encoding. The *EXTRA* field effectively embeds a second version that follows all the same rules as a standalone normal version. The fully expanded format for a version with this paradigm would now be `MAJOR_BASE.MINOR_BASE.PATCH_BASE` which expands to:
|
||||
|
||||
```
|
||||
MAJOR_BASE.MINOR_BASE.PATCH_BASE-MAJOR.MINOR.PATH+META_BASE
|
||||
```
|
||||
|
||||
For any artifact of this type the meaning of incrementing the components of a version entirely depend on the versioning class itself.
|
||||
|
||||
<div class="example">
|
||||
Example Dependent Artifact Versioning
|
||||
|
||||
`1.2.3-4.5.6` > `1.2.2-5.6.7`
|
||||
</div>
|
||||
|
||||
# Acknowledgments
|
||||
|
||||
We would like to give special thanks to the [SemVer project](https://SemVer.org) for providing an early open-source version of the SemVer specification that highly influenced the development of this specification.
|
||||
|
||||
We would also like to thank the [CleverThis](https://CleverThis.com) company and the [CleverLibre](https://CleverLibre.org) non-profit organization for donating resources and staff for the completion of this specification. With particular thanks to [Jeffrey Phillips Freeman](https://JeffreyFreeman.me) for his leadership in this initiative.
|
||||
Loading…
Add table
Reference in a new issue