Semantic versioning semantic version number

The Semantic version number is a naming convention about the software version number initiated by Tom Preston-Werner, the founder of GitHub. For details about this specification, visit the official website or the GitHub project page, official Website documentation:

Semantic version 2.0.0

Summary

Version format: Major version number. Minor version number. revision number. The rules for increasing the version number are as follows:

1. Major version: When you modify an incompatible API,
2. Minor version: When you add backward compatible functionality,
3. Revision No.: when you make a downward compatible issue fix.

The prefix version number and version compilation information can be added to the end of "major version number. Minor version number. revision number" as an extension.

Introduction

In the field of software management, there is a valley of death called "relying on Hell". The larger the system size, the more kits it joins, the more likely you will find yourself in despair one day in the future.

Releasing a new version of the suite in a highly dependent system may soon become a nightmare. If the dependency is too high, the version control may be locked (each dependent suite must be revised to complete an upgrade ). If the dependency is too loose, version confusion cannot be avoided (assuming that multiple versions compatible with the future have exceeded a reasonable number ). When your project progresses because the version dependency is locked or the version chaos is not easy and reliable, it means that you are in the dependency hell.

As a solution to this problem, I propose to use a set of simple rules and conditions to restrict the configuration and growth of version numbers. These rules are designed based on (but not limited to) practices that are widely used by various closed and open source software. To make this theory work, you must first define a public API. This can be achieved through file definitions or code mandatory requirements. In any case, this set of APIS is very important. Once you have defined a public API, you can modify the corresponding version number to describe your modifications. Consider using the format of this version number: XYZ (main version number. minor version number. revision number) when the problem is fixed but does not affect the API, the revision number is incremented; when the API is backward compatible with the addition and modification, the version number is incremented; when the API is not backward compatible with the modification, increase the base version number.

I call this system "semantic Version Control". Under this Convention, the version number and its update method contain the underlying code and modification content between adjacent versions.

Semantic version control specification (semver)

The following keywords are interpreted as follows in RFC 2119. In order to keep the statement smooth, the keywords encountered in the following files will be translated according to the entire sentence syntax, and no individual translation will be performed here .)

1. The software "must be must" that uses semantic version control to define public APIs. This API can be defined in code or appear in rigorous files. All forms should be accurate and complete.

2. The standard version "must be must" in XYZ format ,?? Here, x, y, and z are non-negative integers, and "Do Not Allow must not" to add zero in front of the number. X indicates the primary version number, y indicates the minor version number, and Z indicates the revision number. Each element "must be must" is incremented by a number. For example, 1.9.1-> 1.10.0-> 1.11.0.

3. After a software release marked with a version number is released, "prohibit must not" to change the content of the software version. Any modifications must be released in the new version.

4. The software with a major version of zero (0.yz) is in the initial stage of development, and everything may be changed at any time. Such a public API should not be regarded as a stable version.

5. Version 1.0.0 is used to define the formation of public APIs. After this version, all version updates are based on the public API and the modified content.

6. Revision No. Z (XYZ | x> 0) "must be must" is incremental only when downward compatible correction is performed. The correction here refers to the internal modification for incorrect results.

7. The minor version number y (XYZ | x> 0) "must be must" increases progressively when a new feature with backward compatibility appears. When the function of any public API is marked as discarded, the value must be "must. Also, "may" increases progressively when a large number of new features or improvements are added to the internal program. "may" includes changes at the revision level. Each time the version number increments, the revision number must be "must" to zero.

8. The main version number x (XYZ | x> 0) "must be must", which increases progressively when any incompatible changes are added to the public API. "May" includes minor version number and revision level changes. When the primary version number increases, the minor version number and revision number "must be must.

9. The prefix "may" is marked after the revision, followed by a connection number and a series of Logo symbols separated by periods. The "must be must" is composed of English ASCII code numbers and Connection Numbers [0-9a-za-z-], and the "prohibit must not" is left blank. The digital identifier "Do Not Allow must not" to be filled with zero in front. The priority of the first version is lower than the associated standard version. The first version number indicates that the version is not stable and may not meet the compatibility requirements. Example: 1.0 ??. 0-Alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, and 1.0.0-x.7.z. 92.

10. The version compilation information "may" is marked after the revision or the first version number. It is decorated with a plus sign and a series of Mark symbols separated by periods. The "must be must" is composed of ASCII english numbers and the connection number [0-9a-za-z-], and the "prohibit must not" is left blank. When determining the priority level of a version, the version compilation information "shocould" is ignored. Therefore, the two versions are at the same priority level only when the version compilation information is different. Example: 1.0.0-Alpha + 001, 1.0.0 + 20130313144700, 1.0.0-Beta + exp. sha.4154f85.

11. The version priority level refers to how different versions are compared during sorting. When determining the priority level, "must be must" splits the version into major version numbers, minor version numbers, revision numbers, and first version numbers in sequence for comparison (version compilation information is not included in this comparison list ). Compare each identifier in sequence from left to right. The first difference value is used to determine the priority level: the primary version number, minor version number, and revision number are compared by numerical value, for example, 1.0.0 <2.0.0 <2.1.0 <2.1.1. When the primary version number, minor version number, and revision number are the same, it is determined by the first version number with a lower priority level. For example, 1.0.0-Alpha <1.0.0. There are two advance versions with the same primary version number, minor version number, and revision number. The priority level "must be must" is compared by each separated by periods from left to right, after finding a difference value, it is determined that only the numbers are marked and compared with numbers. If there are letters or connection numbers, they are compared in ASCII order. A number has a lower priority level than a non-numeric one. If all the start symbols are the same ?? The priority level of the first version with many BITs is relatively high. Example: 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-Alpha.

Why use semantic version control?

This is not a new or revolutionary idea. In fact, you may already be doing something similar. The problem is that "Approximation" is not enough. Without a formal specification, the version number does not have any substantive significance for dependency management. Naming and clearly defining the above ideas makes it easy for you to express your intentions to software users. Once these intentions become clear, the dependency specifications of elasticity (but not too flexible) can be achieved.

A simple example shows how semantic version control makes dependency hell a thing of the past. Suppose there is a function library named "Fire train", and it needs another tool named "ladder" that already uses semantic version control. When a rescue train is created, the ladder version is 3.1.0. Because the rescue train uses some new features in version 3.1.0, you can safely specify that the version numbers that depend on the ladder are greater than 3.1.0 but less than 4.0.0. In this way, when ladder versions 3.1.1 and 3.2.0 are released, you can include them directly in your suite management system because they are compatible with the original dependent software.

As a responsible developer, make sure that the operations of each package upgrade are consistent with the version number. The real world is complex, and we do not have much to do except to be alert. What you can do is to make semantic version control provide you with a sound way to release and upgrade suites, without the need to launch new dependent suites, saving you time and trouble.

If you agree with this and want to immediately start using semantic version control, you only need to declare that your library is using it and follow these rules. Please keep this link in your readme file to let others know and benefit from these rules.

FAQ in the initial development phase of 0. Y. Z, how do I implement version control?

The simplest method is to use 0.1.0 as your initial development version and increase the version number at each release.

How can I determine the time to release version 1.0.0?

When your software is used in a formal environment, it should have reached version 1.0.0. If you have a stable API that is depended on by users, it will also be version 1.0.0. If you are worried about backward compatibility, it should be 1.0.0.

Will this not impede rapid development and iteration?

When the primary version is zero, it is used for rapid development. If you change the API every day, you should still be in the stage where the main version number is zero (0.yz) or in the independent development branch of the next main version.

For public APIs, if the smallest but incompatible change requires a new major version number, will it soon reach version 42.0.0?

This is a question of development responsibility and foresight. Incompatible changes should not be easily added to software with many code dependencies. The price for upgrading may be huge. To incrementally release incompatible revisions with the primary version number, you must carefully consider the impact of these changes and evaluate the cost and benefit ratio involved.

Writing files for the entire public API is too troublesome!

Software for use by others ?? Writing appropriate documents is your responsibility as a professional developer. Maintaining project efficiency is a very important part of controlling the complexity of the software. If no one knows how to use your software or what functions are called reliably, it is difficult to control the complexity. In the long run, semantic version control and adherence to good standards for public APIs allow everyone and everything to run smoothly.

What should I do if I use an incompatible version as a minor version number and release it?

Once you find that you have broken the semantic version control specification, You need to correct the problem and release a new version number to correct the problem and restore backward compatibility. In this case, you cannot modify the released version. If possible, record the problematic version number to the file and tell the user where the problem is located, so that they can realize that this is a problematic version.

What if I updated my dependency but did not change the public API?

Since public APIs are not affected, this can be considered compatible. If a software and your suite have a common dependency, it will have its own dependency specification, and the author will also inform you of possible conflicts. To determine whether a revision belongs to the revision level or the next version level, you must update the dependency to fix the problem or add new features. For the latter, I often expect more code, which is obviously an increment of the version number level.

What if I change the public API but accidentally fail to follow the version number? (Meaning that significant and incompatible changes are mistakenly added to the Code in the release of the revision level)

Make the best judgment on your own. If you have a large user group that will be greatly affected when you change the behavior based on the intention of the public API, you 'd better publish the main version, even strictly speaking, this fix is only for the publication of revision levels. Remember, semantic version control is to convey meaning through version changes. If these changes are important to your users, let them know through the version number.

How can I deal with the function that is about to be deprecated?

Discarding existing functions is a common practice in software development, and is usually necessary for moving forward. When you discard some public APIs, you should do two things: (1) update your file to let the user know the change, (2) release the obsolete feature with the new version number at an appropriate time. Before the new main version completely removes the discard function, at least one version must contain this discard information so that the user can smoothly transfer to the new version of the API.

Does the semantic version have a limit on the string length of the version?

No. Please make proper judgment on your own. For example, the version that grows to 255 characters is too exaggerated. Furthermore, specific systems may have their own limits on the string length.

About

The Semantic version control specification was established by Tom Preston-Werner, founder of gravatars and co-founder of GitHub.

If you have any suggestions, please ask your questions on GitHub.

Semantic versioning semantic version number