Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #19728 - Updated API stability doc to reflect current meaning o…

…f "stable".
  • Loading branch information...
commit 132d5822b0651bd0f192388693cb22263e68ddf5 1 parent bd006e0
Tim Graham timgraham authored

Showing 1 changed file with 8 additions and 93 deletions. Show diff stats Hide diff stats

  1. +8 93 docs/misc/api-stability.txt
101 docs/misc/api-stability.txt
@@ -4,17 +4,19 @@ API stability
4 4
5 5 :doc:`The release of Django 1.0 </releases/1.0>` comes with a promise of API
6 6 stability and forwards-compatibility. In a nutshell, this means that code you
7   -develop against Django 1.0 will continue to work against 1.1 unchanged, and you
8   -should need to make only minor changes for any 1.X release.
  7 +develop against a 1.X version of Django will continue to work with future
  8 +1.X releases. You may need to make minor changes when upgrading the version of
  9 +Django your project uses: see the "Backwards incompatible changes" section of
  10 +the :doc:`release note </releases/index>` for the version or versions to which
  11 +you are upgrading.
9 12
10 13 What "stable" means
11 14 ===================
12 15
13 16 In this context, stable means:
14 17
15   -- All the public APIs -- everything documented in the linked documents below,
16   - and all methods that don't begin with an underscore -- will not be moved or
17   - renamed without providing backwards-compatible aliases.
  18 +- All the public APIs (everything in this documentation) will not be moved
  19 + or renamed without providing backwards-compatible aliases.
18 20
19 21 - If new features are added to these APIs -- which is quite possible --
20 22 they will not break or change the meaning of existing methods. In other
@@ -35,77 +37,7 @@ Stable APIs
35 37 ===========
36 38
37 39 In general, everything covered in the documentation -- with the exception of
38   -anything in the :doc:`internals area </internals/index>` is considered stable as
39   -of 1.0. This includes these APIs:
40   -
41   -- :doc:`Authorization </topics/auth/index>`
42   -
43   -- :doc:`Caching </topics/cache>`.
44   -
45   -- :doc:`Model definition, managers, querying and transactions
46   - </topics/db/index>`
47   -
48   -- :doc:`Sending email </topics/email>`.
49   -
50   -- :doc:`File handling and storage </topics/files>`
51   -
52   -- :doc:`Forms </topics/forms/index>`
53   -
54   -- :doc:`HTTP request/response handling </topics/http/index>`, including file
55   - uploads, middleware, sessions, URL resolution, view, and shortcut APIs.
56   -
57   -- :doc:`Generic views </topics/class-based-views/index>`.
58   -
59   -- :doc:`Internationalization </topics/i18n/index>`.
60   -
61   -- :doc:`Pagination </topics/pagination>`
62   -
63   -- :doc:`Serialization </topics/serialization>`
64   -
65   -- :doc:`Signals </topics/signals>`
66   -
67   -- :doc:`Templates </topics/templates>`, including the language, Python-level
68   - :doc:`template APIs </ref/templates/index>`, and :doc:`custom template tags
69   - and libraries </howto/custom-template-tags>`. We may add new template
70   - tags in the future and the names may inadvertently clash with
71   - external template tags. Before adding any such tags, we'll ensure that
72   - Django raises an error if it tries to load tags with duplicate names.
73   -
74   -- :doc:`Testing </topics/testing/index>`
75   -
76   -- :doc:`django-admin utility </ref/django-admin>`.
77   -
78   -- :doc:`Built-in middleware </ref/middleware>`
79   -
80   -- :doc:`Request/response objects </ref/request-response>`.
81   -
82   -- :doc:`Settings </ref/settings>`. Note, though that while the :doc:`list of
83   - built-in settings </ref/settings>` can be considered complete we may -- and
84   - probably will -- add new settings in future versions. This is one of those
85   - places where "'stable' does not mean 'complete.'"
86   -
87   -- :doc:`Built-in signals </ref/signals>`. Like settings, we'll probably add
88   - new signals in the future, but the existing ones won't break.
89   -
90   -- :doc:`Unicode handling </ref/unicode>`.
91   -
92   -- Everything covered by the :doc:`HOWTO guides </howto/index>`.
93   -
94   -``django.utils``
95   -----------------
96   -
97   -Most of the modules in ``django.utils`` are designed for internal use. Only
98   -the following parts of :doc:`django.utils </ref/utils>` can be considered stable:
99   -
100   -- ``django.utils.cache``
101   -- ``django.utils.datastructures.SortedDict`` -- only this single class; the
102   - rest of the module is for internal use.
103   -- ``django.utils.encoding``
104   -- ``django.utils.feedgenerator``
105   -- ``django.utils.http``
106   -- ``django.utils.safestring``
107   -- ``django.utils.translation``
108   -- ``django.utils.tzinfo``
  40 +anything in the :doc:`internals area </internals/index>` is considered stable.
109 41
110 42 Exceptions
111 43 ==========
@@ -121,23 +53,6 @@ If we become aware of a security problem -- hopefully by someone following our
121 53 everything necessary to fix it. This might mean breaking backwards
122 54 compatibility; security trumps the compatibility guarantee.
123 55
124   -Contributed applications (``django.contrib``)
125   ----------------------------------------------
126   -
127   -While we'll make every effort to keep these APIs stable -- and have no plans to
128   -break any contrib apps -- this is an area that will have more flux between
129   -releases. As the Web evolves, Django must evolve with it.
130   -
131   -However, any changes to contrib apps will come with an important guarantee:
132   -we'll make sure it's always possible to use an older version of a contrib app if
133   -we need to make changes. Thus, if Django 1.5 ships with a backwards-incompatible
134   -``django.contrib.flatpages``, we'll make sure you can still use the Django 1.4
135   -version alongside Django 1.5. This will continue to allow for easy upgrades.
136   -
137   -Historically, apps in ``django.contrib`` have been more stable than the core, so
138   -in practice we probably won't have to ever make this exception. However, it's
139   -worth noting if you're building apps that depend on ``django.contrib``.
140   -
141 56 APIs marked as internal
142 57 -----------------------
143 58

0 comments on commit 132d582

Please sign in to comment.
Something went wrong with that request. Please try again.