Abstract

Version format: Major version number. The second version number. The increment rule is as follows:

  1. Major version number: When you make incompatible API changes,
  2. Minor version number: When you make a backward-compatible feature addition,
  3. Revision number: When you make a backward compatible problem fix.

The prior version number and version build metadata can be added to the major version number. Second version number. Revision number “is followed as an extension.

Introduction to the

In software management there is the valley of death known as “dependency hell,” and the bigger the system, the more packages you add, the more likely you are to find yourself at some point in the future in the depths of despair.

Releasing a new release package on a highly dependent system can quickly become a nightmare. If the dependencies are too high, you run the risk of version control being locked (each dependency package must be changed to complete an upgrade). If the dependencies are too loose, versioning chaos is unavoidable (assuming that more than a reasonable number of future compatible versions exist). When the progress of your project becomes less convenient and reliable because version dependencies are locked or versioned, it means you are in dependency hell.

As one solution to this problem, I propose a simple set of rules and conditions that constrain the configuration and growth of version numbers. These rules are based on, but are not limited to, conventions that have been widely used in a variety of closed, open source software. In order for this theory to work, you have to have a well-defined public API. This can be done through file definitions or code enforcement. However, clarity of the API is important. Once you have defined the public API, you can explain your changes by changing the corresponding version number. Consider using the version number format X.Y.Z (major version number). If the problem is fixed but does not affect the API, increment the revision number; API remains backward compatible with additions and modifications when incrementally increasing the version number; Increment the major version number when making changes that are not backward compatible.

I call this system “semantic versioning,” where version numbers and how they are updated contain information about underlying code and changes made between adjacent versions.

Semantic Versioning Specification (SemVer)

The following key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, OPTIONAL according to RFC 2119. (In order to keep the sentence smooth, the keywords encountered in the following documents will be translated according to the semantics of the whole sentence, not individually translated here.)

  1. Software that uses semantic versioning MUST define a common API. The API can be defined in code or appear in strict documentation. All forms should be precise and complete.

  2. The standard version number MUST be in the X.Y.Z format, where X, Y, and Z are non-negative integers. MUST NOT be used to add zeros before digits. X is the major release number, Y is the minor release number, and Z is the revision number. Each element MUST be incremented numerically. For example, 1.9.1 -> 1.10.0 -> 1.11.0.

  3. MUST NOT change the content of a marked version of the software after it is released. Any changes MUST be released in the new version.

  4. Software with a major version number of 0 (0.y.z) is in the early stages of development, and everything is subject to change at any time. Such a public API should not be considered stable.

  5. The 1.0.0 version number is used to define the formation of the public API. All version number updates since this release are based on the public API and its modifications.

  6. Revision number Z (X.Y.Z | x > 0) have to (MUST) in only for backward compatibility of incremental correction. A fix here refers to an internal change made in response to an incorrect result.

  7. Second version number (X.Y.Z Y | x > 0) have to (MUST) in increasing downward compatible new features emerged. MUST also be incremented when any public API functionality is marked deprecated. MAY also increment when a large number of new features or improvements are added to the internal program, which MAY include changes to the revision level. The revision number MUST return to zero each time the version number increases.

  8. The major version number (X.Y.Z X | X > 0) have to (MUST) in any incompatible changes were added to increase when the public API. This MAY include changes to the sub-version number and revision level. Each time the major version number increases, the minor version number and revision number MUST return to zero.

  9. The prior version number MAY be marked after the revision, followed by a join number followed by a series of identifiers separated by periods. The identifier MUST consists of ASCII alphanumeric characters and join numbers [0-9A-ZA-Z -], and MUST NOT be left blank. Numeric identifiers prohibit padding zeros before MUST NOT. The prior version has a lower priority than the associated standard version. A prior release number indicates that the release is not stable and may not meet the expected compatibility requirements. Example: 1.0.0 – alpha, 1.0.0 – alpha. 1, 1.0.0 0.3.7, 1.0.0 x. 7. Z. 92.

  10. Version-compilation metadata can (MAY) be annotated after the revision or prior version number, followed by a plus sign followed by a series of identifiers separated by periods. The identifier MUST consists of ASCII alphanumeric characters and join numbers [0-9A-ZA-Z -], and MUST NOT be left blank. Version compilation metadata can be ignored (SHOULD) when determining the priority level of a version. Therefore, the two versions belong to the same priority level only if the versioning compilation metadata is different. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp. Sha.5114f85.

  11. Version priority refers to how different versions compare in order. To determine the priority level, versions MUST be divided into major, minor, revision, and prior versions for comparison (version compilation metadata is not included in this comparison list). Each identifier is compared from left to right, with the first difference used to determine the priority level: major, minor, and revision numbers are compared numerically, for example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. If the major version number, minor version number and revision number are all the same, the earlier version number with lower priority will be used. For example: 1.0.0-alpha < 1.0.0. Have the same major version number, version number and revision number of the two leading the version number, have to (MUST) through its priority level of each can be separated by a period from left to right identifier to compare, until we find a difference value after the decision, only digital identifiers to numerical comparison, there are letters or connective word by word with ASCII ordering to compare. Numeric identifiers have a lower priority than non-numeric identifiers. If all identifiers start with the same identifier, the earlier version number with more columns has a higher priority. Example: 1.0.0 – alpha 1 < < 1.0.0 – alpha. 1.0.0 – alpha. Beta < 1.0.0 – beta 2 < < 1.0.0 – beta. 1.0.0 – beta. 11 1 < < 1.0.0 – rc. 1.0.0.

Why use semantic version control?

This is not a new or revolutionary idea. In fact, you might already be doing something similar. The problem is that approximation is not enough. Without some formal specification to follow, version numbers have little meaning for managing dependencies. Naming and clearly defining the ideas above makes it easy to communicate your intentions to the users of your software. Once these intentions are clear, flexible (but not too elastic) dependency specifications can be reached.

A simple example shows how semantic version control can make dependency hell a thing of the past. Suppose you have a library of functions named “Fire Engine” that needs another package named “Ladder” that already has semantic versioning. When the fire engine was created, the ladder version number was 3.1.0. Because the fire engine uses some of the features added to version 3.1.0, you can safely specify ladders that depend on version numbers greater than 3.1.0 but less than 4.0.0. This way, when Ladder versions 3.1.1 and 3.2.0 are released, you can incorporate them directly into your package management system because they are compatible with the existing dependencies.

As a responsible developer, you should ensure that each package upgrade works in accordance with the version number. The real world is complex, and there’s not much we can do except be vigilant. All you can do is let semantic version control give you a sound way to release and upgrade packages without having to release new dependencies, saving you time and annoyance.

If you agree and want to start using semantic versioning right away, you can simply declare that your library is using it and follow the rules. Keep the link to this page in your README file so that others can learn and benefit from these rules.

FAQ

How do I do version control during the initial development phase of 0.Y.Z?

The easiest way to do this is to use 0.1.0 as your initial development release and increment it with each subsequent release.

How do I know when to release 1.0.0?

By the time your software is used in a formal environment, it should have reached version 1.0.0. If you already have a stable API that users depend on, it will be version 1.0.0. If you’re worried about backward compatibility, this is version 1.0.0.

Doesn’t this discourage rapid development and iteration?

When the major release number is zero, it is for rapid development. If you are changing apis every day, you should still be in the major release zero phase (0.y.z), or in a separate development branch for the next major release.

If even the smallest but non-backward compatible change to a public API requires a new major release number, wouldn’t it be 42.0.0 soon?

It’s a matter of developing responsibly and proactively. Incompatible changes should not be easily added to software that has a lot of dependent code. The cost of upgrading could be huge. Increasing the major version number to release incompatible changes means you have to think through the impact of those changes and evaluate the cost/benefit ratio involved.

Writing files for the entire public API is too much work!

It is your responsibility as a professional developer to write appropriate documentation for software intended for use by others. A very important part of keeping your project effective is managing the complexity of your software, which can be difficult if no one knows how to use your software or which functions are reliably called. In the long run, using semantic versioning and adhering to a well-regulated public API can make everyone and everything run smoothly.

What should I do if I accidentally change an incompatible version as the second version number?

Once you find yourself breaking the specification for semantic versioning, fix the problem and issue a new sub-version number to correct the problem and restore backward compatibility. Even in this case, you should not modify the released version. If possible, record the problem version number in a file to tell the user what the problem is so they can recognize it as a problem version.

What if I update my dependencies but don’t change the public API?

Since no public API is affected, this can be considered compatible. If a piece of software has co-dependencies with your package, it will have its own dependency specification and the authors will inform you of possible conflicts. To determine whether a change is a revision level or a sub-version level, you need to update dependencies to fix problems or add new features. With the latter, I often expect more code, which is obviously a sub-version number increment.

What if I change the public API but inadvertently do not follow the version number change? (Meaning a significant and incompatible change is mistakenly added to the code in a revision level release)

Make your own best judgment. If you have a large user base that will be greatly affected if it changes its behavior in accordance with the intent of the public API, it is best to make a major release, even if the fix is strictly a revision level release. Remember, semantic version control is about communicating meaning by changing version numbers. If these changes are important to your users, tell them through the version number.

How do I deal with features that are about to be deprecated?

Discarding existing features is common in software development and often necessary to move forward. When you deprecate part of a public API, you should do two things :(1) update your files to let users know about the change, and (2) release the deprecated functionality with a new release number when appropriate. At least one minor release should contain the deprecation information before the new major release completely removes the deprecation so that users can move smoothly to the new API.

Is there a limit to the length of the string for semantic versions?

No, please use your own judgment. For example, the 255-character version is exaggerated. Furthermore, specific systems may have their own limits on string length.