[ARVADOS] created: 1.2.0-221-ge5dc0c9de
Git user
git at public.curoverse.com
Mon Oct 22 11:23:04 EDT 2018
at e5dc0c9de3a098b2f3b5f2d29d5dab1c9b234eef (commit)
commit e5dc0c9de3a098b2f3b5f2d29d5dab1c9b234eef
Author: Lucas Di Pentima <ldipentima at veritasgenetics.com>
Date: Mon Oct 22 12:21:55 2018 -0300
13561: Formatting fixes, examples enhancements & additions.
Arvados-DCO-1.1-Signed-off-by: Lucas Di Pentima <ldipentima at veritasgenetics.com>
diff --git a/doc/admin/collection-versioning.html.textile.liquid b/doc/admin/collection-versioning.html.textile.liquid
index ea632b925..6e84fa692 100644
--- a/doc/admin/collection-versioning.html.textile.liquid
+++ b/doc/admin/collection-versioning.html.textile.liquid
@@ -18,8 +18,7 @@ There are 2 configuration settings that control this feature, both go on the @ap
h4. Settting: @collection_versioning@ (Boolean. Default: false)
-If @true@, collection versioning is enabled, meaning that new version records can be created.
-Note that if you set @collection_versioning@ to @false@ after being enabled, old versions that could have been saved will still be accessible.
+If @true@, collection versioning is enabled, meaning that new version records can be created. Note that if you set @collection_versioning@ to @false@ after being enabled, old versions that could have been saved will still be accessible.
h4. Setting: @preserve_version_if_idle@ (Numeric. Default: -1)
diff --git a/doc/user/topics/collection-versioning.html.textile.liquid b/doc/user/topics/collection-versioning.html.textile.liquid
index 81beffe83..fb569fd55 100644
--- a/doc/user/topics/collection-versioning.html.textile.liquid
+++ b/doc/user/topics/collection-versioning.html.textile.liquid
@@ -12,26 +12,28 @@ SPDX-License-Identifier: CC-BY-SA-3.0
When collection versioning is enabled, updating certain collection attributes (@name@, @description@, @properties@, @manifest_text@) will save a copy of the collection state, previous to the update. This copy (a new collection record) will have its own @uuid@, and a @current_version_uuid@ attribute pointing to the current version's @uuid at .
-Every collection has a @version@ attribute that indicates its version number, starting from 1 on new collections and incrementing by 1 with every versionable update. All collections point to their most current version via the @current_version_uuid@ attribute, being @uuid@ and @current_version_uuid@ equal on those collection records that are the the current version of themselves.
-Note that the "current version" collection record doesn't change its @uuid@, "past versions" are saved as new records every time it's needed, pointing to the current collection record.
+Every collection has a @version@ attribute that indicates its version number, starting from 1 on new collections and incrementing by 1 with every versionable update. All collections point to their most current version via the @current_version_uuid@ attribute, being @uuid@ and @current_version_uuid@ equal on those collection records that are the the current version of themselves. Note that the "current version" collection record doesn't change its @uuid@, "past versions" are saved as new records every time it's needed, pointing to the current collection record.
+
+There are two ways that this feature works:
+
+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 are two ways that this feature works: 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.
h3. Collection's past versions behavior & limitations
Past version collection records are read-only, if you need to make changes to one of them, the suggested approach is to copy it into a new collection before updating.
-Some attributes are automatically synced when they change on the current version: @owner_uuid@, @delete_at@, @trash_at@, @is_trashed@, @replication_desired@ and @storage_classes_desired at . This way, old versions follow the current one on several configurations. In the special case that a current version's @uuid@ gets updated, their past versions get also updated to point to the newer UUID.
+Some attributes are automatically synced when they change on the current version: @owner_uuid@, @delete_at@, @trash_at@, @is_trashed@, @replication_desired@ and @storage_classes_desired at . This way, old versions follow the current one on several configurations. In the special case that a current version's @uuid@ gets updated, their past versions get also updated to point to the newer UUID. When a collection's current version is deleted, its past versions will follow it.
Permissions on past versions are the same as their current version, the system does not allow attaching permission links to old versions. If you need to give special access to someone to a particular old version, the correct procedure is by copying it as a new collection.
h3. Example: Accessing past versions of a collection
-To request a particular collection with all its versions you should request a list with filters including the collection's UUID and passing the @include_old_versions@ query parameter. For example, using the @arv@ command line client:
+To request a particular collection with all its versions you should request a list filtering the current version's UUID and passing the @include_old_versions@ query parameter. For example, using the @arv@ command line client:
<pre>
-$ arv collection index --filters '[["uuid", "=", "o967z-4zz18-ynmlhyjbg1arnr2"]]' --include-old-versions
+$ arv collection index --filters '[["current_version_uuid", "=", "o967z-4zz18-ynmlhyjbg1arnr2"]]' --include-old-versions
{
"items":[
{
@@ -53,7 +55,25 @@ $ arv collection index --filters '[["uuid", "=", "o967z-4zz18-ynmlhyjbg1arnr2"]]
}
</pre>
-You can also access a past version directly by its UUID:
+To access a specific collection version using filters:
+
+<pre>
+$ arv collection index --filters '[["current_version_uuid", "=", "o967z-4zz18-ynmlhyjbg1arnr2"], ["version", "=", 1]]' --include-old-versions
+{
+ "items":[
+ {
+ "uuid":"o967z-4zz18-i3ucessyo6xxadt",
+ "created_at":"2018-10-05T14:43:38.916885000Z",
+ "modified_at":"2018-10-05T14:44:31.098019000Z",
+ "version":1,
+ "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2"
+ }
+ ],
+ "items_available":1
+}
+</pre>
+
+You can also access it directly via a GET request using its UUID:
<pre>
$ arv collection get --uuid o967z-4zz18-i3ucessyo6xxadt
commit 177388574a96b3e9770dc3731262502638e9b786
Author: Lucas Di Pentima <ldipentima at veritasgenetics.com>
Date: Wed Oct 10 17:12:27 2018 -0300
13561: Re-phrase user guide & add admin guide section.
Arvados-DCO-1.1-Signed-off-by: Lucas Di Pentima <ldipentima at veritasgenetics.com>
diff --git a/doc/_config.yml b/doc/_config.yml
index 81a034fec..921e261fb 100644
--- a/doc/_config.yml
+++ b/doc/_config.yml
@@ -166,6 +166,8 @@ navbar:
- Cloud:
- admin/storage-classes.html.textile.liquid
- admin/spot-instances.html.textile.liquid
+ - Other:
+ - admin/collection-versioning.html.textile.liquid
installguide:
- Overview:
- install/index.html.textile.liquid
diff --git a/doc/admin/collection-versioning.html.textile.liquid b/doc/admin/collection-versioning.html.textile.liquid
new file mode 100644
index 000000000..ea632b925
--- /dev/null
+++ b/doc/admin/collection-versioning.html.textile.liquid
@@ -0,0 +1,33 @@
+---
+layout: default
+navsection: admin
+title: Configuring collection versioning
+...
+
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+This page describes how to enable and configure the collection versioning feature on the API server.
+
+h3. API Server configuration
+
+There are 2 configuration settings that control this feature, both go on the @application.yml@ file.
+
+h4. Settting: @collection_versioning@ (Boolean. Default: false)
+
+If @true@, collection versioning is enabled, meaning that new version records can be created.
+Note that if you set @collection_versioning@ to @false@ after being enabled, old versions that could have been saved will still be accessible.
+
+h4. Setting: @preserve_version_if_idle@ (Numeric. Default: -1)
+
+This setting control the auto-save aspect of collection versioning, and can be set to:
+* @-1@: Never auto-save versions. Only save versions when the client ask for it by setting @preserve_version@ to @true@ on any given collection.
+* @0@: Preserve all versions every time a collection gets a versionable update.
+* @N@ (being N > 0): Preserve version when a collection gets a versionable update after a period of at least N seconds since the last time it was modified.
+
+h3. Using collection versioning
+
+"Discussed in the user guide":{{site.baseurl}}/user/topics/collection-versioning.html
\ No newline at end of file
diff --git a/doc/user/topics/collection-versioning.html.textile.liquid b/doc/user/topics/collection-versioning.html.textile.liquid
index 739c7fd24..81beffe83 100644
--- a/doc/user/topics/collection-versioning.html.textile.liquid
+++ b/doc/user/topics/collection-versioning.html.textile.liquid
@@ -10,83 +10,43 @@ Copyright (C) The Arvados Authors. All rights reserved.
SPDX-License-Identifier: CC-BY-SA-3.0
{% endcomment %}
-Collection versioning (if enabled system-wide) adds the possibility to store different collection states as it is modified. Depending on the cluster configuration it can work automatically, but there's also a way to manually control it by the user.
+When collection versioning is enabled, updating certain collection attributes (@name@, @description@, @properties@, @manifest_text@) will save a copy of the collection state, previous to the update. This copy (a new collection record) will have its own @uuid@, and a @current_version_uuid@ attribute pointing to the current version's @uuid at .
-Versioning only triggers when selected collection attributes are updated: @name@, @description@, @properties@ and @manifest_text at .
-When one of these attributes change and the cluster-wide's configured collection idle time is up, or the individual collection's @preserve_version@ attribute is @true@, a new copy is made before saving the changes.
+Every collection has a @version@ attribute that indicates its version number, starting from 1 on new collections and incrementing by 1 with every versionable update. All collections point to their most current version via the @current_version_uuid@ attribute, being @uuid@ and @current_version_uuid@ equal on those collection records that are the the current version of themselves.
+Note that the "current version" collection record doesn't change its @uuid@, "past versions" are saved as new records every time it's needed, pointing to the current collection record.
-Every collection has a @version@ attribute that indicates its version number, starting from 1 on new collections and incrementing by 1 with every versionable update. Also, all collections point to their most current version via the @current_version_uuid@ attribute.
+The are two ways that this feature works: 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.
-h3. Accessing past versions of a collection
+h3. Collection's past versions behavior & limitations
+
+Past version collection records are read-only, if you need to make changes to one of them, the suggested approach is to copy it into a new collection before updating.
+
+Some attributes are automatically synced when they change on the current version: @owner_uuid@, @delete_at@, @trash_at@, @is_trashed@, @replication_desired@ and @storage_classes_desired at . This way, old versions follow the current one on several configurations. In the special case that a current version's @uuid@ gets updated, their past versions get also updated to point to the newer UUID.
+
+Permissions on past versions are the same as their current version, the system does not allow attaching permission links to old versions. If you need to give special access to someone to a particular old version, the correct procedure is by copying it as a new collection.
+
+h3. Example: Accessing past versions of a collection
To request a particular collection with all its versions you should request a list with filters including the collection's UUID and passing the @include_old_versions@ query parameter. For example, using the @arv@ command line client:
<pre>
$ arv collection index --filters '[["uuid", "=", "o967z-4zz18-ynmlhyjbg1arnr2"]]' --include-old-versions
{
- "kind":"arvados#collectionList",
- "etag":"",
- "self_link":"",
- "offset":0,
- "limit":100,
"items":[
{
- "href":"/collections/o967z-4zz18-i3ucessyo6xxadt",
- "kind":"arvados#collection",
- "etag":"7bhgspoi4rg9d33o925y8k277",
"uuid":"o967z-4zz18-i3ucessyo6xxadt",
- "owner_uuid":"o967z-tpzed-dvuag6geduje1ub",
"created_at":"2018-10-05T14:43:38.916885000Z",
- "modified_by_client_uuid":"o967z-ozdt8-ac1bob2unkhev15",
- "modified_by_user_uuid":"o967z-tpzed-dvuag6geduje1ub",
"modified_at":"2018-10-05T14:44:31.098019000Z",
- "name":"Test collection",
- "description":"This is the first version",
- "properties":{},
- "portable_data_hash":"d41d8cd98f00b204e9800998ecf8427e+0",
- "replication_desired":null,
- "replication_confirmed":null,
- "replication_confirmed_at":null,
- "storage_classes_desired":[
- "default"
- ],
- "storage_classes_confirmed":[],
- "storage_classes_confirmed_at":null,
- "delete_at":null,
- "trash_at":null,
- "is_trashed":false,
"version":1,
- "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
- "preserve_version":true
+ "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2"
},
{
- "href":"/collections/o967z-4zz18-ynmlhyjbg1arnr2",
- "kind":"arvados#collection",
- "etag":"1b995we7yilwyh7sc0w746urv",
"uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
- "owner_uuid":"o967z-tpzed-dvuag6geduje1ub",
"created_at":"2018-10-05T14:43:38.916885000Z",
- "modified_by_client_uuid":"o967z-ozdt8-ac1bob2unkhev15",
- "modified_by_user_uuid":"o967z-tpzed-dvuag6geduje1ub",
"modified_at":"2018-10-05T14:44:31.078643000Z",
- "name":"Test collection",
- "description":"This is the second (and current) version",
- "properties":{},
- "portable_data_hash":"d41d8cd98f00b204e9800998ecf8427e+0",
- "replication_desired":null,
- "replication_confirmed":null,
- "replication_confirmed_at":null,
- "storage_classes_desired":[
- "default"
- ],
- "storage_classes_confirmed":[],
- "storage_classes_confirmed_at":null,
- "delete_at":null,
- "trash_at":null,
- "is_trashed":false,
"version":2,
- "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
- "preserve_version":false
+ "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2"
}
],
"items_available":2
@@ -98,92 +58,30 @@ You can also access a past version directly by its UUID:
<pre>
$ arv collection get --uuid o967z-4zz18-i3ucessyo6xxadt
{
- "href":"/collections/o967z-4zz18-i3ucessyo6xxadt",
- "kind":"arvados#collection",
- "etag":"1ej4d9klu70bez72cy7yjrz7o",
"uuid":"o967z-4zz18-i3ucessyo6xxadt",
- "owner_uuid":"o967z-tpzed-dvuag6geduje1ub",
"created_at":"2018-10-05T14:43:38.916885000Z",
- "modified_by_client_uuid":"o967z-ozdt8-ac1bob2unkhev15",
- "modified_by_user_uuid":"o967z-tpzed-dvuag6geduje1ub",
"modified_at":"2018-10-05T14:44:31.098019000Z",
- "name":"Test collection",
- "description":"This is the first version",
- "properties":{},
- "portable_data_hash":"d41d8cd98f00b204e9800998ecf8427e+0",
- "manifest_text":"",
- "replication_desired":null,
- "replication_confirmed":null,
- "replication_confirmed_at":null,
- "storage_classes_desired":[
- "default"
- ],
- "storage_classes_confirmed":[],
- "storage_classes_confirmed_at":null,
- "delete_at":null,
- "trash_at":null,
- "is_trashed":false,
"version":1,
- "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
- "preserve_version":true
+ "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2"
}
</pre>
-h3. Manually preserving a version
+h3. Example: Ensuring a version is preserved
-Regardless of the collection's auto-save idle time cluster configuration, the user has the option to request that a particular collection state should be preserved.
+As stated before, regardless of the collection's auto-save idle time cluster configuration, the user has the ability to request that a particular collection state should be preserved.
When working on a collection, if there's a need to preserve the current state as a new version, the @preserve_version@ attribute should be set to @true at . This will trigger a new version creation on the next update, keeping this "version 2" state as a snapshot.
<pre>
$ arv collection update --uuid o967z-4zz18-ynmlhyjbg1arnr2 -c '{"preserve_version":true}'
{
- "href":"/collections/o967z-4zz18-ynmlhyjbg1arnr2",
- "kind":"arvados#collection",
- "etag":"8vhdwnahk8jcr84mqitmd5stu",
"uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
- "owner_uuid":"o967z-tpzed-dvuag6geduje1ub",
"created_at":"2018-10-05T14:43:38.916885000Z",
- "modified_by_client_uuid":"o967z-ozdt8-ac1bob2unkhev15",
- "modified_by_user_uuid":"o967z-tpzed-dvuag6geduje1ub",
"modified_at":"2018-10-05T15:12:57.986454000Z",
- "name":"Test collection",
- "description":"This is the second (and current) version",
- "properties":{},
- "portable_data_hash":"d41d8cd98f00b204e9800998ecf8427e+0",
- "manifest_text":"",
- "replication_desired":null,
- "replication_confirmed":null,
- "replication_confirmed_at":null,
- "storage_classes_desired":[
- "default"
- ],
- "storage_classes_confirmed":[],
- "storage_classes_confirmed_at":null,
- "delete_at":null,
- "trash_at":null,
- "is_trashed":false,
"version":2,
"current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
"preserve_version":true
}
</pre>
-Once the @preserve_version@ attribute is set to @true@, it cannot be manually changed to @false@ and it will only be reset when a versionable update on the collection triggers a new version snapshot.
-
-h3. Collection versions behavior & limitations
-
-Past version collections are read-only, if you need to make changes to one of them, the suggested approach is to copy it into a new collection before updating.
-
-Some attributes get automatically synced when they change on the current version:
-
-* @owner_uuid@
-* @delete_at@
-* @trash_at@
-* @is_trashed@
-* @replication_desired@
-* @storage_classes_desired@
-
-This way, old versions follow the current one on several configurations. In the special case that a current version's UUID gets updated, their past versions get also updated to point to the newer UUID.
-
-Permissions on past versions are the same as their current version, the system does not allow attaching permission links to old versions. If you need to give special access to someone to a particular old version, the correct procedure is by copying it as a new collection.
\ No newline at end of file
+Once the @preserve_version@ attribute is set to @true@, it cannot be changed to @false@ and it will only be reset when a versionable update on the collection triggers a version save.
commit 3318fb4db96c25d87fd5a4037ff2c2aa55bc01ed
Author: Lucas Di Pentima <ldipentima at veritasgenetics.com>
Date: Fri Oct 5 15:55:41 2018 -0300
13561: Update documentation on collection versioning.
Arvados-DCO-1.1-Signed-off-by: Lucas Di Pentima <ldipentima at veritasgenetics.com>
diff --git a/doc/_config.yml b/doc/_config.yml
index 4ab858550..81a034fec 100644
--- a/doc/_config.yml
+++ b/doc/_config.yml
@@ -39,6 +39,7 @@ navbar:
- user/topics/keep.html.textile.liquid
- user/topics/arv-copy.html.textile.liquid
- user/topics/storage-classes.html.textile.liquid
+ - user/topics/collection-versioning.html.textile.liquid
- Running workflows at the command line:
- user/cwl/cwl-runner.html.textile.liquid
- user/cwl/cwl-run-options.html.textile.liquid
diff --git a/doc/api/methods/collections.html.textile.liquid b/doc/api/methods/collections.html.textile.liquid
index bcd57415d..c68773d90 100644
--- a/doc/api/methods/collections.html.textile.liquid
+++ b/doc/api/methods/collections.html.textile.liquid
@@ -35,7 +35,10 @@ table(table table-bordered table-condensed).
|replication_confirmed_at|datetime|When replication_confirmed was confirmed. If replication_confirmed is null, this field is also null.||
|trash_at|datetime|If @trash_at@ is non-null and in the past, this collection will be hidden from API calls. May be untrashed.||
|delete_at|datetime|If @delete_at@ is non-null and in the past, the collection may be permanently deleted.||
-|is_trashed|datetime|True if @trash_at@ is in the past, false if not.||
+|is_trashed|boolean|True if @trash_at@ is in the past, false if not.||
+|current_version_uuid|string|UUID of the collection's current version. On new collections, it'll be equal to the @uuid@ attribute.||
+|version|number|Version number, starting at 1 on new collections. This attribute is read-only.||
+|preserve_version|boolean|When set to true on a current version, it will be saved on the next versionable update.||
h3. Conditions of creating a Collection
@@ -67,7 +70,7 @@ table(table table-bordered table-condensed).
h3. delete
-Put a Collection in the trash. This sets the @trash_at@ field to @now@ and @delete_at@ field to @now@ + token TTL. A trashed group is invisible to most API calls unless the @include_trash@ parameter is true.
+Put a Collection in the trash. This sets the @trash_at@ field to @now@ and @delete_at@ field to @now@ + token TTL. A trashed collection is invisible to most API calls unless the @include_trash@ parameter is true.
Arguments:
@@ -91,6 +94,11 @@ List collections.
See "common resource list method.":{{site.baseurl}}/api/methods.html#index
+table(table table-bordered table-condensed).
+|_. Argument |_. Type |_. Description |_. Location |_. Example |
+|include_trash|boolean (default false)|Include trashed collections.|query||
+|include_old_versions|boolean (default false)|Include past versions of the collection(s) being listed, if any.|query||
+
Note: Because adding access tokens to manifests can be computationally expensive, the @manifest_text@ field is not included in results by default. If you need it, pass a @select@ parameter that includes @manifest_text at .
h3. update
diff --git a/doc/user/topics/collection-versioning.html.textile.liquid b/doc/user/topics/collection-versioning.html.textile.liquid
new file mode 100644
index 000000000..739c7fd24
--- /dev/null
+++ b/doc/user/topics/collection-versioning.html.textile.liquid
@@ -0,0 +1,189 @@
+---
+layout: default
+navsection: userguide
+title: Using collection versioning
+...
+
+{% comment %}
+Copyright (C) The Arvados Authors. All rights reserved.
+
+SPDX-License-Identifier: CC-BY-SA-3.0
+{% endcomment %}
+
+Collection versioning (if enabled system-wide) adds the possibility to store different collection states as it is modified. Depending on the cluster configuration it can work automatically, but there's also a way to manually control it by the user.
+
+Versioning only triggers when selected collection attributes are updated: @name@, @description@, @properties@ and @manifest_text at .
+When one of these attributes change and the cluster-wide's configured collection idle time is up, or the individual collection's @preserve_version@ attribute is @true@, a new copy is made before saving the changes.
+
+Every collection has a @version@ attribute that indicates its version number, starting from 1 on new collections and incrementing by 1 with every versionable update. Also, all collections point to their most current version via the @current_version_uuid@ attribute.
+
+h3. Accessing past versions of a collection
+
+To request a particular collection with all its versions you should request a list with filters including the collection's UUID and passing the @include_old_versions@ query parameter. For example, using the @arv@ command line client:
+
+<pre>
+$ arv collection index --filters '[["uuid", "=", "o967z-4zz18-ynmlhyjbg1arnr2"]]' --include-old-versions
+{
+ "kind":"arvados#collectionList",
+ "etag":"",
+ "self_link":"",
+ "offset":0,
+ "limit":100,
+ "items":[
+ {
+ "href":"/collections/o967z-4zz18-i3ucessyo6xxadt",
+ "kind":"arvados#collection",
+ "etag":"7bhgspoi4rg9d33o925y8k277",
+ "uuid":"o967z-4zz18-i3ucessyo6xxadt",
+ "owner_uuid":"o967z-tpzed-dvuag6geduje1ub",
+ "created_at":"2018-10-05T14:43:38.916885000Z",
+ "modified_by_client_uuid":"o967z-ozdt8-ac1bob2unkhev15",
+ "modified_by_user_uuid":"o967z-tpzed-dvuag6geduje1ub",
+ "modified_at":"2018-10-05T14:44:31.098019000Z",
+ "name":"Test collection",
+ "description":"This is the first version",
+ "properties":{},
+ "portable_data_hash":"d41d8cd98f00b204e9800998ecf8427e+0",
+ "replication_desired":null,
+ "replication_confirmed":null,
+ "replication_confirmed_at":null,
+ "storage_classes_desired":[
+ "default"
+ ],
+ "storage_classes_confirmed":[],
+ "storage_classes_confirmed_at":null,
+ "delete_at":null,
+ "trash_at":null,
+ "is_trashed":false,
+ "version":1,
+ "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
+ "preserve_version":true
+ },
+ {
+ "href":"/collections/o967z-4zz18-ynmlhyjbg1arnr2",
+ "kind":"arvados#collection",
+ "etag":"1b995we7yilwyh7sc0w746urv",
+ "uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
+ "owner_uuid":"o967z-tpzed-dvuag6geduje1ub",
+ "created_at":"2018-10-05T14:43:38.916885000Z",
+ "modified_by_client_uuid":"o967z-ozdt8-ac1bob2unkhev15",
+ "modified_by_user_uuid":"o967z-tpzed-dvuag6geduje1ub",
+ "modified_at":"2018-10-05T14:44:31.078643000Z",
+ "name":"Test collection",
+ "description":"This is the second (and current) version",
+ "properties":{},
+ "portable_data_hash":"d41d8cd98f00b204e9800998ecf8427e+0",
+ "replication_desired":null,
+ "replication_confirmed":null,
+ "replication_confirmed_at":null,
+ "storage_classes_desired":[
+ "default"
+ ],
+ "storage_classes_confirmed":[],
+ "storage_classes_confirmed_at":null,
+ "delete_at":null,
+ "trash_at":null,
+ "is_trashed":false,
+ "version":2,
+ "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
+ "preserve_version":false
+ }
+ ],
+ "items_available":2
+}
+</pre>
+
+You can also access a past version directly by its UUID:
+
+<pre>
+$ arv collection get --uuid o967z-4zz18-i3ucessyo6xxadt
+{
+ "href":"/collections/o967z-4zz18-i3ucessyo6xxadt",
+ "kind":"arvados#collection",
+ "etag":"1ej4d9klu70bez72cy7yjrz7o",
+ "uuid":"o967z-4zz18-i3ucessyo6xxadt",
+ "owner_uuid":"o967z-tpzed-dvuag6geduje1ub",
+ "created_at":"2018-10-05T14:43:38.916885000Z",
+ "modified_by_client_uuid":"o967z-ozdt8-ac1bob2unkhev15",
+ "modified_by_user_uuid":"o967z-tpzed-dvuag6geduje1ub",
+ "modified_at":"2018-10-05T14:44:31.098019000Z",
+ "name":"Test collection",
+ "description":"This is the first version",
+ "properties":{},
+ "portable_data_hash":"d41d8cd98f00b204e9800998ecf8427e+0",
+ "manifest_text":"",
+ "replication_desired":null,
+ "replication_confirmed":null,
+ "replication_confirmed_at":null,
+ "storage_classes_desired":[
+ "default"
+ ],
+ "storage_classes_confirmed":[],
+ "storage_classes_confirmed_at":null,
+ "delete_at":null,
+ "trash_at":null,
+ "is_trashed":false,
+ "version":1,
+ "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
+ "preserve_version":true
+}
+</pre>
+
+h3. Manually preserving a version
+
+Regardless of the collection's auto-save idle time cluster configuration, the user has the option to request that a particular collection state should be preserved.
+
+When working on a collection, if there's a need to preserve the current state as a new version, the @preserve_version@ attribute should be set to @true at . This will trigger a new version creation on the next update, keeping this "version 2" state as a snapshot.
+
+<pre>
+$ arv collection update --uuid o967z-4zz18-ynmlhyjbg1arnr2 -c '{"preserve_version":true}'
+{
+ "href":"/collections/o967z-4zz18-ynmlhyjbg1arnr2",
+ "kind":"arvados#collection",
+ "etag":"8vhdwnahk8jcr84mqitmd5stu",
+ "uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
+ "owner_uuid":"o967z-tpzed-dvuag6geduje1ub",
+ "created_at":"2018-10-05T14:43:38.916885000Z",
+ "modified_by_client_uuid":"o967z-ozdt8-ac1bob2unkhev15",
+ "modified_by_user_uuid":"o967z-tpzed-dvuag6geduje1ub",
+ "modified_at":"2018-10-05T15:12:57.986454000Z",
+ "name":"Test collection",
+ "description":"This is the second (and current) version",
+ "properties":{},
+ "portable_data_hash":"d41d8cd98f00b204e9800998ecf8427e+0",
+ "manifest_text":"",
+ "replication_desired":null,
+ "replication_confirmed":null,
+ "replication_confirmed_at":null,
+ "storage_classes_desired":[
+ "default"
+ ],
+ "storage_classes_confirmed":[],
+ "storage_classes_confirmed_at":null,
+ "delete_at":null,
+ "trash_at":null,
+ "is_trashed":false,
+ "version":2,
+ "current_version_uuid":"o967z-4zz18-ynmlhyjbg1arnr2",
+ "preserve_version":true
+}
+</pre>
+
+Once the @preserve_version@ attribute is set to @true@, it cannot be manually changed to @false@ and it will only be reset when a versionable update on the collection triggers a new version snapshot.
+
+h3. Collection versions behavior & limitations
+
+Past version collections are read-only, if you need to make changes to one of them, the suggested approach is to copy it into a new collection before updating.
+
+Some attributes get automatically synced when they change on the current version:
+
+* @owner_uuid@
+* @delete_at@
+* @trash_at@
+* @is_trashed@
+* @replication_desired@
+* @storage_classes_desired@
+
+This way, old versions follow the current one on several configurations. In the special case that a current version's UUID gets updated, their past versions get also updated to point to the newer UUID.
+
+Permissions on past versions are the same as their current version, the system does not allow attaching permission links to old versions. If you need to give special access to someone to a particular old version, the correct procedure is by copying it as a new collection.
\ No newline at end of file
-----------------------------------------------------------------------
hooks/post-receive
--
More information about the arvados-commits
mailing list