Change title

Change title of the guide.
Update FAQ.
Light changes in the text.

Author: gshep

libver.md

@@ -1,13 +1,12 @@
-Library Versioning 0
-====================
+3D Library Versioning 1
+=======================
 
 Summary
 -------
 
 Given a version number MAJOR.MINOR.PATCH, increment the:
 
-1. MAJOR version when you make source incompatible API changes or
-    start new generation of the library,
+1. MAJOR version when you make source incompatible API changes,
 1. MINOR version when you add functionality that preserves source
     compatibility (binary compatibility may be broken), and
 1. PATCH version when you make bug fixes guaranteed both binary and source
@@ -47,13 +46,13 @@ change that fixes incorrect behavior.
 If binary compatibility is broken by the patch then minor
 version MUST be incremeted (see the next item). The current version (before
 'fix') MUST remain the last in the x.y-branch. For example: there is
-version 1.2.43 and a bug fix does not break binary compatibility so
-new version is 1.2.44, i.e. 1.2.43 -> 1.2.44.
+the version 1.2.43 and a bug fix does not break binary compatibility so
+the new version is 1.2.44, i.e. 1.2.43 -> 1.2.44.
 If a bug fix breakes binary compatibility then the new version MUST be 1.3.0
-and after that 'fix' there MUST NOT exist 1.2.44.
+and after that 'fix' there MUST NOT exist 1.2.44, 1.2.45 and so on.
 
-1. Minor version Y (x.Y.z) MUST be incremented if new, backwards
-compatible functionality is introduced to the public API. The changes MUST
+1. Minor version Y (x.Y.z) MUST be incremented if new
+functionality is introduced to the public API. The changes MUST
 NOT break source compatibility. The changes MAY break binary compatibility.
 It MUST be incremented if any public API
 functionality is marked as deprecated. It MAY be incremented if substantial
@@ -64,7 +63,7 @@ If source compatibility is broken by the minor changes then major
 version MUST be incremeted (see the next item). The current version (before
 the changes) MUST remain the last in the x-branch.
 For instance: 1.5.6 -> 1.6.0 --- source compatibility saved,
-1.5.6 -> 2.0.0 --- source compatibility broken (1.5.7, 1.5.8 and so
+1.5.6 -> 2.0.0 --- source compatibility broken (1.5.7, 1.5.8 and so on
 MUST NOT exist).
 
 1. Major version X (X.y.z) MUST be incremented if any
@@ -74,92 +73,35 @@ be reset to 0 when major version is incremented. For instance:
 2.6.73 -> 3.0.0.
 
 1. Version MUST NOT contain any other information (build, date,
-configurations, names, etc). Any such information MUST BE included
-directly to the library as specific functions/methods and
-duplicated in ChangeLogs/READMEs/etc.
+configurations, names, etc). Any such information MUST BE provided
+directly by the library as specific interface(s) and
+documented in ChangeLogs/READMEs/etc.
 
 FAQ
 ---
 
-### How should I deal with revisions in the 0.y.z initial development phase?
+### What does '3D' in the name mean?
 
-The simplest thing to do is start your initial development release at 0.1.0
-and then increment the minor version for each subsequent release.
+It means three digits or decimals. Actually title of
+the guide should be read as 'how to version a library
+with three digits/decimals?'.
 
-### How do I know when to release 1.0.0?
+### Therefore may there exist '2D', '4D', ... patterns of versioning?
 
-If your software is being used in production, it should probably already be
-1.0.0. If you have a stable API on which users have come to depend, you should
-be 1.0.0. If you're worrying a lot about backwards compatibility, you should
-probably already be 1.0.0.
+To tell the truth, yes.
 
-### Doesn't this discourage rapid development and fast iteration?
+But at first let's consider versioning with one or two digits.
+For shared libraries of compiled languages there are at least
+two the most important issues: API (source compatibility) and
+ABI (binary compatibility). To reflect changes
+in API/ABI of a library two digits are required. Also
+a developer needs to version bugfixes of a library.
+Therefore, three decimals are the minimum possible count of
+decimals to version a library.
 
-Major version zero is all about rapid development. If you're changing the API
-every day you should either still be in version 0.y.z or on a separate
-development branch working on the next major version.
+TODO about '4d' and so  on.
 
-### If even the tiniest backwards incompatible changes to the public API require a major version bump, won't I end up at version 42.0.0 very rapidly?
-
-This is a question of responsible development and foresight. Incompatible
-changes should not be introduced lightly to software that has a lot of
-dependent code. The cost that must be incurred to upgrade can be significant.
-Having to bump major versions to release incompatible changes means you'll
-think through the impact of your changes, and evaluate the cost/benefit ratio
-involved.
-
-### Documenting the entire public API is too much work!
-
-It is your responsibility as a professional developer to properly document
-software that is intended for use by others. Managing software complexity is a
-hugely important part of keeping a project efficient, and that's hard to do if
-nobody knows how to use your software, or what methods are safe to call. In
-the long run, Semantic Versioning, and the insistence on a well defined public
-API can keep everyone and everything running smoothly.
-
-### What do I do if I accidentally release a backwards incompatible change as a minor version?
-
-As soon as you realize that you've broken the Semantic Versioning spec, fix
-the problem and release a new minor version that corrects the problem and
-restores backwards compatibility. Even under this circumstance, it is
-unacceptable to modify versioned releases. If it's appropriate,
-document the offending version and inform your users of the problem so that
-they are aware of the offending version.
-
-### What should I do if I update my own dependencies without changing the public API?
-
-That would be considered compatible since it does not affect the public API.
-Software that explicitly depends on the same dependencies as your package
-should have their own dependency specifications and the author will notice any
-conflicts. Determining whether the change is a patch level or minor level
-modification depends on whether you updated your dependencies in order to fix
-a bug or introduce new functionality. I would usually expect additional code
-for the latter instance, in which case it's obviously a minor level increment.
-
-### What if I inadvertently alter the public API in a way that is not compliant with the version number change (i.e. the code incorrectly introduces a major breaking change in a patch release)
-
-Use your best judgment. If you have a huge audience that will be drastically
-impacted by changing the behavior back to what the public API intended, then
-it may be best to perform a major version release, even though the fix could
-strictly be considered a patch release. Remember, Semantic Versioning is all
-about conveying meaning by how the version number changes. If these changes
-are important to your users, use the version number to inform them.
-
-### How should I handle deprecating functionality?
-
-Deprecating existing functionality is a normal part of software development and
-is often required to make forward progress. When you deprecate part of your
-public API, you should do two things: (1) update your documentation to let
-users know about the change, (2) issue a new minor release with the deprecation
-in place. Before you completely remove the functionality in a new major release
-there should be at least one minor release that contains the deprecation so
-that users can smoothly transition to the new API.
-
-### Is there any size limit on the version string?
-
-No, but use good judgment. A 255 character version string is probably overkill,
-for example. Also, specific systems may impose their own limits on the size of
-the string.
+See also original FAQ at http://semver.org
 
 About
 -----