[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Quasi-editorial change: the "baseline run"
Please read to the end for a not-quite-editorial change that you might want to comment on.
At TC #18, while reviewing the new values for file.roles, we discussed how to specify the run to which the files marked with these roles should be compared. It turns out that we had already encountered this issue with result.baselineState, where we wrote:
If the baselineId property (§3.11.4) of the containing run object (§3.11) is present, the baseline SHALL be the run specified by that baselineId.
If the baselineId property of the containing run object is absent, then a SARIF consumer will need out of band information available to determine the baseline.
But we can do better, now that we have the “Engineering system” conformance profile. So, following our usual practice of abstracting a concept we’ve encountered twice, we introduce the following definition in the Terminology section:
With that definition in hand, we can improve our description of result.baselineState:
A result object MAY contain a property named baselineState whose value is a string that specifies the state of this result with respect to some previous run, which we refer to as the “baseline run.”
If baselineInstanceGuid (§3.11.4) is present on the containing run object (§3.11), its value SHALL specify the baseline run. If baselineInstanceGuid is absent, the engineering system SHALL provide out of band information that determines the baseline run.
… and we can then use similar language for the new values of file.roles:
The following role values denote files that have changed since the “baseline run”. If baselineInstanceGuid (§3.11.4) is present on the containing run object (§3.11), its value SHALL specify the baseline run. If any of these role values are present but baselineInstanceGuid is absent, the engineering system SHALL provide out of band information that determines the baseline run.
NOTE: The statement that the new roles can be computed with respect to a run other than baselineInstanceGuid is not an editorial change. That is a substantive change that we agreed on in TC #18. The editorial change is to introduce that term “baseline run” and to use similar (and improved) language.
NOTE: Technically speaking, the new normative statement that “the engineering system SHALL provide out of band information…” – as opposed to the previous non-normative statement that “a SARIF consumer will need out of band information…” – is a substantive change, but I hope you’ll either (a) agree that it falls within editorial discretion, or (b) agree with the change! If not, let me know.