From fb564015960298ab820d7fd1c7edd3e96a8a95f0 Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Tue, 21 Jul 2009 01:51:40 +0000 Subject: [PATCH] Fixed #11493 -- Added an internal document listing the APIs that have been formally deprecated. Thanks to Alex Gaynor for the draft text. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11277 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/index.txt | 3 ++- docs/internals/deprecation.txt | 21 ++++++++++++++++++++ docs/internals/index.txt | 3 ++- docs/internals/release-process.txt | 31 +++++++++++++++--------------- 4 files changed, 41 insertions(+), 17 deletions(-) create mode 100644 docs/internals/deprecation.txt diff --git a/docs/index.txt b/docs/index.txt index 89ee463dfa..86105372c4 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -200,6 +200,7 @@ The Django open-source project * **Django over time:** :ref:`API stability ` | - :ref:`Archive of release notes ` | `Backwards-incompatible changes`_ + :ref:`Archive of release notes ` | `Backwards-incompatible changes`_ | + :ref:`Deprecation Timeline ` .. _Backwards-incompatible changes: http://code.djangoproject.com/wiki/BackwardsIncompatibleChanges diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt new file mode 100644 index 0000000000..7e7f4c6338 --- /dev/null +++ b/docs/internals/deprecation.txt @@ -0,0 +1,21 @@ +.. _internals-deprecation: + +=========================== +Django Deprecation Timeline +=========================== + +This document outlines when various pieces of Django will be removed, following +their deprecation, as per the :ref:`Django deprecation policy +` + + * 1.3 + * ``AdminSite.root()``. This release will remove the old method for + hooking up admin URLs. This has been deprecated since the 1.1 + release. + + * 2.0 + * ``django.views.defaults.shortcut()``. This function has been moved + to ``django.contrib.contenttypes.views.shortcut()`` as part of the + goal of removing all ``django.contrib`` references from the core + Django codebase. The old shortcut will be removed in the 2.0 + release. diff --git a/docs/internals/index.txt b/docs/internals/index.txt index 0d54948bf5..1cbbb87f06 100644 --- a/docs/internals/index.txt +++ b/docs/internals/index.txt @@ -17,8 +17,9 @@ the hood". .. toctree:: :maxdepth: 1 - + contributing documentation committers release-process + deprecation diff --git a/docs/internals/release-process.txt b/docs/internals/release-process.txt index 911b67e441..6d4ad9e8c9 100644 --- a/docs/internals/release-process.txt +++ b/docs/internals/release-process.txt @@ -48,14 +48,16 @@ Minor releases -------------- Minor release (1.1, 1.2, etc.) will happen roughly every six months -- see -`release process`_, below for details. +`release process`_, below for details. + +.. _internal-release-deprecation-policy: These releases will contain new features, improvements to existing features, and such. A minor release may deprecate certain features from previous releases. If a feature in version ``A.B`` is deprecated, it will continue to work in version ``A.B+1``. In version ``A.B+2``, use of the feature will raise a ``PendingDeprecationWarning`` but will continue to work. Version ``A.B+3`` will -remove the feature entirely. +remove the feature entirely. So, for example, if we decided to remove a function that existed in Django 1.0: @@ -66,9 +68,9 @@ So, for example, if we decided to remove a function that existed in Django 1.0: * Django 1.2 will contain the backwards-compatible replica, but the warning will be promoted to a full-fledged ``DeprecationWarning``. This warning is *loud* by default, and will likely be quite annoying. - + * Django 1.3 will remove the feature outright. - + Micro releases -------------- @@ -92,21 +94,21 @@ varying levels: * The current development trunk will get new features and bug fixes requiring major refactoring. - + * All bug fixes applied to the trunk will also be applied to the last minor release, to be released as the next micro release. - + * Security fixes will be applied to the current trunk and the previous two minor releases. - + As a concrete example, consider a moment in time halfway between the release of Django 1.3 and 1.4. At this point in time: * Features will be added to development trunk, to be released as Django 1.4. - + * Bug fixes will be applied to a ``1.3.X`` branch, and released as 1.3.1, 1.3.2, etc. - + * Security releases will be applied to trunk, a ``1.3.X`` branch and a ``1.2.X`` branch. Security fixes will trigger the release of ``1.3.1``, ``1.2.1``, etc. @@ -117,7 +119,7 @@ Release process =============== Django uses a time-based release schedule, with minor (i.e. 1.1, 1.2, etc.) -releases every six months, or more, depending on features. +releases every six months, or more, depending on features. After each previous release (and after a suitable cooling-off period of a week or two), the core development team will examine the landscape and announce a @@ -174,12 +176,12 @@ and an rc complete with string freeze two weeks before the end of the schedule. Bug-fix releases ---------------- -After a minor release (i.e 1.1), the previous release will go into bug-fix mode. +After a minor release (i.e 1.1), the previous release will go into bug-fix mode. A branch will be created of the form ``branches/releases/1.0.X`` to track bug-fixes to the previous release. When possible, bugs fixed on trunk must *also* be fixed on the bug-fix branch; this means that commits need to cleanly -separate bug fixes from feature additions. The developer who commits a fix to +separate bug fixes from feature additions. The developer who commits a fix to trunk will be responsible for also applying the fix to the current bug-fix branch. Each bug-fix branch will have a maintainer who will work with the committers to keep them honest on backporting bug fixes. @@ -193,14 +195,13 @@ development will be happening in a bunch of places: * On trunk, development towards 1.2 proceeds with small additions, bugs fixes, etc. being checked in daily. - + * On the branch "branches/releases/1.1.X", bug fixes found in the 1.1 release are checked in as needed. At some point, this branch will be released as "1.1.1", "1.1.2", etc. * On the branch "branches/releases/1.0.X", security fixes are made if needed and released as "1.0.2", "1.0.3", etc. - + * On feature branches, development of major features is done. These branches will be merged into trunk before the end of phase two. -