Preface

When we start project development, in order to facilitate project management, we need to define a version for the project. However, how should the project version number be written? Is it 1.0, or 0.1, or 1.0.0 or 0.0.1?

If 1.0.0 is used as the starting point, then the next version should be 1.0.1 or 1.1.0?

We often see the version number of some open source projects, and carry the suffix, such as 3.0.0-beta.0 of vue. or 18.0.0-rc.0 of react. What do these suffixes represent?

Semver specification

Using a good version number management solution can help us quickly understand the range of version changes.

This is not an innovative idea, in fact, you may already be doing something similar. The problem is that just "approximation" is not enough. If there is no formal specification to follow, the version number has no substantial significance for the management of dependencies. Name and give clear definitions to your software users to name and communicate your intentions. Once these intentions become clear, elastic (but not too elastic) dependency specifications can be achieved.

In the open source community, founder of Gravatars and co-founder of GitHub Tom Preston-Werner has established a semantic version control specification, semantic version, referred to as semver, which is called semver specification.

You can learn more about the semver specification at https://semver.org/lang/zh-CN/.

Version number format

Version format: Major version number, minor version number, revision number, we use X.Y.Z as the format alias.

Where X, Y and Z are non-negative integers, and zeros are prohibited before the number. X is the main version number, Y is the minor version number, and Z is the revision number. Each element must be incremented by (MUST) numerical value. For example 1.9.1 -> 1.10.0 -> 1.11.0.

Version Control Specifications

1. After the software marked with the version number is released, ** is prohibited to change the content of this version of the software. Any modification **must be released in a new version.

2. Software with the main version number zero (0.y.z) is in the initial stage of development and everything may be changed at any time. Such public APIs should not be considered stable versions.

3. The version number of 1.0.0 is used to define the formation of public APIs. All version number updates after this version are based on the public API and their modifications.

4. Revision number Z (x.y.Z | x > 0)** Must be incremented only when only backward compatible corrections have been made. The correction here refers to internal modifications made for incorrect results.

5. Secondary version number Y (x.Y.z | x > 0)** Must be incremented when new backward compatible features appear. ** Must be incremented when any public API's functionality is marked as deprecated. Also can increment when there are a lot of new features or improvements in the internal program are added, and can include changes at the revision level. Whenever the version number is incremented, the revision number ** must be zeroed.

6. Major version number X (X.y.z | X > 0)** Must be incremented when any incompatible modifications are added to the public API. Among them, ** can include changes in the subversion number and revision level. Whenever the major version number is incremented, the minor version number and revision number must be zeroed.

7. Pre-version number ** can be marked after the revision, and first add a connection number and then a series of period-delimited identifiers to modify. The identifier **must be composed of ASCII alphanumeric and connection number [0-9A-Za-z-] and **blank is prohibited. Digital identifier **No**Complete zeros in front. The predecessor version has a lower priority than the associated standard version. A pre-version number marked indicates that this version is not stable and may not meet the expected compatibility requirements. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.

8. Version compilation information ** can be marked after the revision or the previous version number, with a plus sign and a series of period-delimited identifiers. The identifier must be composed of ASCII alphanumeric and connection number [0-9A-Za-z-] and **blank is prohibited. When determining the priority level of the version, the version compilation information ** can be ignored. Therefore, when the two versions only have different versions of the version compilation information, they belong to the same priority level.

Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.

9. The priority level of the version refers to how different versions compare when sorting.

10. When judging the priority level, ** must split the version into the main version number, the secondary version number, the revision number and the predecessor version number in sequence and then compare it (The version compilation information is not in this comparison list).

11. Compare each identifier in sequence from left to right. The first difference value is used to determine the priority level: the main version number, the minor version number and the revision number are compared with numerical values.

For example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1.

3. When the main version number, minor version number and revision number are the same, the decision is made by a pre-version number with a relatively low priority level.

For example: 1.0.0-alpha < 1.0.0.

4. Two prior version numbers with the same major version number, minor version number and revision number, and their priority level ** Must be** through each period from left to right Delimited identifiers are compared until a difference value is found:

5. Only the identifiers of numbers are compared by the value level.

6. When there are letters or connection numbers, compare word by word in ASCII.

7. The identifier of a numeric is lower in priority than the identifier of a non-numeric.

8. If the identifiers at the beginning are the same, the priority level of the predecessor version numbers with more columns is higher.

For 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.0.

The incrementing rules are summarized as follows

• Major version number: When you make incompatible API modifications,
• Subversion number: When you make a backward compatible functionality,
• Revision number: Fixed when you made a backward compatibility issue.

The pre-version number and version compilation information can be added to the "main version number. minor version number. revision number" as an extension.

FAQ

How do I do version control during the initial development stage of 0.y.z?

The easiest way is to use 0.1.0 as your initial development version and increment the subversion number at each subsequent release.

How to determine the timing of release of version 1.0.0?

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

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

No, please make appropriate judgments on your own. For example, the 255-character version is overly exaggerated. Furthermore, specific systems may have their own limitations on string length.

Is "v1.2.3" a semantic version number?

"v1.2.3" is not a semantic version number. However, adding the prefix "v" before semanticizing the version number is a common practice to represent the version number. In version control systems, it is common to abbreviate "version" to "v". For example: in git tag v1.2.3 -m "Release version 1.2.3", "v1.2.3" represents the tag name, while "1.2.3" is the semantic version number.

alpha, beta, rc

In the specification, the characters after - in the previous version are customized, and we can often see the identifiers used by some open source libraries such as alpha, beta, and rc.

Generally speaking, these identifiers represent the following meanings:

• alpha: means the internal test version. It is mainly provided for internal development and testing use, and is not recommended for users to download.
• beta: means a public beta version. Users can try some features in advance.
• rc: Indicates the preview version. It means that this version will no longer add new features, and there may be some bugs. After the fix is ​​completed, the official version will be reached.

npm Specify the version range

We can see symbols such as ^ or ~ before the version number, such as:

{
  "vuepress": "^1.9.7",
  "vue": "~2.7.11"
}

These symbols indicate the allowable range for later installation versions of this library.

Common characters include: ^, ~, >, <, <=, >=, etc.

^ represents the update of the subversion number. For example, ^1.2.3 represents the later version >=1.2.3 <2.0.0. But if the main version number is 0, for example ^0.2.3 is equivalent to >=0.2.3 <0.3.0; ^0.0.3 is equivalent to >=0.0.3 <0.0.4.

~ means an update of the revision number. For example, ~1.2.3 means a later version >=1.2.3 <1.3.0.

Full version scope description, view npm documentation