Start fleshing out 1.0 release notes

CHANGELOG.txt

@@ -1,3 +1,28 @@
+1.0.0 (2017-01-08)
+------------------
+
+Full release notes, with more upgrade details, are available at:
+http://channels.readthedocs.io/en/latest/releases/1.0.0.html
+
+* BREAKING CHANGE: WebSockets must now be explicitly accepted or denied.
+  See http://channels.readthedocs.io/en/latest/releases/1.0.0.html for more.
+
+* BREAKING CHANGE: Demultiplexers have been overhauled to directly dispatch
+  messages rather than using channels to new consumers. Consult the docs on
+  generic consumers for more: http://channels.readthedocs.io/en/latest/generics.html
+
+* BREAKING CHANGE: Databinding now operates from implicit group membership,
+  where your code just has to say what groups would be used and Channels will
+  work out if it's a creation, modification or removal from a client's
+  perspective, including with permissions.
+
+* Delay protocol server ships with Channels providing a specification on how
+  to delay jobs until later and a reference implementation.
+
+* Serializers can now specify fields as `__all__` to auto-include all fields.
+
+* Various other small fixes.
+
 0.17.3 (2016-10-12)
 -------------------
 

docs/releases/1.0.0.rst

@@ -56,12 +56,40 @@ This should be mostly backwards compatible, and may actually fix race
 conditions in some apps that were pre-existing.
 
 
+Databinding Group/Action Overhaul
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Previously, databinding subclasses had to implement
+``group_names(instance, action)`` to return what groups to send an instance's
+change to of the type ``action``. This had flaws, most notably when what was
+actually just a modification to the instance in question changed its
+permission status so more clients could see it; to those clients, it should
+instead have been "created".
+
+Now, Channels just calls ``group_names(instance)``, and you should return what
+groups can see the instance at the current point in time given the instance
+you were passed. Channels will actually call the method before and after changes,
+comparing the groups you gave, and sending out create, update or delete messages
+to clients appropriately.
+
+Existing databinding code will need to be adapted; see the
+"Backwards Incompatible Changes" section for more.
+
+
 Demultiplexer Overhaul
 ~~~~~~~~~~~~~~~~~~~~~~
 
 TBD
 
 
+Delay Server
+~~~~~~~~~~~~
+
+A built-in delay server, launched with `manage.py rundelay`, now ships if you
+wish to use it. It needs some extra initial setup and uses a database for
+persistance; see :doc:`/delay` for more information.
+
+
 Backwards Incompatible Changes
 ------------------------------
 
@@ -85,3 +113,37 @@ in the handshaking phase forever and you'll never get any messages.
 
 All built-in Channels consumers (e.g. in the generic consumers) have been
 upgraded to do this.
+
+
+Databinding group_names
+~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have databinding subclasses, you will have implemented
+``group_names(instance, action)``, which returns the groups to use based on the
+instance and action provided.
+
+Now, instead, you must implement ``group_names(instance)``, which returns the
+groups that can see the instance as it is presented for you; the action
+results will be worked out for you. For example, if you want to only show
+objects marked as "admin_only" to admins, and objects without it to everyone,
+previously you would have done::
+
+    def group_names(self, instance, action):
+        if instance.admin_only:
+            return ["admins"]
+        else:
+            return ["admins", "non-admins"]
+
+Because you did nothing based on the ``action`` (and if you did, you would
+have got incomplete messages, hence this design change), you can just change
+the signature of the method like this::
+
+    def group_names(self, instance):
+        if instance.admin_only:
+            return ["admins"]
+        else:
+            return ["admins", "non-admins"]
+
+Now, when an object is updated to have ``admin_only = True``, the clients
+in the ``non-admins`` group will get a ``delete`` message, while those in
+the ``admins`` group will get an ``update`` message.