Anonymous avatar Anonymous committed 9ec489b

starting the intro

Comments (0)

Files changed (1)

 verlib
 ======
 
+Being able to manage version numbers for a project is mandatory to properly
+release it.
+
+In Python there are no real restriction yet on how a project should manage 
+its versions, and how they should be incremented.
+
+While there are a few conventions widely used, like having a major and
+a minor revision (1.1, 1.2, etc.), developers are free to put in the `version` 
+metadata any string they want, and push a new release at PyPI. This version 
+will appear as the `latest` for end users.
+
+Some project are also using dates as their major version numbers, or a custom
+versioning standard that are sometimes quite exotic.
+
+The problem with this freedom, is that the package will be harder to re-package
+for OS packagers, that need to have stricter conventions.
+
+Existing versioning systems
+===========================
+
+There are two main version comparison systems:
+
+- Distutils 
+- Setuptools
+
+Distutils, provides a `StrictVersion` and a `LooseVersion` class that can be
+used to manage versions, but the
+XXX
+Python developer manager
+
+
+Setuptools
+==========
+
+Setuptools, that provides a version parsing system
+XXX
+
+The major problem with setuptools' versioning was that it was too permissive. 
+Many of the versions on PyPI are obviously not useful versions, which makes it 
+difficult for users to grok the versioning that a particular package was
+using and to provide tools on top of pypi. 
+
+While setuptools *does* provide a mechanism for comparing/sorting versions, 
+it is much preferable if the versioning spec is such that a human can make a
+reasonable attempt at that sorting without having to run it against
+some code.
+
+Also there's a problem is the use of dates at the "major" version number 
+(e.g. a version string "20090421") with RPMs: it means that any attempt to 
+switch to a more typical "major.minor..." version scheme is problematic because 
+it will always sort less than "20090421".
+
+XXX
+
+What is verlib
+==============
+
 ``verlib`` provides a version managment system.
 
 The pseudo-format supported is::
 
     N.N[.N]+[abc]N[.N]+[.(dev|post)N+|(devNpostN)]
 
+
 XXX explain why it's better than setuptools, from debian/red-hat PoV
 
 XXX explain here in details (no code example)
 XXX give tons of examples
 
+
 RationalVersion
 ===============
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.