Add better documentation on how clients should handle file renames

[Kered13]

I am in the process of implementing an LSP client, but reading the spec I cannot figure out how I should handle file renames.

• There are the workspace/willRenameFiles and workspace/didRenameFiles methods, but servers are not required to support them.
• The other logical option seems to be to issue a textDocument/didClose followed by a textDocument/didOpen with the new file name.
• If a server does support the workspace operations, should didClose and didOpen still be sent?
• If so, then should they be sent before or after willRenameFiles and didRenameFiles?

[dbaeumer]

Good point. The recommended way on a file rename is to sent a close with the old file and a open with the new file.

[DanTup]

The recommended way on a file rename is to sent a close with the old file and a open with the new file.

Slightly related to #1263 - what about if the rename is only changing case?

Right now, VS code does not send a Close/Open in this case for macOS or Windows (regardless of whether the filesystem is actually case-sensitive or not). However it does send rename events (but continues to use the old casing for everything going forwards). This seems inconsistent and makes it difficult for servers to handle these types of renames.

[dbaeumer]

I personally think that using whatever name the system started to use on case insensitive file systems is the right thing to do. There is actually no guarantee that the initial name had the casing as stored on disk.