docs(user): clarify deleted files and storage quotas

user_manual/files/deleted_file_management.rst

@@ -1,58 +1,127 @@
-======================
-Managing deleted files
-======================
+=============
+Deleted files
+=============
 
-When you delete a file in Nextcloud, it is not immediately deleted permanently,
-only moved into the trash bin. It is not permanently deleted until you manually
-delete it, or when the Deleted Files app deletes it to make room for new files.
+When you delete a file or folder in Nextcloud, it is normally moved to the
+trash bin instead of being deleted immediately. This allows you to restore it
+later.
 
-Find your deleted files by clicking the **Deleted files** button on the Files
-page of the Nextcloud web interface. You can restore or permanently delete files from there.
+Items in the trash bin are permanently deleted when one of the following
+occurs:
+
+- You manually select *Delete permanently*.
+- The Deleted Files app removes the item according to the configured retention
+  policy.
+- The effective trash-bin size limit is exceeded and the item is eligible for
+  removal to free space.
+
+Find your deleted files by selecting **Deleted files** in the Files area of the
+Nextcloud Web interface. From there, you can restore items, download them to
+your device, or delete them permanently.
+
+When you restore an item, Nextcloud normally attempts to return it to its
+original location. If that location no longer exists or is not writable, the
+item is restored to the root of your Files area. If an item with the same name
+already exists, Nextcloud gives the restored item a unique name.
+
+.. note:: If the Versions app is enabled, versions associated with a deleted
+   file are moved to the trash bin and are restored when the file is restored.
 
 Quotas
 ------
 
-Deleted files are not counted against your storage quota. Only your personal
-files count against your quota, not files which were shared with you.
-(See :doc:`quota` to learn more about quotas.)
+Files and folders in your trash bin do not count against your normal storage
+quota.
+
+See :doc:`quota` for more information about how storage quotas are calculated.
 
 What happens when shared files are deleted
 ------------------------------------------
 
-Deleting files gets a little complicated when they are shared files, as this
-scenario illustrates:
-
-1. User1 shares a folder "test" with User2 and User3
-2. User2 (the recipient) deletes a file/folder "sub" inside of "test"
-3. The folder "sub" will be moved to the trash bin of both User1 (owner) and
-   User2 (recipient)
-4. But User3 will not have a copy of "sub" in their trash bin
-
-When User1 deletes "sub" then it is moved to User1's trash bin. It is
-deleted from User2 and User3, but not placed in their trash bins.
-
-When you share files, other users may copy, rename, move, and share them with
-other people, just as they can for any computer files; Nextcloud does not have
-magic powers to prevent this.
-
-How the deleted files app manages storage space
------------------------------------------------
-
-To ensure that users do not run over their storage quotas, the Deleted Files
-app allocates a maximum of 50% of their currently available free space to
-deleted files. If your deleted files exceed this limit, Nextcloud deletes the
-oldest files (files with the oldest timestamps from when they were deleted)
-until it meets the memory usage limit again.
-
-Nextcloud checks the age of deleted files every time new files are added to the
-deleted files. By default, deleted files stay in the trash bin for 30 days. The
-Nextcloud server administrator can adjust this value in the ``config.php`` file
-by setting the ``trashbin_retention_obligation`` value. Files older than the
-``trashbin_retention_obligation`` value will be deleted permanently.
-Additionally, Nextcloud calculates the maximum available space every time a new
-file is added. If the deleted files exceed the new maximum allowed space
-Nextcloud will permanently delete those trashed files with the soonest expiration
-until the space limit is met again.
-
-.. note:: Your administrator may have configured the trash bin retention period
-   to override the storage space management. See `admin documentation <https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/config_sample_php_parameters.html#deleted-items-trash-bin>`_ for more details.
+The behavior of deleted shared files depends on who deletes the item and who
+owns it.
+
+For example, User1 shares a folder named ``TheProject/`` with User2 and User3:
+
+1. User2, a share recipient (sharee), deletes a folder or file named
+   ``Phase2`` inside ``TheProject/``.
+
+   ``TheProject/Phase2`` is moved to the trash bin of User1, the owner, and a
+   copy is placed in User2's trash bin when possible. The item is removed from
+   the shared folder for User3, but User3 does not receive a copy in their
+   trash bin.
+
+2. User1, the owner, deletes ``TheProject/Phase2``.
+
+   The item is moved to User1's trash bin and removed from the shared folder for
+   User2 and User3. It is not placed in their trash bins.
+
+The exact behavior can depend on the type of share and the permissions granted
+by the share. Depending on those permissions, other users may be able to copy,
+rename, move, or re-share shared files. These operations can affect which
+account owns the resulting files and which trash bin receives a deleted item.
+
+.. note::
+
+   When a sharee deletes an item owned by another user, Nextcloud moves the item
+   to the owner's trash bin. A copy in the deleting user's trash bin is also
+   created (in most cases; the copy is on a best-effort basis and is not
+   guaranteed).
+
+How the Deleted Files app manages storage space
+------------------------------------------------
+
+The Deleted Files app manages trash-bin contents using two related rules:
+
+- A storage limit determines how much space the trash bin may use.
+- A retention policy determines when deleted items become eligible for
+  permanent deletion.
+
+Trash-bin storage limit
+~~~~~~~~~~~~~~~~~~~~~~~
+
+For accounts with a storage quota, the default trash-bin limit is up to 50% of
+the account's remaining quota space. This is calculated after the account's
+active files have been taken into account; it is not 50% of the account's total
+quota.
+
+For example, if your quota is 10 GB and your active files use 8 GB, the default
+trash-bin allowance is calculated from the remaining 2 GB.
+
+For accounts without a storage quota, the default limit is calculated using
+available filesystem space instead. Your administrator can override either
+default by configuring a global or per-account trash-bin size.
+
+When the effective trash-bin limit is exceeded, Nextcloud removes eligible
+deleted items, starting with the oldest items, until the limit is satisfied
+again.
+
+Retention and permanent deletion
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, deleted files are retained for at least 30 days. After that,
+eligible items may be permanently deleted when space is needed; they are not
+necessarily deleted immediately after 30 days.
+
+Your administrator can configure different minimum and maximum retention
+periods. Depending on the configuration, items may be permanently deleted
+after a maximum age even when storage space is not currently needed. Automatic
+expiration can also be disabled.
+
+For policies with a configured minimum retention period, an item is eligible
+for space-based cleanup only after that period has elapsed. Policies without a
+minimum retention period may allow space-based cleanup regardless of the
+item's age. Items that have exceeded a configured maximum retention period can
+be permanently deleted regardless of whether space is currently needed.
+
+The relevant configuration setting is
+``trashbin_retention_obligation``. For details about the available values and
+their interaction with quotas and trash-bin sizes, see the
+`Deleted Files section of the Administrator Manual
+<https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/trashbin_configuration.html>`_.
+
+.. note::
+
+   The Deleted Files app may permanently delete an item before its maximum
+   retention period when the effective trash-bin limit is exceeded and the
+   item's minimum retention period has elapsed.

user_manual/files/quota.rst

@@ -2,38 +2,52 @@
 Storage quota
 =============
 
-Your Nextcloud administrator has the option to set a storage quota on users. Look at
-your Personal page to see what your quota is, and how much you have used.
+Your Nextcloud administrator can set a storage quota for your account. Open
+your Personal settings page to see your quota and how much storage you have
+used.
 
 .. figure:: ../images/quota1.png
    :alt: Storage quota indicator on the Personal page
 
 It may be helpful to understand how your quota is calculated.
 
-Metadata (thumbnails, temporary files, cache, and encryption keys) takes up
-about 10% of disk space, but is not counted against user quotas. Some apps
-store information in the database, such as the Calendar and Contacts apps. This
-data is excluded from your quota.
+Metadata such as thumbnails, temporary files, caches, and encryption keys can
+use disk space without counting against your user quota. Some apps store data
+in the database, such as the Calendar and Contacts apps. This data is not
+included in the file-storage quota.
 
-When other users share files with you, the shared files count against the
-original share owner's quota. When you share a folder and allow other users or
-groups to upload files to it, all uploaded and edited files count against your
-quota. When you re-share files shared with you, the re-share still counts
-against the quota of the original share owner.
+When other users share files with you, the shared files normally count against
+the original owner's quota. When you share a folder and allow other users or
+groups to upload or edit files in it, those files count against your quota.
+When you re-share files shared with you, the re-share normally continues to
+count against the original owner's quota.
 
-Encrypted files are a little larger than unencrypted files; the unencrypted size
-is calculated against your quota.
+Encrypted files can use more physical storage than unencrypted files. The
+quota calculation uses the file size reported by Nextcloud's storage layer.
 
-Deleted files that are still in the trash bin do not count against quotas. The
-trash bin is set at 50% of quota. Deleted file aging is set at 30 days. When
-deleted files exceed 50% of quota then the oldest files are removed until the
-total is below 50%.
+When the Versions app is enabled, older file versions are managed separately
+from the normal storage quota according to the app's retention and storage
+rules.
 
-.. note:: Your administrator may have configured the trash bin retention period
-   to override the storage space management. See `administrator documentation <https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/config_sample_php_parameters.html#deleted-items-trash-bin>`_ for more details.
+If you create a public share through a URL and allow uploads, uploaded files
+count against your quota.
 
-When version control is enabled, the older file versions are not counted against
-quotas.
+Deleted files and the trash bin
+-------------------------------
 
-If you create a public share via URL and allow uploads, any uploaded files
-count against your quota.
+Files and folders in your trash bin do not count against your normal storage
+quota. The trash bin nevertheless has its own storage limit.
+
+For accounts with a quota, the default amount of space available to the trash
+bin is calculated as 50% of the account's remaining quota space. This is
+calculated after the account's active files have been taken into account; it is
+not 50% of the total quota.
+
+For accounts without a quota, the default trash-bin limit is calculated using
+available filesystem space instead. An administrator can configure a global or
+per-account trash-bin size that overrides the calculated default.
+
+Your administrator can also configure minimum and maximum trash-bin retention
+periods, or disable automatic expiration. See the `Deleted Files section of the Administrator Manual
+<https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/trashbin_configuration.html>`_
+for details.