Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #14455 -- Documented the backwards compatibility policy for loc…

…al flavors. Implemented the policy for the changes in the Indonesian local flavor (from r14195) that stimulated the development of this policy. Thanks to Karen, Alex, Ramiro and Chris for their help developing the policy.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14411 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 5c05233ffcaa2d2185aaa4b787e4a265c195f13e 1 parent 799a305
Russell Keith-Magee authored November 01, 2010
6  django/contrib/localflavor/id/id_choices.py
... ...
@@ -1,3 +1,4 @@
  1
+import warnings
1 2
 from django.utils.translation import ugettext_lazy as _
2 3
 
3 4
 # Reference: http://id.wikipedia.org/wiki/Daftar_provinsi_Indonesia
@@ -5,6 +6,11 @@
5 6
 # Indonesia does not have an official Province code standard.
6 7
 # I decided to use unambiguous and consistent (some are common) 3-letter codes.
7 8
 
  9
+warnings.warn(
  10
+    'There have been recent changes to the ID localflavor. See the release notes for details',
  11
+    RuntimeWarning
  12
+)
  13
+
8 14
 PROVINCE_CHOICES = (
9 15
     ('ACE', _('Aceh')),
10 16
     ('BLI', _('Bali')),
102  docs/misc/api-stability.txt
@@ -15,19 +15,19 @@ In this context, stable means:
15 15
    - All the public APIs -- everything documented in the linked documents below,
16 16
      and all methods that don't begin with an underscore -- will not be moved or
17 17
      renamed without providing backwards-compatible aliases.
18  
-     
  18
+
19 19
    - If new features are added to these APIs -- which is quite possible --
20 20
      they will not break or change the meaning of existing methods. In other
21 21
      words, "stable" does not (necessarily) mean "complete."
22  
-          
  22
+
23 23
    - If, for some reason, an API declared stable must be removed or replaced, it
24 24
      will be declared deprecated but will remain in the API for at least two
25 25
      minor version releases. Warnings will be issued when the deprecated method
26 26
      is called.
27  
-     
  27
+
28 28
      See :ref:`official-releases` for more details on how Django's version
29 29
      numbering scheme works, and how features will be deprecated.
30  
-     
  30
+
31 31
    - We'll only break backwards compatibility of these APIs if a bug or
32 32
      security hole makes it completely unavoidable.
33 33
 
@@ -41,56 +41,56 @@ of 1.0. This includes these APIs:
41 41
     - :doc:`Authorization </topics/auth>`
42 42
 
43 43
     - :doc:`Caching </topics/cache>`.
44  
-    
  44
+
45 45
     - :doc:`Model definition, managers, querying and transactions
46 46
       </topics/db/index>`
47  
-    
  47
+
48 48
     - :doc:`Sending e-mail </topics/email>`.
49  
-    
  49
+
50 50
     - :doc:`File handling and storage </topics/files>`
51  
-    
  51
+
52 52
     - :doc:`Forms </topics/forms/index>`
53  
-    
  53
+
54 54
     - :doc:`HTTP request/response handling </topics/http/index>`, including file
55 55
       uploads, middleware, sessions, URL resolution, view, and shortcut APIs.
56  
-    
  56
+
57 57
     - :doc:`Generic views </topics/http/generic-views>`.
58 58
 
59 59
     - :doc:`Internationalization </topics/i18n/index>`.
60  
-    
  60
+
61 61
     - :doc:`Pagination </topics/pagination>`
62  
-    
  62
+
63 63
     - :doc:`Serialization </topics/serialization>`
64  
-    
  64
+
65 65
     - :doc:`Signals </topics/signals>`
66  
-    
  66
+
67 67
     - :doc:`Templates </topics/templates>`, including the language, Python-level
68 68
       :doc:`template APIs </ref/templates/index>`, and :doc:`custom template tags
69 69
       and libraries </howto/custom-template-tags>`. We may add new template
70 70
       tags in the future and the names may inadvertently clash with
71 71
       external template tags. Before adding any such tags, we'll ensure that
72 72
       Django raises an error if it tries to load tags with duplicate names.
73  
-      
  73
+
74 74
     - :doc:`Testing </topics/testing>`
75 75
 
76 76
     - :doc:`django-admin utility </ref/django-admin>`.
77  
-    
  77
+
78 78
     - :doc:`Built-in middleware </ref/middleware>`
79  
-    
  79
+
80 80
     - :doc:`Request/response objects </ref/request-response>`.
81  
-    
  81
+
82 82
     - :doc:`Settings </ref/settings>`. Note, though that while the :doc:`list of
83 83
       built-in settings </ref/settings>` can be considered complete we may -- and
84 84
       probably will -- add new settings in future versions. This is one of those
85 85
       places where "'stable' does not mean 'complete.'"
86  
-      
  86
+
87 87
     - :doc:`Built-in signals </ref/signals>`. Like settings, we'll probably add
88 88
       new signals in the future, but the existing ones won't break.
89  
-      
  89
+
90 90
     - :doc:`Unicode handling </ref/unicode>`.
91  
-        
  91
+
92 92
     - Everything covered by the :doc:`HOWTO guides </howto/index>`.
93  
-    
  93
+
94 94
 ``django.utils``
95 95
 ----------------
96 96
 
@@ -106,7 +106,7 @@ the following parts of :doc:`django.utils </ref/utils>` can be considered stable
106 106
     - ``django.utils.safestring``
107 107
     - ``django.utils.translation``
108 108
     - ``django.utils.tzinfo``
109  
-    
  109
+
110 110
 Exceptions
111 111
 ==========
112 112
 
@@ -145,8 +145,62 @@ Certain APIs are explicitly marked as "internal" in a couple of ways:
145 145
     - Some documentation refers to internals and mentions them as such. If the
146 146
       documentation says that something is internal, we reserve the right to
147 147
       change it.
148  
-      
  148
+
149 149
     - Functions, methods, and other objects prefixed by a leading underscore
150 150
       (``_``). This is the standard Python way of indicating that something is
151 151
       private; if any method starts with a single ``_``, it's an internal API.
152 152
 
  153
+.. _misc-api-stability-localflavor:
  154
+
  155
+Local flavors
  156
+-------------
  157
+
  158
+.. versionchanged:: 1.3
  159
+
  160
+:mod:`django.contrib.localflavor` contains assorted pieces of code
  161
+that are useful for particular countries or cultures. This data is
  162
+local in nature, and is subject to change on timelines that will
  163
+almost never correlate with Django's own release schedules. For
  164
+example, a common change is to split a province into two new
  165
+provinces, or to rename an existing province.
  166
+
  167
+These changes present two competing compatibility issues. Moving
  168
+forward, displaying the names of deprecated, renamed and dissolved
  169
+provinces in a selection widget is bad from a user interface
  170
+perspective. However, maintaining full backwards compatibility
  171
+requires that we support historical values that may be stored in a
  172
+database -- including values that may no longer be valid.
  173
+
  174
+Therefore, Django has the following policy with respect to changes in
  175
+local flavor:
  176
+
  177
+    * At the time of a Django release, the data and algorithms
  178
+      contained in :mod:`django.contrib.localflavor` will, to the best
  179
+      of our ability, reflect the officially gazetted policies of the
  180
+      appropriate local government authority. If a province has been
  181
+      added, altered, or removed, that change will be reflected in
  182
+      Django's localflavor.
  183
+
  184
+    * These changes will *not* be backported to the previous stable
  185
+      release. Upgrading a minor version of Django should not require
  186
+      any data migration or audits for UI changes; therefore, if you
  187
+      want to get the latest province list, you will either need to
  188
+      upgrade your Django install, or backport the province list you
  189
+      need.
  190
+
  191
+    * For one release, the affected localflavor module will raise a
  192
+      ``RuntimeWarning`` when it is imported.
  193
+
  194
+    * The change will be announced in the release notes as a backwards
  195
+      incompatible change requiring attention. The change will also be
  196
+      annotated in the documentation for the localflavor module.
  197
+
  198
+    * Where necessary and feasible, a migration script will be provided
  199
+      to aid the migration process.
  200
+
  201
+For example, Django 1.2 contains an Indonesian localflavor. It has a
  202
+province list that includes "Nanggroe Aceh Darussalam (NAD)" as a
  203
+province. The Indonesian government has changed the official name of
  204
+the province to "Aceh (ACE)". As a result, Django 1.3 does *not*
  205
+contain "Nanggroe Aceh Darussalam (NAD)" in the province list, but
  206
+*does* contain "Aceh (ACE)".
38  docs/ref/contrib/localflavor.txt
@@ -129,6 +129,35 @@ in the file. See any of the existing flavors for examples.
129 129
 
130 130
 .. _create a ticket: http://code.djangoproject.com/simpleticket
131 131
 
  132
+Localflavor and backwards compatibility
  133
+=======================================
  134
+
  135
+As documented in our :ref:`API stability
  136
+<misc-api-stability-localflavor>` policy, Django will always attempt
  137
+to make :mod:`django.contrib.localflavor` reflect the officially
  138
+gazetted policies of the appropriate local government authority. For
  139
+example, if a government body makes a change to add, alter, or remove
  140
+a province (or state, or county), that change will be reflected in
  141
+Django's localflavor in the next stable Django release.
  142
+
  143
+When a backwards-incompatible change is made (for example, the removal
  144
+or renaming of a province) the localflavor in question will raise a
  145
+warning when that localflavor is imported. This provides a runtime
  146
+indication that something may require attention.
  147
+
  148
+However, once you have addressed the backwards compatibility (for
  149
+example, auditing your code to see if any data migration is required),
  150
+the warning serves no purpose. The warning can then be supressed.
  151
+For example, to suppress the warnings raised by the Indonesian
  152
+localflavor you would use the following code::
  153
+
  154
+    import warnings
  155
+    warnings.filterwarnings('ignore',
  156
+                            category=RuntimeWarning,
  157
+                            module='django.contrib.localflavor.id')
  158
+    from django.contrib.localflavor.id import forms as id_forms
  159
+
  160
+
132 161
 Argentina (``ar``)
133 162
 =============================================
134 163
 
@@ -234,7 +263,7 @@ Brazil (``br``)
234 263
 .. class:: br.forms.BRCPFField
235 264
 
236 265
     A form field that validates input as `Brazilian CPF`_.
237  
-    
  266
+
238 267
     Input can either be of the format XXX.XXX.XXX-VD or be a group of 11 digits.
239 268
 
240 269
 .. _Brazilian CPF: http://en.wikipedia.org/wiki/Cadastro_de_Pessoas_F%C3%ADsicas
@@ -242,7 +271,7 @@ Brazil (``br``)
242 271
 .. class:: br.forms.BRCNPJField
243 272
 
244 273
     A form field that validates input as `Brazilian CNPJ`_.
245  
-    
  274
+
246 275
     Input can either be of the format XX.XXX.XXX/XXXX-XX or be a group of 14
247 276
     digits.
248 277
 
@@ -443,6 +472,11 @@ Indonesia (``id``)
443 472
 
444 473
     A ``Select`` widget that uses a list of Indonesian provinces as its choices.
445 474
 
  475
+.. versionchanged:: 1.3
  476
+    The province "Nanggroe Aceh Darussalam (NAD)" has been removed
  477
+    from the province list in favor of the new official designation
  478
+    "Aceh (ACE)".
  479
+
446 480
 .. class:: id.forms.IDPhoneNumberField
447 481
 
448 482
     A form field that validates input as an Indonesian telephone number.
11  docs/releases/1.3.txt
@@ -209,6 +209,17 @@ problem.
209 209
 .. _Scunthorpe problem: http://en.wikipedia.org/wiki/Scunthorpe_problem
210 210
 .. _commit that implemented this change: http://code.djangoproject.com/changeset/13996
211 211
 
  212
+Localflavor changes
  213
+~~~~~~~~~~~~~~~~~~~
  214
+
  215
+Django 1.3 introduces the following backwards-incompatible changes to
  216
+local flavors:
  217
+
  218
+    * Indonesia (id) -- The province "Nanggroe Aceh Darussalam (NAD)"
  219
+      has been removed from the province list in favor of the new
  220
+      official designation "Aceh (ACE)".
  221
+
  222
+
212 223
 .. _deprecated-features-1.3:
213 224
 
214 225
 Features deprecated in 1.3

0 notes on commit 5c05233

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