add versioning vignette to close #77

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: deposits
 Title: A universal client for depositing and accessing research data
     anywhere
-Version: 0.2.1.033
+Version: 0.2.1.034
 Authors@R: 
     person("Mark", "Padgham", , "[email protected]", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0003-2172-5265"))

codemeta.json

@@ -7,7 +7,7 @@
   "codeRepository": "https://github.com/ropenscilabs/deposits",
   "issueTracker": "https://github.com/ropenscilabs/deposits/issues",
   "license": "https://spdx.org/licenses/MIT",
-  "version": "0.2.1.033",
+  "version": "0.2.1.034",
   "programmingLanguage": {
     "@type": "ComputerLanguage",
     "name": "R",

vignettes/frictionless.Rmd

@@ -4,7 +4,7 @@ author:
   - "Mark Padgham"
 date: "`r Sys.Date()`"
 vignette: >
-  %\VignetteIndexEntry{5. frictionless}
+  %\VignetteIndexEntry{6. frictionless}
   %\VignetteEngine{knitr::rmarkdown}
   %\VignetteEncoding{UTF-8}
 ---

vignettes/versioning.Rmd

@@ -0,0 +1,102 @@
+---
+title: "The deposits package"
+author: 
+  - "Mark Padgham"
+date: "`r Sys.Date()`"
+vignette: >
+  %\VignetteIndexEntry{5. Publication and versioning}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r setup, include=FALSE}
+knitr::opts_chunk$set (
+    collapse = TRUE,
+    warning = TRUE,
+    message = TRUE,
+    width = 120,
+    comment = "#>",
+    fig.retina = 2,
+    fig.path = "README-"
+)
+```
+
+The
+[main](https://docs.ropensci.org/deposits/articles/deposits.html#publishing-a-deposit)
+and [example
+workflow](https://docs.ropensci.org/deposits/articles/workflow.html#publishing-a-deposit)
+vignettes both finish with publication. While publication of data may often be
+viewed as a singular act, after which data remain indefinitely available in the
+same static state in which they were first published, data may also evolve and
+develop after initial publication. The versioning abilities of deposits allow
+for updated versions of deposits to be created and published. A single static
+URL will then generally resolve to the latest published version, yet all
+previous versions will also remain accessible.
+
+Not all host systems have explicit interfaces for version control, and so
+deposits offers two distinct versioning process: one for host systems which
+explicitly record version numbers, and another for those without. In all cases,
+versioning is only applicable to *published* deposits. Private deposits may
+only exist in a single version, and these versioning functions will generally
+not be able to be applied.
+
+# Explicit version control
+
+Zenodo offers explicit control over versioning, enabling all aspects including
+version numbers of deposits, to be specified and updated when desired. This
+vignette presumes that a copy of a published deposit also exists locally, and
+that aspects of data and/or metadata in this local version have been updated,
+and so differ from those in the published version. The first step is to
+retrieve the published version, and fill a client with the updated metadata.
+This is done by passing the local `path` to the directory containing the
+deposit to the [`deposit_fill_metadata()`
+method](https://docs.ropensci.org/deposits/reference/depositsClient.html#method-deposit-fill-metadata-)
+method. This code also uses the Zenodo "sandbox" environment to trial the
+functions without publication on Zenodo itself.
+
+```{r dep-retr, eval = FALSE}
+library (deposits)
+cli <- depositsClient$new (service = "zenodo", sandbox = TRUE)
+my_id <- cli$deposits$id [1] # select deposit to retreive
+cli$deposit_retrieve (my_id)
+# path <- "/<local>/<path>/<to>/<deposit>/"
+path <- "/data/mega/code/repos/pre-processing-r/typetracer"
+cli$deposit_fill_metadata (path)
+```
+
+A new version can then be created by calling:
+
+```{r dep-version, eval = FALSE}
+cli$deposit_version ()
+```
+
+The client will then reveal a different, updated deposit ID value and
+corresponding URL. Clicking on that (or copying into a web browser) will then
+open a page in "edit" mode, containing the updated metadata fields. The new
+version can then be published with the [`deposit_publish()`
+method](https://docs.ropensci.org/deposits/reference/depositsClient.html#method-deposit-publish-).
+The primary URL of the deposit will then resolve to the latest published
+version.
+
+# Services without explicit version control
+
+Figshare does not offer explicit control of versions. Instead, a deposit may be
+edited at any time. Re-publishing an edited deposit then increments an internal
+version number, from 1 to 2 for a first version, and further increments for
+subsequent versions. The [`deposit_version()`
+method](https://docs.ropensci.org/deposits/reference/depositsClient.html#method-deposit-version-)
+described above only applies to service with explicit version control. New
+versions on Figshare may be created from deposits by updating metadata (for
+example, by using the [`deposit_fill_metadata()`
+method](https://docs.ropensci.org/deposits/reference/depositsClient.html#method-deposit-fill-metadata-)
+demonstrated above, and then calling these two methods:
+
+```{r dep-version-fs, eval = FALSE}
+cli$deposit_update ()
+cli$deposit_publish ()
+```
+
+The only difference to the workflow for Zenodo is that [`deposit_update()`
+method](https://docs.ropensci.org/deposits/reference/depositsClient.html#method-deposit-update-)
+is called instead of [`deposit_version()`
+method](https://docs.ropensci.org/deposits/reference/depositsClient.html#method-deposit-version-).