textDocument/didChange does not number versions according to content changes

[castwide]

I'm working on a language server that uses incremental document syncs. According to the specification, the document's version number should be incremented once for each content change, including when there are multiple changes in a single textDocument/didChange notification. The vscode client conforms in most cases, but occasionally the version number goes out of sync. From my tests, it appears that the most common causes are large copy/pastes, multiple consecutive undo operations, and bulk operations like indenting blocks of code.

Here's a simple reproducible example:

1. Open a file in an editor. (I opened a Ruby file while using my Ruby language server extension).
2. The client sends a textDocument/didOpen notification with the version set to 1.
3. Select 4 lines of code and press tab.
4. The client sends a textDocument/didChange notification with the following parameters:

{
  "textDocument": {
    "uri": "file:///path/to/file.rb",
    "version": 2
  },
  "contentChanges": [
    {
      "range": {
        "start": {
          "line": 3,
          "character": 0
        },
        "end": {
          "line": 3,
          "character": 0
        }
      },
      "rangeLength": 0,
      "text": "  "
    },
    {
      "range": {
        "start": {
          "line": 2,
          "character": 0
        },
        "end": {
          "line": 2,
          "character": 0
        }
      },
      "rangeLength": 0,
      "text": "  "
    },
    {
      "range": {
        "start": {
          "line": 1,
          "character": 0
        },
        "end": {
          "line": 1,
          "character": 0
        }
      },
      "rangeLength": 0,
      "text": "  "
    },
    {
      "range": {
        "start": {
          "line": 0,
          "character": 0
        },
        "end": {
          "line": 0,
          "character": 0
        }
      },
      "rangeLength": 0,
      "text": "  "
    }
  ]
}

Based on the specification, shouldn't the new version number be 5 instead of 2?

[dbaeumer]

I see that the spec is not good formulated here, but the only thing the spec requires is that with every change notification there is a new version number and that the number is increasing. However the number can not be used to indicate the number of internal changes nor must it be the case that the number is consecutive. From the spec:

	/**
	 * The version number of this document (it will increase after each
	 * change, including undo/redo).
	 */
	version: number;

I will add a sentence to the VersionedTextDocumentIdentifier as well.

[castwide]

I may have misunderstood this part of the spec for DidChangeTextDocumentParams:

	/**
	 * The actual content changes. The content changes describe single state changes
	 * to the document. So if there are two content changes c1 and c2 for a document
	 * in state S10 then c1 move the document to S11 and c2 to S12.
	 */
	contentChanges: TextDocumentContentChangeEvent[];

I take it that the referenced document state numbers (S10-S12) are not the same as document version numbers?

[dbaeumer]

No, they are not. They talk about the state of the document. I could have used S' and S'' which I might consider to do to make this more clear.

[dbaeumer]

I made that change.