Missing Documentation for new BooleanField limitation

[robingreen]

The recent add to django/trunk/django/core/management/validation.py breaks the Rietveld install process as described in:

​http://code.google.com/appengine/articles/pure_django.html

[robingreen]

Here's the error's output:

$ make all
svn co ​http://rietveld.googlecode.com/svn/trunk/codereview@405
A codereview/intra_region_diff.py
A codereview/middleware.py
A codereview/patching.py
A codereview/views.py
A codereview/init.py
A codereview/models.py
A codereview/library.py
A codereview/engine.py
A codereview/urls.py
A codereview/feeds.py

U codereview

Checked out revision 405.
patch -p0 < patches/library.diff
patching file codereview/library.py
patch -p0 < patches/views.diff
patching file codereview/views.py
patch -p0 < patches/models.diff
patching file codereview/models.py
./manage.py syncdb
Error: One or more models did not validate:
codereview.issue: "local_base": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.issue: "closed": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.message: "draft": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.content: "is_uploaded": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.content: "is_bad": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.content: "file_too_large": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.patch: "is_binary": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.patch: "delta_calculated": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.comment: "left": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.account: "fresh": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.account: "uploadpy_hint": BooleanFields do not accept null values. Use a NullBooleanField instead.

make: * [dev.db] Error 1

[robingreen]

$ make all
svn co http://rietveld.googlecode.com/svn/trunk/codereview@405
A    codereview/intra_region_diff.py
A    codereview/middleware.py
A    codereview/patching.py
A    codereview/views.py
A    codereview/__init__.py
A    codereview/models.py
A    codereview/library.py
A    codereview/engine.py
A    codereview/urls.py
A    codereview/feeds.py
 U   codereview
Checked out revision 405.
patch -p0 < patches/library.diff
patching file codereview/library.py
patch -p0 < patches/views.diff
patching file codereview/views.py
patch -p0 < patches/models.diff
patching file codereview/models.py
./manage.py syncdb
Error: One or more models did not validate:
codereview.issue: "local_base": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.issue: "closed": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.message: "draft": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.content: "is_uploaded": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.content: "is_bad": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.content: "file_too_large": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.patch: "is_binary": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.patch: "delta_calculated": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.comment: "left": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.account: "fresh": BooleanFields do not accept null values. Use a NullBooleanField instead.
codereview.account: "uploadpy_hint": BooleanFields do not accept null values. Use a NullBooleanField instead.

make: *** [dev.db] Error 1

[James Bennett]

The error message makes clear what's going on here. BooleanField is only for two-value (true or false) logic. If three-value (true, false or null) logic is needed, use NullBooleanField.

[10456] corrected a bug wherein null=True was allowed on the field definition even though assigning a null value to the field would raise a (run-time) exception. The correct thing for any application which relied on the buggy behavior is simply to use a NullBooleanField instead.

[yishai@…]

I am reopening - apologies if this is not the proper way to do this. This change is not documented in the Model field documentation nor in the backwards incompatible changes list (e.g., in the release notes or in the Wiki).

See in particular the (now) misleading text in:
​http://docs.djangoproject.com/en/dev/ref/models/fields/#django.db.models.Field.null
And no mention of this limitation in:
​http://docs.djangoproject.com/en/dev/ref/models/fields/#booleanfield

[Alex Gaynor]

This should be in the 1.1 release document.

[sbj3]

Added note to null attribute and BooleanField that NullBooleanField s/b used.

[Chris Beaven]

In [16020]:

Fixes #10786 -- Document that NullBooleanField should be used rather than BooleanField with null=True. Thanks sbj3 for the patch.