DOC Document replacing Path class with Symfony's Path class

en/08_Changelogs/6.0.0.md

@@ -23,6 +23,7 @@ title: 6.0.0 (unreleased)
   - [Changes to some extension hook names](#hooks-renamed)
   - [Strict typing for `Factory` implementations](#factory-strict-typing)
   - [Elemental `TopPage` class names changed](#elemental-top-page)
+  - [`Path` class removed](#path-removed)
   - [General changes](#api-general)
 - [Other changes](#other-changes)
   - [MySQL 5 no longer supported](#mysql-5-support)
@@ -367,6 +368,23 @@ The class names for the `TopPage` feature in [`dnadesign/silverstripe-elemental`
 
 If you reference any of these classes in your project or module, most likely in config if you have [`tractorcow/silverstripe-fluent`](https://github.com/tractorcow/silverstripe-fluent) installed, then you will need to update the references to the new class names.
 
+### `Path` class removed {#path-removed}
+
+The `SilverStripe\Core\Path` class has been removed. If you were using this class, use the `Symfony\Component\Filesystem\Path` class from [`symfony/filesystem`](https://github.com/symfony/filesystem) instead.
+
+Both of these classes have been included in recent installations of Silverstripe CMS, leading to confusion about which one to use. The two classes work subtly differently, so while usually the results would be the same, sometimes they would differ. Removing the class in silverstripe/framework removes the confusion about which class to use.
+
+The important differences to note are:
+
+- `SilverStripe\Core\Path::normalise()` would strip trailing (and optionally leading) slashes and white space. The Symfony class does not.
+- `SilverStripe\Core\Path::join()` would throw an exception if any of the paths passed in included `..`, which prevented path traversal. The Symfony class allows path traversal.
+
+This means when using `Path::join()` you will need to consider whether the paths you're joining can be trusted, and whether path traversal could lead to a potential vulnerability in that scenario. The upside is that you *can intentionally* use `../` to traverse paths when that's useful for your business logic.
+
+See [Symfony documentation](https://symfony.com/doc/current/components/filesystem.html#path-manipulation-utilities) for documentation on Symfony's `Path` class.
+
+See [the OWASP website](https://owasp.org/www-community/attacks/Path_Traversal) for more information about path traversal vulnerabilities.
+
 ### General changes {#api-general}
 
 - [`DataObject::write()`](api:SilverStripe\ORM\DataObject::write()) has a new boolean `$skipValidation` parameter. This can be useful for scenarios where you want to automatically create a new record with no data initially without restricting how developers can set up their validation rules.