Docs for #1104 - Started working on v2/git-reader docs

docs/client-specifications.rst

@@ -93,7 +93,7 @@ The following two endpoints MUST be used to retrieve data. Clients MUST NOT use
 
 Returns the following response for the collection ``{cid}`` in the bucket ``{bid}`` (likely ``main``):
 
-- ``changes``: list of records, optionally filtered with ``?_since="{timestamp}"``
+- ``changes``: list of records, optionally filtered with ``?_since={timestamp}``
 - ``metadata``: collection attributes
 - ``timestamp``: records timestamp
 
@@ -119,7 +119,7 @@ For each collection, the amount of possible values for the timestamps is finite.
 
 Returns the list of collections and their current timestamp.
 
-- ``changes``: list of collections and their timestamp, optionally filtered with ``?_since="{timestamp}"``
+- ``changes``: list of collections and their timestamp, optionally filtered with ``?_since={timestamp}``
 - ``timestamp``: highest collections timestamp
 
 .. note::
@@ -177,12 +177,12 @@ If the HTTP status is not OK (>=400), the response contains a JSON mapping, with
       "code": 400,
       "errno": 107,
       "error": "Invalid parameters",
-      "message": "_since in querystring: The value should be integer between double quotes.",
+      "message": "_since in querystring: The value should be integer, optionally between double quotes.",
       "details": [
         {
           "location": "querystring",
           "name": "_since",
-          "description": "The value should be integer between double quotes."
+          "description": "The value should be integer, optionally between double quotes."
         }
       ]
     }

docs/index.rst

@@ -26,6 +26,7 @@ Remote Settings is a Mozilla service that makes it easy to manage evergreen sett
    tutorial-attachments
    tutorial-dev-kinto-admin
    client-specifications
+   v2-notes
 
 Indices and tables
 ==================

docs/v2-notes.rst

@@ -0,0 +1,35 @@
+.. _v2-notes:
+
+Version 2 Endpoints
+===================
+
+Version 2 of the remote-settings reader endpoints started going live in late 2025.
+Clients will begin transitioning to them in early 2026.
+
+
+Why V2?
+-------
+
+V2 routes are served by the git-reader service, which provides several advantages compared to using a full service in a read-only mode:
+
+1. Simplifies the hosting/deploying of reader nodes
+    a. No database is required for reads
+    b. Far fewer dependencies to worry about
+2. Allow for down-stream changes
+    a. It's now possible to remove a specific collection (even modify if content signing is setup).
+    b. Useful in enterprise environments, or even firefox forks
+3. Prevent clients from using non-optimized routes
+    a. All kinto routes are served by the v1 readers, but most are not used
+4. Allows for specific reader releases
+    a. Changes that impact just the admin UI or writers will not require a reader release
+
+
+Breaking Changes
+----------------
+We are changing the format of one parameter, ``_expected``, which was wrapped in quotes in V1 routes. V2 routes will expect an unwrapped integer as a timestamp. V1 is being made forward-compatible to not require the quotes, so future clients will be able to switch API versions forth without issue.
+
+
+Hosting a V2 Reader
+-------------------
+
+Please see the `git-reader readme <https://github.com/mozilla/remote-settings/blob/main/git-reader/README.md>`_ for instructions.