Document highlevel filesystem APIs

[chillu]

Overview

The asset abstraction in 4.x changes APIs in major ways, and makes the underlying system a lot more complex - to the point where even core committers like myself can't reliably trace through operations like "does File->delete() delete from the filesystem or not?". This means we need to rely on documentation more strongly.

There's three pages on this topic:
https://docs.silverstripe.org/en/4/developer_guides/files/file_management/
https://docs.silverstripe.org/en/4/developer_guides/files/file_security/
https://docs.silverstripe.org/en/4/developer_guides/files/images/

ACs

• As a seasoned or new SilverStripe dev, I can understand the following:
  • Changed default behaviour of delete() in upgrade guide (this isn't sufficient)
  • An overview of how files are handled in SilverStripe (potentially with a diagram or two?)
  • How protected assets are handled (and it's limitations)
  • How file drafts and publishing it's handled (highlevel, point to detailed versioned docs)
  • How to perform common operations on files and their impact (e.g. rename, move, delete)
  • How relationships are handled to other content (HTMLText, has_many, many_many)
  • Why it's not a good idea to have a has_many on File (or assign $owns on a many_many with files)
  • Image uploads and allowed_extensions restrictions (currently mentioned in "File Security", but too far down the page)

PRs

• DOCS Improve high level file documentation silverstripe-framework#7501