Version number naming rules
Reprinted address: https://semver.org/lang/zh-CN/
Semantic version 2.0.0
Summary
Version format: major version number. Minor version number. Revision number. The rules for incrementing the version number are as follows:
- Major version number: When you make incompatible API changes,
- Minor version number: When you make a new feature for backward compatibility,
- Revision number: When you made a fix for backward compatibility issues.
The advanced version number and version compilation metadata can be added after the "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 "dependency hell." The larger the system, the more packages you join, and the more likely you are to find yourself in despair someday.
Publishing a new version of the package on a highly dependent system may soon become a nightmare. If the dependency is too high, you may face the risk of version control being locked (you must revise each dependency package to complete a certain upgrade). If the dependencies are too loose, it will be impossible to avoid the chaos of versions (assuming that multiple versions compatible with the future have exceeded a reasonable number). When the progress of your project becomes blocked and the version chaos is not simple and reliable, it means that you are in a hell of dependence.
As one of the solutions to this problem, I propose to use a simple set of rules and conditions to restrict the configuration and growth of version numbers. These rules are based on (but not limited to) conventions that have been widely used by various closed and open source software. In order for this theory to work, you must first have a well-defined public API. This can be achieved through document definitions or code enforcement requirements. In any case, the clarity of this API is very important. Once you define the public API, you can explain your changes to everyone by modifying the corresponding version number. Consider using such a version number format: XYZ (major version number. Minor version number. Revision number) when the problem is fixed but does not affect the API, increment the revision number; when the API remains backward compatible with new and modified, increment the minor version number; When making incompatible changes, increment the major version number.
I call this system "semantic version control". Under this set of conventions, the version number and its update method contain information about the underlying code and modified content between adjacent versions.
Semantic version control specification (SemVer)
The following keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, OPTIONAL are interpreted according to RFC 2119. (Annotation: In order to keep the sentence smooth, the keywords encountered in the following documents will be translated in accordance with the semantics of the entire sentence, and no individual translation will be performed here.)
-
Software using semantic versioning must (MUST) define a public API. The API can be defined in the code or appear in a rigorous file. Whatever the form, it should strive for accuracy and completeness.
-
The standard version number must (MUST) be in XYZ format, where X, Y, and Z are non-negative integers, and MUST NOT pad zeros in front of the number. X is the major version number, Y is the minor version number, and Z is the revision number. Each element must (MUST) increase in value. For example: 1.9.1-> 1.10.0-> 1.11.0.
-
After the software marked with the version number is released, MUST NOT change the contents of the software of that version. Any changes must (MUST) be released in a new version.
-
Software with a major version number 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 considered a stable version.
-
The version number of 1.0.0 is used to define the formation of the public API. After this version, all version number updates are based on the public API and its modifications.
-
The revision number Z (xyZ
|x> 0) must (MUST) be incremented only when a downward compatible correction is made. The corrections here refer to internal changes made for incorrect results. -
The minor version number Y (xYz
|x> 0) must (MUST) be incremented when new features that are backward compatible appear. It must also be incremented (MUST) when the functionality of any public API is marked as deprecated. May (MAY) increments when a large number of new functions or improvements are added to the internal program, which may include changes in the revision level. Whenever the minor version number is incremented, the revision number must (MUST) be reset to zero. -
The major version number X (Xyz
|X> 0) must (MUST) be incremented when any incompatible changes are added to the public API. Among them may (MAY) including minor version number and revision level changes. Whenever the major version number is incremented, the minor version number and revision number must (MUST) be reset to zero. -
The leading version number (MAY) can be marked after the revision, first add a connection number and then a series of identifiers separated by periods to modify. The identifier must (MUST) be composed of ASCII alphanumerics and the connection number [0-9A-Za-z-], and MUST NOT be left blank. Digital identifiers MUST NOT zero-fill in front. The predecessor version has lower priority than the associated standard version. Being labeled with the advanced version number 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.
-
The version compilation metadata can be (MAY) marked after the revision or prior version number, followed by a plus sign followed by a series of identifiers separated by periods. The identifier must (MUST) be composed of ASCII alphanumerics and the connection number [0-9A-Za-z-], and MUST NOT be left blank. When judging the priority level of the version, the version compilation metadata can be ignored. Therefore, when the two versions differ only in the version compilation metadata, they belong to the same priority level. Examples: 1.0.0-alpha + 001, 1.0.0 + 20130313144700, 1.0.0-beta + exp.sha.5114f85.
-
The priority level of versions refers to how different versions are compared when sorting. When judging the priority level, you must (MUST) split the version in order of major version number, minor version number, revision number and prior version number for comparison (version compilation metadata is not in this comparison list). Compare each identifier in order from left to right. The first difference value is used to determine the priority level: major version number, minor version number and revision number are compared by value, for example: 1.0.0 <2.0.0 <2.1.0 <2.1.1. When the major version number, minor version number, and revision number are the same, it is determined by the prior version number with a lower priority level. For example: 1.0.0-alpha <1.0.0. There are two leading version numbers with the same major version number, minor version number and revision number, and their priority levels must (MUST) be compared through each period-separated identifier from left to right until a difference is found Decision: Identifiers with only numbers are compared with the numerical value, and when there are letters or connection numbers, they are compared with each other in ASCII order. Digital identifiers have a lower priority than non-numeric identifiers. If the identifiers at the beginning are the same, the previous version number with more fields has higher priority. 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.
Why use semantic versioning?
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. If there is no formal specification to follow, the version number has no substantive meaning for dependency management. Naming the above ideas and giving them a clear definition makes it easy for you to convey your intentions to software users. Once these intentions become clear, flexible (but not too flexible) dependent specifications can be achieved.
A simple example can show how semantic version control makes dependency hell a thing of the past. Suppose there is a library called "Firetruck", it needs another package called "Ladder" and already has semantic versioning. When the firetruck was created, the version number of the ladder was 3.1.0. Because Firetruck uses some of the new features in version 3.1.0, you can safely specify that the version number that depends on the ladder is 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 include them directly in your package management system because they are compatible with the original dependent software.
As a responsible developer, you should ensure that the operation of each package upgrade is consistent with the version number. The real world is complicated, and there is not much we can do except to increase our vigilance. All you can do is let semantic version control provide you with a sound way to release and upgrade packages without the need to launch new dependent packages, saving you time and trouble.
If you agree with this and want to start using semantic versioning immediately, you just need to declare that your library is using it and follow these rules. Please keep this page link in your README file to let others know these rules and benefit from them.
FAQ
In the initial development stage of 0.yz, how do I perform version control?
The easiest way is to use 0.1.0 as your initial development version, and increment the minor version number with each subsequent release.
How to judge when 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 already have a stable API that users rely on, it will be version 1.0.0. If you are worried about backward compatibility, it should be considered version 1.0.0.
Won't this hinder rapid development and iteration?
When the major version number is zero, it is for rapid development. If you are changing the API every day, then you should still be at the stage where the major version number is zero (0.yz), or in the independent development branch of the next major version.
For public APIs, if even the smallest but incompatible changes require a new major version number, would n’t it reach version 42.0.0 soon?
This is a question of development responsibility and forward-looking. Incompatible changes should not be easily added to software with many dependent codes. The cost of upgrading can be enormous. To increment the major version number to issue incompatible revisions means that you must think carefully about the impact of these changes and evaluate the cost and benefit ratios involved.
Writing documents for the entire public API is too much trouble!
It is your responsibility as a professional developer to write appropriate files for software for others to use. A very important part of keeping a project efficient is to control the complexity of the software. If no one knows how to use your software or does not know which function calls are reliable, it will be difficult to control the complexity. In the long run, the use of semantic versioning and good adherence to public APIs will allow everyone and everything to run smoothly.
What if I accidentally release an incompatible revision as a minor version number?
Once you find that you have broken the specification of semantic versioning, you must fix the problem and issue a new minor version number to correct the problem and restore backward compatibility. Even in this case, you cannot modify the released version. If possible, record the problematic version number in the file and tell the user where the problem is, so that they can realize that this is the problematic version.
What if I update my dependencies but do not change the public API?
Since it does not affect the public API, this can be considered compatible. If a certain software and your package have a common dependency, it will have its own dependency specification, and the author will also inform about possible conflicts. To determine whether the revision is a revision level or a sub-version level, it is based on your updated dependencies to fix problems or add new features. For the latter, I often expect to be accompanied by more code, which will obviously be an increment of the minor version number level.
What if I change the public API but inadvertently do not follow the version number change? (Meaning that in the release of the revision level, major and incompatible changes were mistakenly added to the code)
Make your own best judgment. If you have a large user base that will be greatly affected by changing the behavior in accordance with the intent of the public API, it is best to do a major version release, even if strictly speaking this fix is only a revision level release. Remember, semantic version control is to convey meaning through the change of version number. If these changes are important to your users, then explain to them through the version number.
What should I do with the features that will be deprecated?
Abandoning existing features is commonplace in software development, and is usually necessary to move forward. When you deprecate part of the public API, you should do two things: (1) update your file to let users know about the change, (2) deprecate the feature at a suitable time through the new minor version release. Before the new major version completely removes the deprecation function, at least one minor version contains this deprecation information, so that users can smoothly transfer to the new version of the API.
Does the semantic version limit the string length of the version?
No, please make appropriate judgments yourself. For example, the 255-character version is overblown. Furthermore, certain systems may have their own restrictions on the length of the string.
on
The specification for semantic version control was established by Tom Preston-Werner , founder of Gravatars and co-founder of GitHub .
If you have any suggestions, please post your questions on GitHub .
license
