Provide a way to add a timestamp to a comment

[alexr00]

Example of where this could be used: microsoft/vscode-pull-request-github#121

Some ideas for how this could look:

[alexr00]

FYI @laurentlb, I'm planning to start work on this soon.

[laurentlb]

To get a UX consistent with GitHub, I think we'll need two fields:

• one for display (e.g. 2 hours ago or on Aug, 1 2018)
• one for hover (on GitHub, it's used for the full date with timezone). Other extensions could use it to show multiple timezones.

[hermannloose]

I just discussed another idea with @laurentlb:

• have a single timestamp field on Comment objects (most likely a Date)
• allow registering a formatter in CommentController, which when provided, is called with these timestamps and returns a string or optionally a more complex object, e.g. { label: string, tooltip?: string, ...} or {editorLabel: string, editorTooltip?: string, panelLabel: string, panelTooltip?: string}
• provide reasonable default formatting if no formatter was registered

This seems the most flexible with regards to to tailoring an extension (e.g. "our company is in these three timezones, which should be available from the tooltip") as well as allowing a user to easily configure this (e.g. "I want this exact format string for long dates" or "I never want relative dates"), in the settings of an extension, or the settings of core VS Code itself (for the default formatting when no formatter was registered).

edit: For responsive relative dates (specifically "X mins ago"), the formatter would probably also need a way to influence when it is called again for the timestamp of a particular comment. Coming from RXJS, this seems like a fitting place to return an observable—all updates owned by the formatter—but this is not something I have encountered in VS Code code so far. An alternative with more manual house-keeping necessary on the VS Code side would be including another field in the object returned for a formatted date, which indicates when it will go stale. This could be an enum for more constraints from VS Code, e.g. "call me roughly every minute" vs "call me roughly every hour". Alternatively, just a relativeDate: boolean and determine this in VS Code based on the difference between the timestamp and now, at the (mostly theoretical) cost of not performing smoothly for "commented 90 minutes ago".

[alexr00]

Current proposal:

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

Lines 6 to 14 in 96189e4

	declare module 'vscode' {
	export interface Comment {
	timestamp?: {
	date: Date,
	label?: string,
	useRelativeTime?: boolean
	}
	}
	}

[alexr00]

Note from early discussions: We usually leave display decisions up to the users. Instead of having useRelativeTime be part of the API, we could have a setting. If extensions disagree they can always change the default value of the setting.