Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

[1.5.X] Fixed #19728 - Updated API stability doc to reflect current m…

…eaning of "stable".

Backport of 132d582 from master
  • Loading branch information...
commit 23ef6e1baf29d0390d5b94de0441e19f722d3aab 1 parent 4f99b0b
Tim Graham authored February 19, 2013

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

  1. 101  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 notes on commit 23ef6e1

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