Semantic version of 2.0.0

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

Semantic Version 2.0.0 Summary

Version format: Major version number. minor version number. Revision number, the increment rule for the version number is as follows:

1. Major version number: When you make incompatible API modifications,
2. Minor version number: When you do a backwards-compatible functionality added,
3. Revision number: When you make a backward-compatible problem fix.

The prior version number and version compilation information can be added to the "major version number." Minor version number. The revision number is followed by an extension.

Brief introduction

In the field of software management there is a valley of death called "hell-dependent", the larger the system, the more packages you add, the more likely you will find yourself in despair in the future someday.

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

As one of the solutions to this problem, I propose to use a simple set of rules and conditions to constrain the configuration and growth of the version number. These rules are based on, but not limited to, the practices that have been widely used by various closed, open source software. In order for this theory to work, you have to have a well-defined public API first. This can be achieved through file definitions or code enforcement requirements. In any case, the clarity of this set of APIs is very important. Once you have defined the public API, you can change the corresponding version number to explain your changes. Consider using this version number format: XYZ (major version number, minor version number, revision number) fix the issue but do not affect the API, increment the revision number, add and modify the API to keep backwards-compatible, increment the minor version number, and when making non-compatible modifications, increment 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 content of the modification 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 in accordance with the narrative of RFC 2119. In order to keep the sentence smooth, the following documents encountered by the keyword will be translated according to the whole sentence semantics, in this first no individual translation. ）

2. Software that uses semantic versioning "must be must" to define a public API. The API can be defined in the code or appear in a rigorous file. No matter what form it is, you should strive for accuracy and completeness.

4. The standard version number "must be must" in XYZ format,?? Where X, Y, and Z are non-negative integers, and "Prohibit must not" is 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" is incremented by a number. For example: 1.11.0, 1.10.0, 1.9.1.

6. After the release of the software that marks the version number, "Prohibit must not" changes the content of this version of the software. Any modification "must be must" to be released in a new version.

8. 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.

10. The version number of the 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 its modifications.

12. Revision Z (x.y.z | X > 0) "must be must" is incremented only when a backward-compatible correction is made. The correction here refers to an internal modification of an incorrect result.

14. Minor version number Y (x.y.z | X > 0) "must be must" is incremented when new features that are backwards compatible are present. Also "must be must" incremented when the functionality of any public API is marked as deprecated. Also "may" is incremented when an internal program has a large number of new features or improvements added, where "may" includes changes to the revision level. Each time the minor version number increments, the revision number "must be must" to zero.

16. Major version number X (x.y.z | X > 0) "must be must" is incremented when any incompatible modifications are added to the public API. Where "may" includes minor version number and change of revision level. The minor and revision numbers "must be must" to zero whenever the major version number is incremented.

18. The prior version number "may" is labeled after the revision, with a connection number followed by a series of symbol symbols separated by periods. The identity symbol "must be must" consists of an ASCII code of English numerals and a connection number [0-9a-za-z-], and "Prohibit must not" to remain white. The digital identification symbol "Prohibit must not" in front of the complement 0. The priority of the advance edition is lower than the associated standard version. Being marked with a prior version number indicates that this version is not stable and may not meet the requirements for compatibility. Example: 1.0??. 0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.

20. Version compilation Information "May" is labeled after a revision or prior version number, plus a plus sign followed by a series of symbol symbols separated by periods to decorate. The identity symbol "must be must" consists of an ASCII English number and a connection number [0-9a-za-z-], and "Prohibit must not" to remain white. Version compilation Information "Can be should" is ignored when determining the priority level of a version. As a result, two versions belong to the same priority level only when the version compilation information is different. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.

22. The priority level of a version refers to how different versions are compared when sorting. When judging the priority level, "must be must" to split the version into the main version number, the minor version number, the revision number and the prior version number after the comparison (version compilation information is not in this comparison list). Each identity symbol 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 version number, minor version number and revision number are all the same, the priority level is lower than the prior version number. For example: 1.0.0-alpha < 1.0.0. With the same major version number, minor version number, and revision number of the two antecedent version number, its priority level "must be must" through each left-to-right by a period-delimited symbol to compare, until a difference value is found after the decision: only the number of the identification symbol with a numeric value, the letter or the connection number is verbatim ASCII The sort to compare. The identification symbol of a number is lower than the non-numeric identification symbol priority level. If the beginning of the logo are all the same, column?? A bit more advanced 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 should I control the versioning of the semantics?

This is not a new or revolutionary idea. In fact, you may already be doing something similar. The problem is that just "approximate" is not enough. If there is no formal specification to follow, the version number is of no practical significance for the management of dependencies. Naming these ideas and giving them a clear definition makes it easy for you to communicate your intentions to software users. Once these intentions become clear, flexible (but not too flexible) dependency specifications can be achieved.

As a simple example, you can show how semantic versioning makes dependency hell a thing of the past. Suppose you have a library called "Fire Truck," which requires another suite called "Ladder" and already has a set of semantics for versioning. When a fire truck is created, the ladder version number is 3.1.0. Because fire trucks use some of the new features of version 3.1.0, you can safely specify that the version number dependent on the ladder is equal to 3.1.0 but less than 4.0.0. This way, when the ladder versions 3.1.1 and 3.2.0 are released, you can incorporate them directly into your suite management system, as they are compatible with the existing software dependencies.

As a responsible developer, you should make sure that each package upgrade works in the same manner as the version number. The real world is complex, and we can do little more than be vigilant. All you can do is let the semantic versioning provide you with a robust way to publish and upgrade the suite without having to launch a new dependency package, saving you time and hassle.

If you agree and want to start using semantic versioning right away, you just have to declare that your library is using it and follow the rules. Please keep this page link in your README file to let others know and benefit from the rules.

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

The simplest approach is to use 0.1.0 as your initialization development version and increment the minor version number for each subsequent release.

How do I know when to publish a 1.0.0 version?

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

Does this hinder rapid development and iteration?

The major version number is zero for rapid development. If you are changing the API every day, then you should still be in the major version number zero phase (0.Y.Z), or in the next major version of the standalone Development branch.

For the public API, if even the smallest but not backwards compatible changes need to produce a new major version number, it will soon reach 42.0. version 0?

This is the development of a sense of responsibility and a forward-looking issue. Incompatible changes should not be easily added to software that has many dependencies on the code. The cost of an upgrade can be huge. Increasing the major version number to issue incompatible revisions means that 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 too much trouble!

Software for the use of others?? It is your responsibility as a professional developer to write the appropriate documentation. A very important part of keeping your project productive 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 functions are called reliably. In the long term, the adherence to semantic versioning and good standards for public APIs can make everyone and everything run smoothly.

What if I accidentally put an incompatible revision as the minor version number?

Once you find yourself destroying the semantic versioning specification, fix the problem and issue a new minor version number to correct the problem and restore backwards compatibility. Even in this case, it is not possible to modify the released version. If possible, log the problematic version number to the file and tell the user the problem, so that they can be aware that this is a problematic version.

What if I update my dependencies but do not change the public API?

This can be considered compatible because it does not affect the public API. If a software has a common dependency on your suite, it will have its own dependency specification, and the author will tell you about possible conflicts. To determine whether the revision is a revised level or sub-level, depending on your updated dependency is to fix the problem or add new features. For the latter, I often expect to be accompanied by more code, which will obviously be incremented at 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 release of the revision level)

Make the best judgment on your own. If you have a large user base that is affected by changes in behavior based on the intent of the public API, it is best to do a major release, even if the fix is strictly a revision-level release. Remember, semantic versioning is about changing the version number to convey meaning. If these changes are important to your users, explain them through the version number.

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

Discarding existing functionality is a common occurrence in software development and is often necessary to move forward. When you discard some of the public APIs, you should do two things: (1) Update your files to let the user know about the change, (2) Release the deprecated feature to the new minor version number at the appropriate time. Before the new major version completely removes the deprecated feature, at least one minor version will contain this deprecated information so that the user can smoothly transfer to the new version of the API.

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

No, please do your own proper judgment. For example, versions that grow to 255 characters are overly exaggerated. Furthermore, specific systems may have their own limitations on string lengths.

About

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

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

Authorized

Creative CC Name 3.0 Unported License Terms http://creativecommons.org/licenses/by/3.0/

Semantic version of 2.0.0