The LSP spec does not state anywhere that the result has to be ordered - therefore, I'd say that clients should not rely on this behavior (https://microsoft.github.io/language-server-protocol/specification#textDocument_references).

Is there a reason that the client cannot apply this ordering? VSCode definitely orders results, so it seems redundant to me for us to guarantee ordering, when more likely than not, the client will redo the sort.

Is there a reason that the client cannot apply this ordering?

No reason, other than perhaps there being a sensible default that the server might want to offer to clients so that they don't have to do the work themselves.

But just to note: the current state means that the results sent from server to client will not be stable, which is a problem if you're looking to assert in tests against the behaviour of gopls at a high-level input/output.

Thanks for bringing this to our attention! We do not want to commit to sorting the returned results at this time since it is not in the spec.

Thanks @suzmue @stamblerre.

Quite agree that this isn't specified in the LSP spec, which I think means that one can in fact argue that returning sorted results is just as correct/valid as returning them in a random order.

In addition to the points about it being a sensible default from the client's perspective and making testing easier, I think it's also more intuitive that for a list response type the order is defined, whether in the spec or the implementation.

All that said, very happy to defer 😄

Use of the references method has just landed in govim (govim/govim#291) so thanks again for the work to get this into gopls!

Re-opening this issue to continue discussion on the following specific point.

The textDocument/references method parameter is defined as follows:

interface ReferenceParams extends TextDocumentPositionParams {
	context: ReferenceContext
}

interface ReferenceContext {
	/**
	 * Include the declaration of the current symbol.
	 */
	includeDeclaration: boolean;
}

From govim, we set includeDeclaration: true. This means we're expecting the declaration to be one of the locations returned.

To my mind I think it's most intuitive to have the declaration as the first location, hence we should define that this is what gopls will do, regardless of whether it then sorts the remaining results or not.

What do you think?

Yes, that makes sense. Thanks for pointing that out.

Until find references is supported at a project level (#32869), this would mean that find references would return all of the references in the current package + the declaration from the other package (if includeDeclaration=true).

Change https://golang.org/cl/184723 mentions this issue: internal/lsp: include declaration for references

Looks like the CL above fixed the problem. Please re-open if there's anything else we should do here.