Increase documentation of forceVersion in syncToSynapse

Description

`syncToSynapse` calls `store`, which has the parameter `forceVersion` with a default of `True`. This seems counter-intuitive since I would expect the default to be not forcing the re-upload and versioning of files that have not changed. Highlighting the need for a `forceVersion` column in the manifest if not wanting to re-upload the files would be helpful `syncToSynapse` documentation.

For example, we have had data contributors upload their bulk data using a manifest without annotation columns. We could have them update the annotations using a file view. However, we are requiring them to validate the manifest to ensure that it includes all required annotations and they are valid. Since they should have this manifest already and we want to encourage/train contributors to upload using the validated manifest, this is the approach we have chosen in these cases.

Currently, the documentation says:


Manifest file format

The format of the manifest file is a tab delimited file with one row per file to upload and columns describing the file. The minimum required columns are path and parent where path is the local file path and parent is the Synapse Id of the project or folder where the file is uploaded to. In addition to these columns you can specify any of the parameters to the File constructor (name, synapseStore, contentType) as well as parameters to the syn.store command (used, executed, activityName, activityDescription, forceVersion). Used and executed can be semi-colon (“;”) separated lists of Synapse ids, urls and/or local filepaths of files already stored in Synapse (or being stored in Synapse by the manifest). Any additional columns will be added as annotations.


I'm proposing updating this with more emphasis on `forceVersion` (suggested addition in bold):


Manifest file format

The format of the manifest file is a tab delimited file with one row per file to upload and columns describing the file. The minimum required columns are path and parent where path is the local file path and parent is the Synapse Id of the project or folder where the file is uploaded to. In addition to these columns you can specify any of the parameters to the File constructor (name, synapseStore, contentType) as well as parameters to the syn.store command (used, executed, activityName, activityDescription, forceVersion). For only updating annotations without uploading new versions of unchanged files, the syn.store parameter forceVersion should be included in the manifest with the value set to False. Used and executed can be semi-colon (“;”) separated lists of Synapse ids, urls and/or local filepaths of files already stored in Synapse (or being stored in Synapse by the manifest). Any additional columns will be added as annotations.


This also arises in the Synapse docs for uploading/editing in bulk. I already created an issue in GitHub to update the Synapse docs with more clarifying information. I am fine with updating that article and only requesting this team to update the Python documentation for clarification.

Environment

None
Your pinned fields
Click on the next to a field label to start pinning.

Assignee

Jordan Kiang

Reporter

Nicole Kauer

Validator

Bruce Hoff