A while back I proposed changing the way the ``django.VERSION`` tuple is set up. That discussion petered out a bit, until I brought it up with Jacob just before the 1.0 release. At the time, we felt it wasn't possible to do it before we rolled 1.0 (this was, due to my absent-mindedness, about ten minutes before we tagged the release, so it's my fault this didn't happen prior to 1.0), but now I'd like to revisit this and get it done so we have something a bit more sensible going forward.
I'm writing this mostly as an explanation of what I plan to do; if there aren't any well-founded objections, I'll make the necessary changes and commit them before we create the 1.0.x branch. The problems with the current scheme ==================================== Right now, ``django.VERSION`` is a 3-tuple whose format has been known to vary wildly according to what we're doing at a given moment. This has led to two major problems: 1. Because the third item in the ``VERSION`` tuple has been used for qualifiers like 'pre', 'beta', etc., we only have two items available for the actual version number. This has been known to cause hilarious results in the case of releases like, say, 0.96.3, which has to be (0, 96.3, None) (stop and think about how IEEE floats get printed, and you'll see the issue here). 2. That third item has never followed any really predictable format, except for the period of the 1.0 alpha/beta releases. This makes it difficult to tell what sort of Django codebase you're looking at without thinking about it and possibly doing some archaeology. I don't see any good way to deal with these issues while retaining the current 3-tuple, so... The format of ``django.VERSION`` going forward ============================================== Based on a good suggestion from Steve Holden, I'm going to change ``django.VERSION`` to follow, as closely as possible, the format of Python's own ``sys.version_info``. This means it will become a 5-tuple, whose elements are, in order: major version, minor version, micro version, release level, serial. The Python docs don't actually define these terms clearly, but for Django's use I'm going to lay out what these mean and what values they can take, inferring at times from how Python's done it (I've been reading the history of Include/patchlevel.h to get a feel for the way that's evolved over time... fun fun). So here goes: "major" The major version number of the Django release, e.g., 1 for the 1.x releases. "minor" The minor version number of the Django release, e.g., 0 for the 1.0.x releases, 1 for the 1.1.x release, etc. "micro" The micro version number of the Django release, e.g., 1 for a release number 1.0.1, 2 for a release number 1.0.2, etc. "release level" A short string describing the type of release. Value will be one of: "alpha", "beta", "rc" (for release candidates, "final". "serial" For situations where we do more than one release of a given level, the incremental number of the release (e.g., 1 for "alpha 1", 3 for "beta 3", etc.). How this will work ================== For the most part, this all works pretty simply and intuitively. Let's consider the case of the eventual 1.1 release and, for sake of example, assume we do two alpha releases, two beta releases, one release candidate and then the final 1.0. During that process, the ``VERSION`` tuple would evolve as follows: * For Django 1.1 alpha 1: (1, 1, 0, 'alpha', 1). * For Django 1.1 alpha 2: (1, 1, 0, 'alpha', 2). * For Django 1.1 beta 1: (1, 1, 0, 'beta', 1). * For Django 1.1 beta 2: (1, 1, 0, 'beta', 2). * For Django 1.1 release candidate 1: (1, 1, 0, 'rc', 1). * For the final 1.1 release: (1, 1, 0, 'final', 0). The only tricky bit is what to do immediately after a release; for example, after we release 1.1, what happens to ``django.VERSION`` in trunk as we gear up development for 1.2? Taking a cue once again from Python, the answer is that we go from this, which is 1.1 final:: (1, 1, 0, 'final', 0) to this, which denotes dev work in trunk for 1.2 prior to any alpha release:: (1, 2, 0, 'alpha', 0) In other words, a release level of "alpha" and a serial of 0 indicates we're working toward the release specified by the rest of the tuple, but have not yet reached the point of issuing alpha versions of it. The ``django.get_version()`` function will be rewritten to piece this together as follows: * For a "real" release like, say, 1.1, the tuple (1, 1, 0, 'final', 0) will become the printed string "1.1 final". * For an alpha, beta or RC, a tuple like (1, 1, 0, 'beta', 2) will become the printed string "1.1 beta 2". (1, 1, 0, 'rc', 1) will become "1.1 rc 1". * For the one special case of checkouts from trunk prior to the beginning of alpha releases, a tuple like (1, 2, 0, 'alpha', 0) will become the printed string "1.2 pre-alpha". In all cases, if we're on an SVN checkout we append the revision number, e.g.: "1.2 pre-alpha SVN-31337". Packages, or other installs for which SVN checkout info is unavailable, will **omit** this rather than drop in the "SVN-unknown" we currently use. A real example: getting ready for 1.1 and 1.0.1 =============================================== Real Soon Now(TM) we'll be splitting things up a bit: trunk will become the development ground for the eventual 1.1 release, and a branch will be created which will track bugfixes for 1.0 and eventually produce a 1.0.1 release. The ``VERSION`` tuples of those two lines of code will become: * For trunk, leading up to 1.1: (1, 1, 0, 'alpha', 0). Thus ``get_version()`` will print "1.1 pre-alpha", to which SVN info will be appended if available. * For the 1.0.x branch, leading up to 1.0.1: (1, 0, 1, 'alpha', 0). Thus ``get_version()`` will print "1.0.1 pre-alpha", to which SVN info will be appended if available. Backwards-incompatibility concerns ================================== So far as I know, no-one's actually relying on ``django.VERSION`` keeping the format it currently has, because it's been so unpredictable over Django's history. If anyone really *is* relying on it, bring it up and we'll see what can be done about easing the transition. When this will happen ===================== Whenever the core team decides it's time to branch 1.0.x from trunk, I'll commit these changes immediately prior to the creation of the branch, then set the verion info appropriately in trunk and in the branch after the split happens. -- "Bureaucrat Conrad, you are technically correct -- the best kind of correct." --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to django-developers@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/django-developers?hl=en -~----------~----~----~----~------~----~------~--~---