Initial release notes

docs/topics/3.0-announcement.md

@@ -0,0 +1,239 @@
+**THIS DOCUMENT IS CURRENTLY A WORK IN PROGRESS**
+
+See the [Version 3.0 GitHub issue](https://github.com/tomchristie/django-rest-framework/pull/1800) for more details.
+
+# REST framework 3.0
+
+**Note incremental nature, discuss upgrading.**
+
+## Motivation
+
+**TODO**
+
+---
+
+## Request objects
+
+#### The `request.data` property.
+
+**TODO**
+
+#### The parser API.
+
+**TODO**
+
+## Serializers
+
+#### Single-step object creation.
+
+**TODO**: Drop `.restore_object()`, use `.create()` and `.update()` which should save the instance.
+
+**TODO**: Drop`.object`, use `.validated_data` or get the instance with `.save()`.
+
+#### Always use `fields`, not `exclude`.
+
+The `exclude` option is no longer available. You should use the more explicit `fields` option instead.
+
+#### The `extra_kwargs` option.
+
+The `read_only_fields` and `write_only_fields` options have been removed and replaced with a more generic `extra_kwargs`.
+
+    class MySerializer(serializer.ModelSerializer):
+        class Meta:
+            model = MyModel
+            fields = ('id', 'email', 'notes', 'is_admin')
+            extra_kwargs = {
+            	'is_admin': {'read_only': True}
+            }
+
+Alternatively, specify the field explicitly on the serializer class:
+
+    class MySerializer(serializer.ModelSerializer):
+        is_admin = serializers.BooleanField(read_only=True)
+
+        class Meta:
+            model = MyModel
+            fields = ('id', 'email', 'notes', 'is_admin')
+
+#### Changes to `HyperlinkedModelSerializer`.
+
+The `view_name` and `lookup_field` options have been removed. They are no longer required, as you can use the `extra_kwargs` argument instead:
+
+    class MySerializer(serializer.HyperlinkedModelSerializer):
+        class Meta:
+            model = MyModel
+            fields = ('url', 'email', 'notes', 'is_admin')
+            extra_kwargs = {
+            	'url': {'lookup_field': 'uuid'}
+            }
+
+Alternatively, specify the field explicitly on the serializer class:
+
+    class MySerializer(serializer.HyperlinkedModelSerializer):
+        url = serializers.HyperlinkedIdentityField(
+            view_name='mymodel-detail',
+            lookup_field='uuid'
+        )
+
+        class Meta:
+            model = MyModel
+            fields = ('url', 'email', 'notes', 'is_admin')
+
+#### Fields for model methods and properties.
+
+You can now specify field names in the `fields` option that refer to model methods or properties. For example, suppose you have the following model:
+
+    class Invitation(models.Model):
+        created = models.DateTimeField()
+        to_email = models.EmailField()
+        message = models.CharField(max_length=1000)
+
+		def expiry_date(self):
+		    return self.created + datetime.timedelta(days=30)
+
+You can include `expiry_date` as a field option on a `ModelSerializer` class.
+
+    class InvitationSerializer(serializers.ModelSerializer):
+        class Meta:
+            model = Invitation
+            fields = ('to_email', 'message', 'expiry_date')
+
+These fields will be mapped to `serializers.ReadOnlyField()` instances.
+
+    >>> serializer = InvitationSerializer()
+    >>> print repr(serializer)
+    InvitationSerializer():
+        to_email = EmailField(max_length=75)
+        message = CharField(max_length=1000)
+        expiry_date = ReadOnlyField()
+
+
+## Serializer fields
+
+#### The `Field` and `ReadOnly` field classes.
+
+**TODO**
+
+#### Coercing output types.
+
+**TODO**
+
+#### The `ListSerializer` class.
+
+**TODO**
+
+#### The `MultipleChoiceField` class.
+
+**TODO**
+
+#### Changes to the custom field API.
+
+**TODO** `to_representation`, `to_internal_value`.
+
+#### Explicit `querysets` required on relational fields.
+
+**TODO**
+
+#### Optional argument to `SerializerMethodField`.
+
+**TODO**
+
+## Generic views
+
+#### Simplification of view logic.
+
+**TODO**
+
+#### Removal of pre/post save hooks. 
+
+The following method hooks no longer exist on the new, simplified, generic views: `pre_save`, `post_save`, `pre_delete`, `post_delete`.
+
+If you do need custom behavior, you might choose to instead override the `.save()` method on your serializer class. For example:
+
+    def save(self, *args, **kwargs):
+        instance = super(MySerializer).save(*args, **kwarg)
+        send_email(instance.to_email, instance.message)
+		return instance
+
+Alternatively write your view logic exlpicitly, or tie your pre/post save behavior into the model class or model manager.
+
+#### Removal of view attributes.
+
+The `.object` and `.object_list` attributes are no longer set on the view instance. Treating views as mutable object instances that store state during the processing of the view tends to be poor design, and can lead to obscure flow logic.
+
+I would personally recommend that developers treat view instances as immutable objects in their application code.
+
+#### PUT as create.
+
+**TODO**
+
+## API style
+
+There are some improvements in the default style we use in our API responses.
+
+#### Unicode JSON by default.
+
+Unicode JSON is now the default. The `UnicodeJSONRenderer` class no longer exists, and the `UNICODE_JSON` setting has been added. To revert this behavior use the new setting:
+
+    REST_FRAMEWORK = {
+        'UNICODE_JSON': False
+    }
+
+#### Compact JSON by default.
+
+We now output compact JSON in responses by default. For example, we return:
+
+    {"email":"amy@example.com","is_admin":true}
+
+Instead of the following:
+
+    {"email": "amy@example.com", "is_admin": true}
+
+The `COMPACT_JSON` setting has been added, and can be used to revert this behavior if needed:
+
+    REST_FRAMEWORK = {
+        'COMPACT_JSON': False
+    }
+
+#### Throttle headers using `Retry-After`.
+
+The custom `X-Throttle-Wait-Second` header has now been dropped in favor of the standard `Retry-After` header. You can revert this behavior if needed by writing a custom exception handler for your application.
+
+#### Date and time objects as ISO-8859-1 strings in serializer data.
+
+Date and Time objects are now coerced to strings by default in the serializer output. Previously they were returned as `Date`, `Time` and `DateTime` objects, and later coerced to strings by the renderer.
+
+You can modify this behavior globally by settings the existing `DATE_FORMAT`, `DATETIME_FORMAT` and `TIME_FORMAT` settings keys. Setting these values to `None` instead of their default value of `'iso-8859-1'` will result in native objects being returned in serializer data.
+
+    REST_FRAMEWORK = {
+        # Return native `Date` and `Time` objects in `serializer.data`
+        'DATETIME_FORMAT': None
+        'DATE_FORMAT': None
+        'TIME_FORMAT': None
+    }
+
+You can also modify serializer fields individually, using the `date_format`, `time_format` and `datetime_format` arguments:
+
+    # Return `DateTime` instances in `serializer.data`, not strings.
+    created = serializers.DateTimeField(format=None)
+
+#### Decimals as strings in serializer data.
+
+Decimals are now coerced to strings by default in the serializer output. Previously they were returned as `Decimal` objects, and later coerced to strings by the renderer.
+
+You can modify this behavior globally by using the `COERCE_DECIMAL_TO_STRING` settings key.
+
+    REST_FRAMEWORK = {
+        'COERCE_DECIMAL_TO_STRING': False
+    }
+
+Or modify it on an individual serializer field, using the `corece_to_string` keyword argument.
+
+    # Return `Decimal` instances in `serializer.data`, not strings.
+    amount = serializers.DecimalField(
+        max_digits=10,
+        decimal_places=2,
+        coerce_to_string=False
+    )
+
+The default JSON renderer will return float objects for uncoerced `Decimal` instances. This allows you to easily switch between string or float representations for decimals depending on your API design needs.