Prepare for required server version

We want to introduce server version-dependent functionality in git-pw.
While using the versionless URL might be slightly shorter, it does make
things a lot tougher to figure out. Start warning users if the server
URL provided doesn't come with a server version. This can be an error in
future versions.

Signed-off-by: Stephen Finucane <stephen@that.guru>

Author: stephenfin

README.rst

@@ -72,10 +72,16 @@ To begin, you'll need to configure Git settings appropriately. The following
 settings are **required**:
 
 ``pw.server``
-  The URL for the Patchwork instance. This will typically look like. For
-  example::
+  The URL for the Patchwork instance's API. This should include the API
+  version::
 
-      https://patchwork.ozlabs.org/
+      https://patchwork.ozlabs.org/api/1.1
+
+  You can discover the API version supported by your instance by comparing the
+  server version, found at ``/about``, with the API versions provided in the
+  `documentation`__.
+
+  __ https://patchwork.readthedocs.io/en/stable-2.1/api/rest/#rest-api-versions
 
 ``pw.project``
   The project name or list-id. This will appear in the URL when using the web
@@ -101,7 +107,7 @@ configure the Patchwork project, run:
 
 .. code-block:: bash
 
-   $ git config pw.server 'https://patchwork.ozlabs.org/api/1.0/'
+   $ git config pw.server 'https://patchwork.ozlabs.org/api/1.1/'
    $ git config pw.project 'patchwork'
 
 Development

git_pw/api.py

@@ -57,7 +57,21 @@ def _get_headers():  # type: () -> Dict[str, str]
 
 def _get_server():  # type: () -> str
     if CONF.server:
-        return CONF.server.rstrip('/')
+        server = CONF.server.rstrip('/')
+
+        if not re.match(r'.*/api/\d\.\d$', server):
+            LOG.warning('Server version missing')
+            LOG.warning('You should provide the server version in the URL '
+                        'configured via git-config or --server')
+            LOG.warning('This will be required in git-pw 2.0')
+
+        if not re.match(r'.*/api(/\d\.\d)?$', server):
+            # NOTE(stephenfin): We've already handled this particular error
+            # above so we don't warn twice. We also don't stick on a version
+            # number since the user clearly wants the latest
+            server += '/api'
+
+        return server
     else:
         LOG.error('Server information missing')
         LOG.error('You must provide server information via git-config or via '
@@ -193,7 +207,7 @@ def index(resource_type, params=None):
         A list of dictionaries, representing the summary view of each resource.
     """
     # NOTE(stephenfin): All resources must have a trailing '/'
-    url = '/'.join([_get_server(), 'api', resource_type, ''])
+    url = '/'.join([_get_server(), resource_type, ''])
 
     # NOTE(stephenfin): Not all endpoints in the Patchwork API allow filtering
     # by project, but all the ones we care about here do.
@@ -218,8 +232,7 @@ def detail(resource_type, resource_id, params=None):
         A dictionary representing the detailed view of a given resource.
     """
     # NOTE(stephenfin): All resources must have a trailing '/'
-    url = '/'.join([_get_server(), 'api', resource_type,
-                    str(resource_id), ''])
+    url = '/'.join([_get_server(), resource_type, str(resource_id), ''])
 
     return get(url, params, stream=False).json()
 
@@ -238,7 +251,7 @@ def update(resource_type, resource_id, data):
     Returns:
         A dictionary representing the detailed view of a given resource.
     """
-    url = '/'.join([CONF.server.rstrip('/'), 'api', '1.0', resource_type,
-                    str(resource_id), ''])
+    # NOTE(stephenfin): All resources must have a trailing '/'
+    url = '/'.join([_get_server(), resource_type, str(resource_id), ''])
 
     return put(url, data).json()

releasenotes/notes/require-server-version-93ac0818c293b85e.yaml

@@ -0,0 +1,6 @@
+---
+upgrade:
+  - |
+    Configuring a server without the API version, e.g. via ``git config
+    pw.server`` will now result in a warning. An error will be raised in a
+    future release of *git-pw*.