[master] 33188acfa doc: Add a design pattern entry for hash_ignore_vary

[Dridi Boukelmoune]

commit 33188acfa13f0abe5f025c63a6c181433888dd5e
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date:   Tue Sep 7 14:51:04 2021 +0200

    doc: Add a design pattern entry for hash_ignore_vary

diff --git a/doc/sphinx/vcl-design-patterns/index.rst b/doc/sphinx/vcl-design-patterns/index.rst
index ed903ffa9..142ded002 100644
--- a/doc/sphinx/vcl-design-patterns/index.rst
+++ b/doc/sphinx/vcl-design-patterns/index.rst
@@ -17,3 +17,4 @@ may be simplified.
 	:maxdepth: 1
 
 	resp-status.rst
+	req-hash_ignore_vary.rst
diff --git a/doc/sphinx/vcl-design-patterns/req-hash_ignore_vary.rst b/doc/sphinx/vcl-design-patterns/req-hash_ignore_vary.rst
new file mode 100644
index 000000000..b5b620c96
--- /dev/null
+++ b/doc/sphinx/vcl-design-patterns/req-hash_ignore_vary.rst
@@ -0,0 +1,56 @@
+..
+	Copyright (c) 2021 Varnish Software AS
+	SPDX-License-Identifier: BSD-2-Clause
+	See LICENSE file for full text of license
+
+Ignoring the Vary header for bots
+=================================
+
+Varnish supports HTTP variants out of the box, but the *Vary* header is
+somewhat limited since it operates on complete header values. If you want for
+example to conduct an A/B testing campaign or perform blue/green deployment
+you can make clients "remember" their path with a first-party cookie.
+
+When a search engine bot asks for contents however, there's a high chance that
+they don't process cookies and in all likelihood you would prefer to serve a
+response quickly. In that case you would probably prefer not to even try to
+attribute a category to the client, but in that case you create a new variant
+in your cache that is none of A, B, blue, green, or whatever your backend
+serves.
+
+If the way content is served makes no difference to the bot, because you
+changed the color of a button or something else orthogonal to the content
+itself, then you risk a cache miss with the detrimental effects of adding a
+needless variant to the cache and serving it with extra latency.
+
+If latency is paramount, you can use ``req.hash_ignore_vary`` to opt out of
+the Vary match during the lookup and get the freshest variant.
+
+Ignoring how the cookie is set, and assuming the backend always provides an
+accurate *Cache-Control* even when cookies are present, below is an example of
+an A/B testing setup where bots are served the freshest variant::
+
+
+    import cookie;
+
+    include "devicedetect.vcl";
+
+    sub vcl_recv {
+        call devicedetect;
+        if (req.http.X-UA-Device ~ "bot") {
+            set req.hash_ignore_vary = true;
+        }
+    }
+
+    sub vcl_req_cookie {
+        cookie.parse(req.http.Cookie);
+        set req.http.X-AB-Test = cookie.get("ab-test");
+        return;
+    }
+
+    sub vcl_deliver {
+        unset resp.http.Vary;
+    }
+
+It is also assumed that the backend replies with a ``Vary: X-AB-Test`` header
+and varies on no other header.
diff --git a/doc/sphinx/vcl-design-patterns/resp-status.rst b/doc/sphinx/vcl-design-patterns/resp-status.rst
index 33dbc3573..29feeb59b 100644
--- a/doc/sphinx/vcl-design-patterns/resp-status.rst
+++ b/doc/sphinx/vcl-design-patterns/resp-status.rst
@@ -3,8 +3,6 @@
 	SPDX-License-Identifier: BSD-2-Clause
 	See LICENSE file for full text of license
 
-.. _dp_vcl_resp_status:
-
 Using extra digits in resp.status
 =================================