Speclet for terminallogger progress

terminal-logger-progress.md

Progress speclet

• allows to specify the progress of the task
• allows describing the overall operation
• allows describing the 'instant' state
• allows determinate status (x/y)
• allows indeterminate status

Example API usage:

var reporter = LoggingService.GetProgressReporter("Test under linux-x64");
// Terminal Logger at this point starts rendering a progress tracker that looks something like
// Test under linux-x64: [-------------------]

int succeeded = 10;
int failed = 5;
int skipped = 2;
int total = 100;

// run tests

// periodically report progress. percentage is optional, if not specified an indeterminate progress is shown
// description is optional, if not specified only a progress bar is shown
// if description is too long to render a reasonable progress, description may be truncated
reporter.ReportProgress(percentage: (10 + 5 + 2)/100, description: $"{succeeded} succeeded, {failed} failed, {skipped} skipped");
// Terminal Logger at this point renders a progress tracker that looks something like
//      Test under linux-x64: [##########---------] 10 succeeded, 5 failed, 2 skipped (17%)
// NOTE: the layout coulod change - for example this might also be viable:
//      Test under linux-x64: [##########---------(10 succeeded, 5 failed, 2 skipped)] (17%)
// The key concept is that these are just rearrangements of the same core sections (defined below).

// finish the operation
reporter.CompleteProgress(finalMessage: $"{succeeded} succeeded, {failed} failed, {skipped} skipped, {total} tests run.");
// the MSbuild Logging engine would send a final summary message to the binlog
// terminal logger may show the completed progress item for a period of time, but the progress-reporting area may clear 
// as the overall projects are completed.

The overall progress reporting in Terminal Logger specifically should be thought of as a new 'area' of the rendering. Today we have a 'project summary' area and a 'node status' area. Progress would be reported in a new area in between the two. Each progress item would have its own line, and each line would have up to 4 components:

• The name of the progress item, set by GetProgressReporter
• The progress bar, which is a visual representation of the progress. This could be showing a known or unknown quantity of work items.
• An optional description, which is a textual representation/summary of the progress shown in the bar.
• An optional percentage, which is shown if the progress is deterministic.

Questions for the engine:

• what frequency/how should messages from child nodes be sent to the central node, to not swamp the system?
• how should rendering of the description be controlled? Is allowing users to emit their own ANSI codes for color/etc fine for now?

References:

• Work Done Progress in the LSP Spec

Some kind of IsEnabled flag would need to be available for Managed Code Task authors and MSBuild logic authors to see if progress reporting is supported for the current session to avoid taking the perf hit.