microsoft / microsoft/language-server-protocol

Clarify use of Title/Message in ProgressStartEvent

Open
#1,025 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

clarification help wanted progress
Dominant language
TypeScript
Stars
13k
Forks
1k
Avg merge
6d 1h
Merged PRs (30d)
10

Description

Currently the title field for ProgressStartEvent says:

Mandatory (short) title of the progress reporting. Shown in the UI to describe the long running operation.

However VS Code allows this field to be set as an empty string and will render it differently (it does not include the colon to join the title/message if the title is an empty string).

I prefer VS Code's behaviour, as I want to send a single string for progress updates, which I can currently do like this:

this.sendEvent(new ProgressStartEvent(debugLaunchProgressId, "", "Launching..."));
this.sendEvent(new ProgressUpdateEvent(debugLaunchProgressId, "Compiling..."));
this.sendEvent(new ProgressUpdateEvent(debugLaunchProgressId, "Deploying to Device..."));

This results in the status bar showing:

Launching...
Compiling...
Deploying to Device...

This is what I want. However, if title is intended to not be an empty string, I cannot generate the strings I want, as they will all be prefixed:

this.sendEvent(new ProgressStartEvent(debugLaunchProgressId, "Launching..."));
this.sendEvent(new ProgressUpdateEvent(debugLaunchProgressId, "Compiling..."));
this.sendEvent(new ProgressUpdateEvent(debugLaunchProgressId, "Deploying to Device..."));

Results in:

Launching...
Launching...: Compiling...
Launching...: Deploying to Device...

I could live with the "Launching:" prefix, but having the "..." looks weird. And if I remove it from the original message, then it is inconsistent with the others (and I'd like to keep it to be consistent with other messages shown in the status bar by VS Code, for example the "Building..." notification from TypeScript).

So for now I'm going to ship sending an empty string for title on the assumption that VS Code's behaviour is reasonable, and other clients will follow - however I think the spec should be more explicit about whether this is allowed (and if it's not, there should be a way to replace a single-string status message rather than forcing the x:b format when wanting to update).

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the ProgressStartEvent definition and its title description, then compare the documented behavior with the VS Code examples in the issue. Done means the specification clearly states whether an empty title is allowed and explains how single-string progress updates should be represented.

Written by the indexing model from the issue text.

Assessment

Tech stack
vscode
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.