Ticket #19728: 19728.diff

File 19728.diff, 4.0 KB (added by Tim Graham, 12 years ago)
  • docs/misc/api-stability.txt

    diff --git a/docs/misc/api-stability.txt b/docs/misc/api-stability.txt
    index 3c265be..751ba56 100644
    a b API stability  
    44
    55:doc:`The release of Django 1.0 </releases/1.0>` comes with a promise of API
    66stability 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.
     7develop against a 1.X version of Django will continue to work with future
     81.X releases. You may need to make minor changes when upgrading the version of
     9Django your project uses: see the "Backwards incompatible changes" section of
     10the :doc:`release note </releases/index>` for the version or versions to which
     11you are upgrading.
    912
    1013What "stable" means
    1114===================
    1215
    1316In this context, stable means:
    1417
    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.
    1820
    1921- If new features are added to these APIs -- which is quite possible --
    2022  they will not break or change the meaning of existing methods. In other
    Stable APIs  
    3638
    3739In general, everything covered in the documentation -- with the exception of
    3840anything 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``
     41of 1.0.
    10942
    11043Exceptions
    11144==========
Back to Top