Add a notion of pending / draft state to code review comments

[hermannloose]

#127473 introduced CommentThreadState with Unresolved and Resolved values to indicate the actionable vs non-actionable state of a particular conversation in code review.

In addition to that, GitHub pull requests and other code review systems frequently treat new comment threads or specific replies added by a user as pending / draft, being visible only to the user until they publish all pending comments at the same time.

We propose adding a new field to Comment objects to model this state.

For type, we think a boolean might be enough, but similar to #127473 we might want to use an enum instead for flexibility.

We don't have a preference for a particular name, draft, pending, or published (with inverse semantics) would all work well.

Areas in VS Code that would benefit from having a draft state:

• the line gutter and the comments panel could render different icons for threads with drafts, to better indicate to users which conversations they have already replied to, for overview
• there could be built-in commands to expand or collapse threads with drafts in the editor, so that users can hide threads that they have already replied to
• the filtering functionality in the comments panel could have an option to "Show Drafts" so that users can hide threads they have already replied to

cc @laurentlb @JonasMa

[alexr00]

The GitHub Pull Requests extension uses the Comment label for this.

[hermannloose]

@alexr00 This is also our current approach, but it's text-only and does not enable the other use cases.

I also realized I didn't make it very explicit above that the three listed use cases all work on the level of threads, not individual comments / replies. They rely on a notion of a CommentThread being in a state of "having drafts" (orthogonal to whether the thread is unresolved or resolved) whenever one of its Comment children is a draft. The exact mechanics of this would still need to be formalized.

[hermannloose]

@alexr00 I opened a PR so we have something more concrete to discuss. As mentioned, we are very flexible regarding the naming, this is just a starting point.

[alexr00]

Proposal:

vscode/src/vscode-dts/vscode.proposed.commentsDraftState.d.ts

Lines 10 to 21 in cc614c8

	export enum CommentVisibility {
	Published = 0,
	Draft = 1
	}
	export interface Comment {
	visibility?: CommentVisibility;
	}
	export interface CommentThread {
	readonly hasDraftComments: boolean;
	}

[alexr00]

Adding to the March milestone for discussion.

[alexr00]

Notes from early API discussion:

• We should not have hasDraftComments in CommentThread as this is sugar, which we try to avoid in API.
• Comment visibility can be state to better align with CommentThread state. CommentVisibility would then likely follow and be CommentState.
• We don't have a good suggestion yet for what to name the values of CommentState/CommentVisibility. There isn't a good precedent in the API. Since one of the consumers of this API would be GitHub Pull Requests and Issues, we could match GitHub and say Pending, as this would also be reflected in the UI and would be consistent with GitHub. However, "pending" actually doesn't describe well that the comment is not yet available to other users.

[hermannloose]

I updated #173305 to remove hasDraftComments. Is there a rough timeline for the other decisions?

[alexr00]

@hermannloose this isn't planned work, so I don't have time allocated for it at the moment. I intend to take another look at this next week and I'll try to put it on the plan for April if I don't get to it next week.

[alexr00]

Latest proposal:

https://github.com/hermannloose/vscode/blob/55d18a49229350e2d8f7808418e6eb6aa7ccef35/src/vscode-dts/vscode.proposed.commentsDraftState.d.ts#L10-L17