From b1a88ceac8f65aaf90076827120e233cb52976d6 Mon Sep 17 00:00:00 2001 From: Lucas Di Pentima Date: Tue, 16 Nov 2021 13:17:52 -0300 Subject: [PATCH] 17635: Improving documentation on preserve_version field. Arvados-DCO-1.1-Signed-off-by: Lucas Di Pentima --- .../topics/collection-versioning.html.textile.liquid | 2 +- sdk/python/arvados/collection.py | 9 ++++++--- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/user/topics/collection-versioning.html.textile.liquid b/doc/user/topics/collection-versioning.html.textile.liquid index 9a32de0d0b..d6a3bb4c10 100644 --- a/doc/user/topics/collection-versioning.html.textile.liquid +++ b/doc/user/topics/collection-versioning.html.textile.liquid @@ -18,7 +18,7 @@ A version will be saved when one of the following conditions is true: One is by "configuring (system-wide) the collection's idle time":{{site.baseurl}}/admin/collection-versioning.html. This idle time is checked against the @modified_at@ attribute so that the version is saved when one or more of the previously enumerated attributes get updated and the @modified_at@ is at least at the configured idle time in the past. This way, a frequently updated collection won't create lots of version records that may not be useful. -The other way to trigger a version save, is by setting @preserve_version@ to @true@ on the current version collection record: this ensures that the current state will be preserved as a version the next time it gets updated. +The other way to trigger a version save, is by setting @preserve_version@ to @true@ on the current version collection record: this ensures that the current state will be preserved as a version the next time it gets updated. This includes either creating a new collection or updating a preexisting one. In the case of using @preserve_version = true@ on a collection's create call, the new record state will be preserved as a snapshot on the next update. h3. Collection's past versions behavior & limitations diff --git a/sdk/python/arvados/collection.py b/sdk/python/arvados/collection.py index 831b5d7e31..9ef610d24b 100644 --- a/sdk/python/arvados/collection.py +++ b/sdk/python/arvados/collection.py @@ -1578,7 +1578,8 @@ class Collection(RichCollectionBase): Retry count on API calls (if None, use the collection default) :preserve_version: - If True, the saved collection will be preserved, provided that the + If True, the saved collection will be preserved as a snapshot on the + next versionable update, provided that the Collections.CollectionVersioning configuration is enabled. """ @@ -1692,8 +1693,10 @@ class Collection(RichCollectionBase): Retry count on API calls (if None, use the collection default) :preserve_version: - If True, the saved collection will be preserved, provided that the - Collections.CollectionVersioning configuration is enabled. + If True, the newly saved collection will generate a new snapshot of + itself on the next versionable update. This parameter requires that + the Collections.CollectionVersioning is enabled and will raise an + exception otherwise. """ if properties and type(properties) is not dict: -- 2.30.2