Merge pull request #7120 from umbraco/cms/add-note-to-unique-media-scheme

Add clarifying detail to documentation about UniqueMediaScheme

Author: eshanrnh

16/umbraco-cms/extending/filesystemproviders/README.md

@@ -140,11 +140,17 @@ You can then access the configured file system provider through `_mediaFileManag
 
 The MediaPath Scheme defines the current set of rules that decide the format of the Media Path when it is saved into the media archive wherever it is located.
 
-By default the MediaPath scheme used by Umbraco is the `UniqueMediaPathScheme` this generates a unique 'folder' to place the uploaded image in eg.
+By default the MediaPath scheme used by Umbraco is the `UniqueMediaPathScheme` this generates a 'folder' to place the uploaded image in, for example:
 
 `/media/dozdrg2f/mylovelyimage.jpg`
 
-`/media` is defined by the PhysicalFileSystem and 'dozdrg2f' is generated by the `UniqueMediaPathScheme`.
+`/media` is defined by the PhysicalFileSystem and `dozdrg2f` is generated by the `UniqueMediaPathScheme`.
+
+{% hint style="info" %}
+The folder generated by `UniqueMediaPathScheme` is not strictly unique, as it's based on the first eight characters of the GUID for the media item. In practice, with randomly generated GUIDs, a collision is unlikely.
+
+There is an increased possibility of generating colliding paths if creating media programmatically and setting keys using version 7 "ordered" GUIDs via `Guid.CreateVersion7()`. As such these should be avoided. `UniqueMediaPathScheme` will throw an exception if it detects they have been used. Any manually created keys should use `Guid.NewGuid()`.
+{% endhint %}
 
 You can create your own logic for the path by implementing `IMediaPathScheme` and setting it during composition with: