semantic-versioning/semantic-versioning-w3c
17
0
Fork 0
Code Issues 1 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

bs file for the updated html #2

Open
aditya wants to merge 1 commits from development into master
pull from: development
merge into: semantic-versioning:master
Conversation 0 Commits 1 Files Changed 1
+239
1 changed files with 239 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
semantic_versioning.bs
+239
View File
@@ -0,0 +1,239 @@
<pre class='highlight'>
<!DOCTYPE html>
<!-- Converted to Bikeshed -->
Title: Semantic Versioning
## Semantic Versioning
W3C Member Submission 27 November 2024
Copyright © 2024
World Wide Web Consortium.
W3C®
liability,
trademark and
W3C Document License rules apply.
## Abstract
Semantic Versioning is a specification for versioning of software and related artifacts. It ensures versions are predictable and meaningful adding semantics to versioning.
## 1. Overview
Given a version number
```
MAJOR.MINOR.PATCH-EXTRA+META
```
MAJOR version when you make backwards incompatible changes
MINOR version when you add functionality in a backward compatible manner
PATCH version when you make backward compatible bug fixes
EXTRA version when you make a new prerelease, or other extra versioning parameters
## 2. 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.
1.9.0, 1.10.0, 1.11.0
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
1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3117B344092BD
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
## 2.1. 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.
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.
## 2.1.1. API Versioning
When, versioning software with a public API such as libraries, and web endpoints it must match the following criteria:
The resource MUST declare a public API.
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.
## 2.1.2. 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:
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.
## 2.1.3. 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:
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:
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.
## 2.1.4. 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:
Public structured data whose schema is being defined.
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.
## 2.1.5. 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.
The artifact must include 2 or more publicly exposed components that can be defined by one of the versioning classes outlined here.
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.
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
## 2.2. 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.
Its version only makes sense relative to the base projects version.
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.
1.2.3-4.5.6 > 1.2.2-5.6.7
## 3. Acknowledgments
We would like to give special thanks to the SemVer project 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 company and the CleverLibre non-profit organization for donating resources and staff for the completion of this specification. With particular thanks to Jeffrey Phillips Freeman for his leadership in this initiative.
## 4. Backus–Naur Form Grammar for Valid SemVer Versions
```
<valid semver> ::= <version core>
| <version core> "-" <pre-release>
| <version core> "+" <build>
| <version core> "-" <pre-release> "+" <build>
<version core> ::= <major> "." <minor> "." <patch>
<major> ::= <numeric identifier>
<minor> ::= <numeric identifier>
<patch> ::= <numeric identifier>
<pre-release> ::= <dot-separated pre-release identifiers>
<dot-separated pre-release identifiers> ::= <pre-release identifier>
| <pre-release identifier> "." <dot-separated pre-release identifiers>
<build> ::= <dot-separated build identifiers>
<dot-separated build identifiers> ::= <build identifier>
| <build identifier> "." <dot-separated build identifiers>
<pre-release 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"
```
## References
## Status of This Document
This section describes the status of this
document at the time of its publication. A list of current W3C
publications can be found
in the W3C technical reports index at
https://www.w3.org/TR/.
By publishing this document, W3C acknowledges that the
Submitting Members have made a formal Submission request to W3C for discussion. Publication of this document by
W3C indicates no endorsement of its content by W3C, nor that W3C has, is, or will be allocating any resources to the issues addressed by it. This document is not the product of a chartered W3C group, but is published as potential input to the
W3C Process. A
W3C Team Comment has been published in conjunction with this Member Submission. Publication of acknowledged Member Submissions at the W3C site is one of the benefits of
W3C Membership. Please consult the requirements associated with Member Submissions of
section 3.3 of the W3C Patent Policy. Please consult the complete
list of acknowledged W3C Member Submissions.
## Table of Contents
</pre>