Notes on explicit hyperlink relations behavior

1 files changed, 6 insertions, 0 deletions

diff --git a/docs/topics/2.2-announcement.md b/docs/topics/2.2-announcement.md
index 262ae61d..65c05267 100644
--- a/docs/topics/2.2-announcement.md
+++ b/docs/topics/2.2-announcement.md
@@ -140,6 +140,12 @@ If you're overriding the `BasePermission` class, the old-style signature will co
 
 Note also that the usage of the internal APIs for permission checking on the `View` class has been cleaned up slightly, and is now documented and subject to the deprecation policy in all future versions.
 
+## More explicit hyperlink relations behavior
+
+When using a serializer with a `HyperlinkedRelatedField` or `HyperlinkedIdentityField`, the hyperlinks would previously use absolute URLs if the serializer context included a `'request'` key, and fallback to using relative URLs otherwise.  This could lead to non-obvious behavior, as it might not be clear why some serializers generated absolute URLs, and others do not.
+
+From version 2.2 onwards, serializers with hyperlinked relationships *always* require a `'request'` key to be supplied in the context dictionary.  The implicit behavior will continue to function, but it's use will raise a `PendingDeprecationWarning`.
+
 [xordoquy]: https://github.com/xordoquy
 [django-python-3]: https://docs.djangoproject.com/en/dev/faq/install/#can-i-use-django-with-python-3
 [porting-python-3]: https://docs.djangoproject.com/en/dev/topics/python3/