The administrator manual has a section called “Controlling file versions and aging”(Controlling file versions and aging — Nextcloud latest Administration Manual latest documentation). From what I can understand, it describes an app that erases old versions of files following a defined strategy. It is implied that functionality for creating versions is provided elsewhere on a deployment, but I find no other description of versions in the documentation.
How are versions created? Is automatic? With every update? Is it manual? What access to or control over versions are available from a client, either the official synchronization client or a third-party client using the web services API?
Does anyone know of a reference that explains the function and features of versions (not simply how to limit their accumulation) in Nextcloud, or would someone kind please offer a brief explanation in a response?
File versioning happens automatically by default. It technically uses the Versions app but that is built in and maintained by the core Nextcloud team, so you can think of it as a built in feature (but can be disabled if you want). The Admin guide you referenced talks about the default settings and how to adjust them, but perhaps what you’re asking for is provided in the User guide which talks more about how to view and restore file versions as an end user (https://docs.nextcloud.com/server/stable/user_manual/files/version_control.html).
File versions are automatically created every time a changed file is synced (you save a file, the client syncs it, then you make changes to that file and it gets synced again, etc.).
As far as I know, you can only access previous file versions from the browser. There is no way through the official client on Windows, Android, or Linux that I know of. I can’t say for sure, but that would indicate that they may not have support (yet) for file versions through the API.
How to: Basically sync files, and whenever the need arises to go back to a previously saved version of that file, log into your account through the browser, open the details for that file, and restore a previous version.
I also found yet a different description of the Versions app by clicking on it in the apps listing in a working Nextcloud installation.
This application automatically maintains older versions of files that are changed. When enabled, a hidden versions folder is provisioned in every user’s directory and is used to store old file versions. A user can revert to an older version through the web interface at any time, with the replaced file becoming a version. The app automatically manages the versions folder to ensure the user doesn’t run out of Quota because of versions. In addition to the expiry of versions, the versions app makes certain never to use more than 50% of the user’s currently available free space. If stored versions exceed this limit, the app will delete the oldest versions first until it meets this limit. More information is available in the Versions documentation.
I think you make a good point though, that information should be easier to find and I also think it should definitely be available without having to first install Nextcloud.
Usually if you want things to change, it’s best to submit a new issue on Github (Issues · nextcloud/server · GitHub). What do you think, should this be made more clear in the admin guide, the user guide, or both?
In my experience, the issue tracking system attached to a source repository is not the preferred place to consider problems with documentation, but rather for items inside of the code base, such as bugs. Of course some projects have different conventions. I would be reluctant to submit this request I unless I know it is welcome.
The appropriate manual for the information depends specifically on the information. Plainly, the user manual should instruct users when versions are or are not made, how they can be managed by users in individual instances, and how their experience may be affected by site policies set by their administrators. The administrative manual in turn should explain in as much detail as feasible what options are available, what limitations are known, and how their decisions affect user experience and utilization of system resources.
You’re right, I wasn’t thinking about it but it would make more sense to open an issue on their documentation tracker which is also on Github: https://github.com/nextcloud/documentation/issues