Document Windows compatibility

Author: adamziel

README.md

@@ -103,3 +103,56 @@ bin/regenerate_composer.json.php
 
 This will merge all the package-specific dependencies and the autoload rules into
 the root composer.json file.
+
+### Windows compatibility
+
+Windows compatibility is achieved on a few different fronts:
+
+#### Newlines
+
+This repository comes with a `.gitattributes` file to ensure that the unit test
+files and fixtures are normalized to `\n` on checkout. It's important, because
+Windows uses `\r\n` for newlines in text files. Unix-based systems use `\n`.
+Without the `.gitattributes`, git on Windows would replace all the `\n` with `\r\n` 
+on checkout.
+
+The strings produced by the library uses `\n` for newlines where it can make
+that choice. For example, the `WXRWriter` class will separate XML tags with
+`\n` newlines to make sure the generated XML is consistent across platforms.
+
+#### Paths
+
+The `Filesystem` components makes a point of using Unix-style forward slashes
+as directory separators, even on Windows.
+
+As a library consumer, ensure all the local paths you pass to the library are
+using Unix-style forward slashes as directory separators. A simple str_replace
+will do the trick:
+
+```php
+if (DIRECTORY_SEPARATOR === '\\') {
+	$path = str_replace('\\', '/', $path);
+}
+```
+
+The reason for using Unix-style forward slashes is care for data integrity.
+Windows understands both forward slashes and backslashes, so the replacement
+operation is safe there. On Unix, however, a backslash can be used as a part
+of a filename so it cannot be safely translated.
+
+Importantly, do not just run this str_replace() on every possible path.
+`C:\my-dir\my-file.txt` is both, a valid Windows absolute path and a valid Unix
+filename and a relative path. Furthermore, `Filesystem` supports more filesystems
+than just local disk.
+
+Anytime you're handling paths, consider:
+
+-   Which filesystem is this path related to? Local? Remote? Git?
+-   Which OS are you on? Windows? Unix?
+
+If the answers are "local" and "Windows", you may need to apply the `str_replace()`
+slash normalization. Otherwise, just keep the path as it is.
+
+The takeaway from this section is: **paths are difficult**.
+
+For a fun read on the topic, check out this article: [Windows File Paths](https://www.fileside.app/blog/2023-03-17_windows-file-paths/).