Document how converters should provide notifications

[ghost]

Copied from sarif-standard/sarif-spec-v1#144, created by @michaelcfanning:

Should we provide a way for a converter to communicate that something strange happened during conversion? What about tools that process existing log files and add some notes/observations? Not a breaking change to extend the enum.

[ghost]

Comment from @lgolding:

These belong in toolNotifications. Converters can specify a distinguished notification.id. It could even be something like PREfastConverter.1, .2, ...

The message should also make it clear who produced the notification.

[ghost]

Comment from @lgolding:

@michaelcfanning Do you agree that these should be toolNotifications with a distinguished id, or do you have another suggestion?

[ghost]

Notes from TC con call 2017/09/27:

• Need to mark a file as having been the result of a conversion.
• Need to distinguish notifications produced by the source tool from those produced by the converter.

JimKupsch suggests "provenance" -- tell which native tool output file was converted, and which converter version was used to convert it.

Do we want a chain of these?

toolNotification could say which numeric index into the provenance array was the source of the notification.

[DerSaidin]

A tool could merge multiple input reports. A linear chain may be insufficient.

[michaelcfanning]

another possibility is adding converter specific notifications property

[ghost]

@michaelcfanning I like the idea of a "converter specific notifications property". Now that we have a conversion object, that's the natural place for it conversion.notifications. I'll write the change draft that way.