Version Parts Major Minor

[Coleman John]

Insystems with many dependencies, releasing new package versions can quicklybecome a nightmare. If the dependency specifications are too tight, you are indanger of version lock (the inability to upgrade a package without having torelease new versions of every dependent package). If dependencies arespecified too loosely, you will inevitably be bitten by version promiscuity(assuming compatibility with more future versions than is reasonable).Dependency hell is where you are when version lock and/or version promiscuityprevent you from easily and safely moving your project forward.

As a solution to this problem, we propose a simple set of rules andrequirements that dictate how version numbers are assigned and incremented.These rules are based on but not necessarily limited to pre-existingwidespread common practices in use in both closed and open-source software.For this system to work, you first need to declare a public API. This mayconsist of documentation or be enforced by the code itself. Regardless, it isimportant that this API be clear and precise. Once you identify your publicAPI, you communicate changes to it with specific increments to your versionnumber. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes notaffecting the API increment the patch version, backward compatible APIadditions/changes increment the minor version, and backward incompatible APIchanges increment the major version.

Software using Semantic Versioning MUST declare a public API. This APIcould be declared in the code itself or exist strictly in documentation.However it is done, it SHOULD be precise and comprehensive.

A normal version number MUST take the form X.Y.Z where X, Y, and Z arenon-negative integers, and MUST NOT contain leading zeroes. X is themajor version, Y is the minor version, and Z is the patch version.Each element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0.

Minor version Y (x.Y.z x > 0) MUST be incremented if new, backwardcompatible functionality is introduced to the public API. It MUST beincremented if any public API functionality is marked as deprecated. It MAY beincremented if substantial new functionality or improvements are introducedwithin the private code. It MAY include patch level changes. Patch versionMUST be reset to 0 when minor version is incremented.

Major version X (X.y.z X > 0) MUST be incremented if any backwardincompatible changes are introduced to the public API. It MAY also include minorand patch level changes. Patch and minor versions MUST be reset to 0 when majorversion is incremented.

A pre-release version MAY be denoted by appending a hyphen and aseries of dot separated identifiers immediately following the patchversion. Identifiers MUST comprise only ASCII alphanumerics and hyphens[0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUSTNOT include leading zeroes. Pre-release versions have a lowerprecedence than the associated normal version. A pre-release versionindicates that the version is unstable and might not satisfy theintended compatibility requirements as denoted by its associatednormal version. Examples: 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.--.

Precedence for two pre-release versions with the same major, minor, andpatch version MUST be determined by comparing each dot separated identifierfrom left to right until a difference is found as follows:

If all of this sounds desirable, all you need to do to start using SemanticVersioning is to declare that you are doing so and then follow the rules. Linkto this website from your README so others know the rules and can benefit fromthem.

Use your best judgment. If you have a huge audience that will be drasticallyimpacted by changing the behavior back to what the public API intended, thenit may be best to perform a major version release, even though the fix couldstrictly be considered a patch release. Remember, Semantic Versioning is allabout conveying meaning by how the version number changes. If these changesare important to your users, use the version number to inform them.

Deprecating existing functionality is a normal part of software development andis often required to make forward progress. When you deprecate part of yourpublic API, you should do two things: (1) update your documentation to letusers know about the change, (2) issue a new minor release with the deprecationin place. Before you completely remove the functionality in a new major releasethere should be at least one minor release that contains the deprecation sothat users can smoothly transition to the new API.

Software versioning is the process of assigning either unique version names or unique version numbers to unique states of computer software. Within a given version number category (e.g., major or minor), these numbers are generally assigned in increasing order and correspond to new developments in the software. At a fine-grained level, revision control is used for keeping track of incrementally-different versions of information, whether or not this information is computer software, in order to be able to roll any changes back.

Modern computer software is often tracked using two different software versioning schemes: an internal version number that may be incremented many times in a single day, such as a revision control number, and a release version that typically changes far less often, such as semantic versioning[1] or a project code name.

File numbers were used especially in public administration, as well as companies, to uniquely identify files or cases. For computer files this practice was introduced for the first time with MIT's ITS file system, later the TENEX filesystem for the PDP-10 in 1972.[2]

Later lists of files including their versions were added, and dependencies amongst them. Linux distributions like Debian, with its dpkg, early on created package management software which could resolve dependencies between their packages. Debian's first try was that a package knew other packages which depended on it. From 1994 on this idea was inverted, so a package that knew the packages it needed. When installing a package, dependency resolution was used to automatically calculate the packages needed as well, and install them with the desired package. To facilitate upgrades, minimum package versions were introduced. Thus the numbering scheme needed to tell which version was newer than the required one.[3][4][5]

A variety of version numbering schemes have been created to keep track of different versions of a piece of software. The ubiquity of computers has also led to these schemes being used in contexts outside computing.

In sequence-based software versioning schemes, each software release is assigned a unique identifier that consists of one or more sequences of numbers or letters.[6] This is the extent of the commonality; schemes vary widely in areas such as the number of sequences, the attribution of meaning to individual sequences, and the means of incrementing the sequences.

In some schemes, sequence-based identifiers are used to convey the significance of changes between releases. Changes are classified by significance level, and the decision of which sequence to change between releases is based on the significance of the changes from the previous release, whereby the first sequence is changed for the most significant changes, and changes to sequences after the first represent changes of decreasing significance.

Depending on the scheme, significance may be assessed by lines of code changed, function points added or removed, the potential impact on customers in terms of work required to adopt a new version, risk of bugs or undeclared breaking changes, degree of changes in visual layout, the number of new features, or almost anything the product developers or marketers deem to be significant, including marketing desire to stress the "relative goodness" of the new version.

Developers may choose to jump multiple minor versions at a time to indicate that significant features have been added, but are not enough to warrant incrementing a major version number; for example, Internet Explorer 5 from 5.1 to 5.5 or Adobe Photoshop 5 to 5.5. This may be done to emphasize the value of the upgrade to the software user or, as in Adobe's case, to represent a release halfway between major versions (although levels of sequence-based versioning are not necessarily limited to a single digit, as in Blender version 2.91 or Minecraft Java Edition starting from 1.7.10).

Again, in these examples, the definition of what constitutes a "major" as opposed to a "minor" change is entirely subjective and up to the author, as is what defines a "build", or how a "revision" differs from a "minor" change.

Often programmers write new software to be backward compatible, i.e., the new software is designed to interact correctly with older versions of the software (using old protocols and file formats) and the most recent version (using the latest protocols and file formats). For example, IBM z/OS is designed to work properly with 3 consecutive major versions of the operating system running in the same sysplex.This enables people who run a high availability computer cluster to keep most of the computers up and running while one machine at a time is shut down, upgraded, and restored to service.[12]

Software in the experimental stage (alpha or beta) often uses a zero in the first ("major") position of the sequence to designate its status. However, this scheme is only useful for the early stages, not for upcoming releases with established software where the version number has already progressed past 0.[1]

On the other hand, some software packages identify releases by decimal numbers: 1.7, 1.8, 1.81, 1.82, 1.9, etc. Decimal versions were common in the 1980s, for example with NetWare, DOS, and Microsoft Windows, but even in the 2000s have been for example used by Opera[13] and Movable Type.[14] In the decimal scheme, 1.81 is the minor version following 1.8, while maintenance releases (i.e. bug fixes only) may be denoted with an alphabetic suffix, such as 1.81a or 1.81b.

3a8082e126