django.VERSION changes
James Bennett
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."
Jacob Kaplan-Moss
> 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.
We've talked about this in person a few times, but for the record, I
approve; this is the right approach.
Jacob
kubiku
> * For the final 1.1 release: (1, 1, 0, 'final', 0).
great mood improver for internal django developers, "stable" gives
stronger message to django users and especially their bosses. And
brings more assurance that it means what it means. Final is, well,
something just has ended.
Do you plan to have svn branches for stable releases e.g django-1.0,
django-1.1 which would allow people who are sticked to one particular
realese to easily update in case of micro (security fixes) release?
(e.g I check out django-1.0 and whenever django-1.0.1, django-1.0.2
and so on are released, its enough to svn up?)
Kuba
Fredrik Lundh
> May I suggest using word "stable" instead of final? While "final" is
> great mood improver for internal django developers, "stable" gives
> stronger message to django users and especially their bosses. And
> brings more assurance that it means what it means. Final is, well,
> something just has ended.
"final" is the standard for Python version tuples; see "version_info" on
this page:
http://docs.python.org/lib/module-sys.html
</F>
kubiku
instead of "rc", shouldn't we?
I still claim that "stable" passes better message. And it's more
respected my newcomers. Anywere you go to download piece of software
you look for a stable release, not final (unless following trunk or
snapshots of course).
Yet this is so internal issue, I'm not going to fight for that :)
Kuba