From 5a539659a3a05c1e65af7ccbf6323b440dc8592a Mon Sep 17 00:00:00 2001 From: Andrew Godwin Date: Sun, 8 Jan 2017 17:33:47 -0800 Subject: [PATCH] Start fleshing out 1.0 release notes --- CHANGELOG.txt | 25 +++++++++++++++++ docs/releases/1.0.0.rst | 62 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+) diff --git a/CHANGELOG.txt b/CHANGELOG.txt index 979a9ff..a4fc760 100644 --- a/CHANGELOG.txt +++ b/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) ------------------- diff --git a/docs/releases/1.0.0.rst b/docs/releases/1.0.0.rst index 019d312..a19f213 100644 --- a/docs/releases/1.0.0.rst +++ b/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.