Reword to clarify streams lacking a version number #43
Conversation
A TAP14 stream *must* have a version line saying "TAP version 14" in order to be TAP14. It's confusing to say that a TAP stream *must* have that line when describing the syntax, though. Reword this to make it clear that a version line must be that line, and the semantics of *missing* that line is that this is not a TAP14 stream -- not that it's a TAP14 stream with an error in it. Of course, a harness that interprets TAP14, when given not-TAP14, can reasonably decide to report an error. Add the note about TAP13 compatibility into a new section on backwards compatibility, making it clear that both the "may" handle TAP13 and the "may" report an error for missing version, are... all about handling backwards compatibility with That Which Is Not TAP14. Ref. TestAnything#41
In both cases, TAP14 is believed to be compatible with observed behaviors, and it's plausible for a TAP14 harness to support this automatically. Don't differentiate based on whether the stream is from a version where the Version line was formalized.
If a harness does not want to do so, they do not have to -- and the spec is not changing that. But it's a good idea to do so, because TAP tries hard to be compatible for a reason, and that reason implies that it's safe and good to support it. So, lean harder on the notion that it's a recommended move to do so.
|
|
||
| ```tap | ||
| TAP version 13 | ||
| ``` | ||
|
|
||
| Harnesses _may_ treat any TAP stream lacking a version as a failed test. | ||
| and likewise treat a missing Version line as implicitly TAP14. |
There was a problem hiding this comment.
I thought missing version line would be TAP12?
|
I think this is too complex and, at the same time, doesn't clarify whether:
|
|
Suggested language (from #41, added forward-looking language as well). I think this leaves us all in the clear as far as our current parsing behavior, doesn't impose any additional burdens on new entrants or significant changes to the semantics, and still leaves the door open for harness implementations that want to be a bit more strict about the versions they support. To indicate that test output is TAP13 or newer the first line SHOULD be If the first line of the input is not a version line, harnesses MUST behave as if a Harnesses MAY require a minimal version and reject any input that specifies an older version. Harnesses MUST NOT treat a TAP stream lacking a version line as a failed test, unless they do not support TAP version 12 input. Harnesses MAY interpret ostensibly TAP13 or TAP12 streams (including those lacking an explicit version) as TAP14, as this specification is compatible with observed behavior of existing TAP13 consumers and producers. For example, a Harness MAY parse child tests that appear in an unversioned TAP stream. Harnesses MAY emit a warning or failure when encountering a version declaration greater than 14. However, as ongoing backward compatibility is expected in future versions of the TAP specification, Harnesses SHOULD attempt to parse a higher-versioned stream as faithfully as possible. |
See #41 for discussion. Here's my attempt at solving the wording, hopefully even in a manner that technically means the same thing.