From 3e0456d88b0eea9e2c4865d6d7d027630a9b64fd Mon Sep 17 00:00:00 2001
From: Alexander Neumann <alexander@bumpern.de>
Date: Wed, 11 Nov 2020 20:00:34 +0100
Subject: [PATCH] Highlight that s3.list-objects-v1 is a temporary

---
 changelog/unreleased/issue-3083  | 18 ++++++++++++------
 doc/030_preparing_a_new_repo.rst |  9 ++++++---
 2 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/changelog/unreleased/issue-3083 b/changelog/unreleased/issue-3083
index 00e34167..5790a009 100644
--- a/changelog/unreleased/issue-3083
+++ b/changelog/unreleased/issue-3083
@@ -1,13 +1,19 @@
 Enhancement: Allow usage of deprecated S3 ListObjectsV1 API
 
 Restic didn't work with some S3 API implementations that don't have a
-working ListObjectsV2 API endpoint. This concerns mainly Ceph versions
-before v14.2.5 , but may impact other S3 API implementations.
+broken `ListObjectsV2` API endpoint. This concerns mainly Ceph versions
+before v14.2.5 , but may impact other S3 API implementations. When a broken
+server implementation is used, restic prints errors similar to the following:
 
-Restic now allows selection of the older ListObjectsV1 endpoint by using
-the 's3.list-objects-v1' extended option, for instance:
+    List() returned error: Truncated response should have continuation token set
 
-`restic -o s3.list-objects-v1=true snapshots`
+As a temporary workaround, restic now allows selection of the older
+`ListObjects` endpoint by using the `s3.list-objects-v1` extended option, for
+instance:
+
+    restic -o s3.list-objects-v1=true snapshots
+
+This option may be removed in future versions of restic.
 
 https://github.com/restic/restic/issues/3083
-https://github.com/restic/restic/pull/3085
\ No newline at end of file
+https://github.com/restic/restic/pull/3085
diff --git a/doc/030_preparing_a_new_repo.rst b/doc/030_preparing_a_new_repo.rst
index 164cb700..e6cd3575 100644
--- a/doc/030_preparing_a_new_repo.rst
+++ b/doc/030_preparing_a_new_repo.rst
@@ -240,9 +240,12 @@ or is only available via HTTP, you can specify the URL to the server
 like this: ``s3:http://server:port/bucket_name``.
 
 
-.. note:: Certain S3-compatible servers do not properly implement the ListObjectsV2 API,
-          most notably Ceph versions before v14.2.5. On these backends you need to
-          provide the ``-o s3.list-objects-v1=true`` option to use the ListObjects API instead.
+.. note:: Certain S3-compatible servers do not properly implement the
+          ``ListObjectsV2`` API, most notably Ceph versions before v14.2.5. On these
+          backends, as a temporary workaround, you can provide the
+          ``-o s3.list-objects-v1=true`` option to use the older
+          ``ListObjects`` API instead. This option may be removed in future
+          versions of restic.
 
 
 Minio Server