Semantic version 2.0.0_ version control

Transferred from http://semver.org/lang/zh-CN/

Semantic version of 2.0.0 summary

Version format: Major version number. minor version number. Revision number, the version number increment rule is as follows: Major version number: When you do incompatible API modifications, the minor version number: When you do a backward-compatible functionality add, revise number: When you do a backward-compatible problem fix.

The advance version number and version compilation information can be added to the back of the "major version number. minor version number. Revision number" as an extension. Brief introduction

In the realm of software management there is the valley of death called "hell-dependent", and the larger the system, the more packages you have, the more likely you are to find yourself in despair one day in the future.

Publishing a new version of this kit in a highly dependent system can be a nightmare soon. If the dependencies are too high, you may face the risk of version control being locked out (you must have a revision of each dependent package to complete an upgrade). If the dependencies are too loose, the version confusion will not be avoided (assuming that multiple versions compatible with the future have exceeded a reasonable number). When your project progresses because version dependencies are locked or version clutter becomes less simple and reliable, it means you are in a hell of a dependency.

As one of the solutions to this problem, I propose to constrain the configuration and growth of version numbers with a simple set of rules and conditions. These rules are designed on the basis of, but not limited to, practices that have been widely used by various closed and open source software. In order for this theory to work, you have to have a well-defined public API first. This can be done through file definitions or code coercion requirements. In any case, it is important that this set of APIs be clearly understood. Once you have defined the public API, you can change the corresponding version number to show you the changes. Consider using this version number format: XYZ (major version number. minor version number. Revision number) to fix the problem without affecting the API, increment the revision number, and the API to keep backward-compatible additions and modifications, increment the minor version number, and make backward-compatible modifications, incrementing the major version number.

I call this system "semantic versioning," under which the version number and its update include information about the underlying code and the 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, and OPTIONAL are interpreted in accordance with the description of RFC 2119. In order to keep the sentence smooth, the following documents encountered the key words will be translated in accordance with the whole sentence semantics, in this first no individual translation. ）

Software that uses semantic versioning "must must" defines a public API. The API can be defined in code or appear in a rigorous file. Any form should be precise and complete.

The standard version number "must be must" in XYZ format where X, Y, and Z are non-negative integers, and "Prohibit must not" is up to 0 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 be must" to increment by numeric value. For example: 1.9.1-> 1.10.0-> 1.11.0.

The "Prohibit must not" changes the content of the software after the release of the labeled version number. Any modifications are "must be must" to be released in a new version.

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

The 1.0.0 version number is used to define the formation of public APIs. After this release, all version number updates are based on the public APIs and their modifications.

Revision number Z (x.y.z | X > 0 "must be must" is incremented only for backward-compatible revisions. The amendment here refers to an internal modification of an incorrect result.

Minor version number Y (x.y.z | X > 0 "must be must" is incremented when new features with backward compatibility are present. The function of any public API is marked as discarded and "must be must" increments. Also "may" is incremented when an internal program has a large number of new features or improvements are added, where "may" includes changes in revision levels. Every time the minor version number increments, the revision number "must be must" to zero.

Major version number X (x.y.z | X > 0) "must be must" increments when any incompatible modifications are added to the public API. Where "can may" includes minor version number and revision level change. Every time the major version number increments, the minor version number and revision number "must be must" to zero.

The advance version number "May" is marked in the revision, preceded by a connection number and a series of delimited identification symbols to decorate. The identifier "must be must" consists of the English digits of the ASCII code and the connection number [0-9a-za-z-], and the "Prohibit must not" is left white. The digital identifier "prohibit must not" in front of the 0. The advance version has a lower priority than the associated standard version. The marked Advance version number indicates that this version is not stable and may not meet the requirements of compatibility. Example: 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 Information "may" is labeled with the revision or the advance version number, preceded by a plus sign plus a series of dotted-delimited identification symbols. The identifier "must be must" consists of the English digits of ASCII and the connection number [0-9a-za-z-], and "Prohibit must not" from being white. Version compilation Information "Can be SHOULD" is ignored when determining the priority level of a version. Therefore, when two versions only differ in version compilation information, they fall into the same priority level. Example: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.

The priority level of a version refers to how different versions compare when they are sorted. When you determine the priority level, you must must the version by splitting the master version number, minor version number, revision number, and advance version number (version compilation information is not in the list of comparisons). Each identifier is compared from left to right, and the first difference value is used to determine the priority level: major, minor, and revision numbers, for example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. When the major, minor, and revision numbers are the same, they are changed to a lower priority version number. For example: 1.0.0-alpha < 1.0.0. Two advance version numbers with the same major, minor, and revision numbers, its priority level "must be must" is compared by each period-delimited identifier symbol from left to right until a difference value is found: Only the number of the identifiers is compared to the numeric value, with the letters or connection numbers verbatim, in ASCII The sort to compare. The number's identity symbol has a lower priority than the non-numeric identifier. If the beginning of the identity symbol is the same, the field of more than the advance version number priority level is higher. 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-r C.1 < 1.0.0. Why do you want to make the version control of the semantics.

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 is not meaningful for dependency management. Naming and giving clear definitions of the above ideas makes it easy for you to communicate your intentions to the users of the software. Once these intentions become clear, the flexible (but not too flexible) dependency specification can be achieved.

A simple example will show how semantic versioning makes it possible to rely on hell for the past. Suppose there is a function library called "Fire Truck," which requires another suite named "Ladder" and already has a version control for the semantics of the language. When the fire engine was created, the ladder version number was 3.1.0. Because fire trucks use some version of the new features of 3.1.0, you can safely specify that the version number of the ladder is equal to 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 incorporate them directly into your suite management system because they can be compatible with pre-existing software dependencies.

As a responsible developer, you should make sure that each suite upgrade works in accordance with the version number. The real world is complex, and we can do little more than raise our vigilance. All you can do is let the semantic version control provide you with a sound way to distribute and upgrade the suite without having to launch a new dependency suite to save you time and trouble.

If you agree with this and want to start using semantic versioning immediately, you just have to declare that your library is using it and follow these rules. Please keep this page link in your README file so that others know the rules and benefit from it. FAQ in the initial development phase of 0.y.z, how do I control versioning.

The easiest way to do this is to use 0.1.0 as your initial development version and to increment the minor version number for each subsequent release. How to judge the timing of releasing the 1.0.0 version.

When your software is used in the formal environment, it should have reached version 1.0.0. If you already have a stable API to be relied upon by the user, it will also be a 1.0.0 version. If you are worried about backward-compatible issues, it should be considered a 1.0.0 version. This does not hinder rapid development and iteration.

The major version number is zero for rapid development. If you are changing the API every day, you should still be in the major version zero phase (0.Y.Z), or in the next major version of the stand-alone Development branch. For the public API, if even the smallest but not backward-compatible changes need to produce a new major version number, it will soon reach 42.0.0 version.

This is the development of a sense of responsibility and forward-looking issues. Incompatible changes should not be easily added to software that has a lot of dependent code. The cost of an upgrade can be huge. To increment the major version number to issue an incompatible revision means you have to be thoughtful about the impact of these changes and evaluate the cost and benefit ratios involved. Writing files for the entire public API is too much trouble.

Writing appropriate files for the software you use for others is your responsibility as a professional developer. A very important part of keeping a project efficient is controlling the complexity of the software, and it can be difficult to control complexity if no one knows how to use your software or what function calls are reliable. In the long run, it is possible to keep everyone and everything running smoothly by making semantic versioning and a good standard of public APIs. What if you accidentally put an incompatible revision as a minor version number.

Once you find yourself breaking the code for semantic versioning, fix the problem and issue a new minor version number to correct the problem and restore backward compatibility. Even in this case, it is not possible to modify the published version. If you can, log the problematic version number to the file, tell the user the problem, and let them be aware that it is a problematic version. What if I update my dependencies without changing the public API.

This can be assumed to be compatible because it does not affect the public API. If a software and your suite have a common dependency, it will have its own dependency specification and the author will tell you about possible conflicts. To determine whether the revision is a revision or secondary level, it is based on your updated dependencies to fix the problem or add new features. For the latter, I often expect to be accompanied by more code, which is obviously incremented by a minor version number level. What if I change the public API but inadvertently do not follow the version number changes? (meaning that significant and incompatible changes are mistakenly added to the code in the revision level release)

Make the best judgments on your own. If you have a large user base that is greatly affected by changing behavior following 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 versioning is a way of conveying meaning through the change of version number. If these changes are important to your users, then use the version number to explain to them. How do I handle the features that are about to be deprecated.

Discarding existing functionality is a common occurrence in software development and is often necessary for forward development. When you discard a partial public API, you should do two things: (1) Update your files to let users know about the change, (2) Release the deprecated function at the right time through a new minor version number. Before the new major release completely removes the deprecated feature, at least one minor version contains the discard information so that the user can move smoothly to the new API. Does the semantic version have a limit on the length of the version string?

No, please make a proper judgment on your own. For example, a version of 255 characters long has been exaggerated. Furthermore, specific systems may have their own limitations for string lengths. About

The code for semantic versioning is established by Tom Preston-werner, co-founder of the Gravatars and GitHub co-founder.

If you have any suggestions, please go to GitHub to ask your questions. Authorized

Create CC name Mark 3.0 Unported License Terms http://creativecommons.org/licenses/by/3.0/