From 78f5b205b289c1dccdf920592461e198181f82ab Mon Sep 17 00:00:00 2001 From: Eli Schwartz Date: Wed, 28 Dec 2022 21:05:55 -0500 Subject: [PATCH 1/3] clarify the syntax of the version line 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. https://github.com/TestAnything/Specification/issues/41 --- tap-version-14-specification.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/tap-version-14-specification.md b/tap-version-14-specification.md index 5f35a6d..8a54cc0 100644 --- a/tap-version-14-specification.md +++ b/tap-version-14-specification.md @@ -156,23 +156,28 @@ backwards compatibility. ### Version -To indicate that this is TAP14 the first line _must_ be +The TAP version of a TAP stream is indicated on the first line. ```tap TAP version 14 ``` -Harnesses _may_ interpret ostensibly -[TAP13](https://testanything.org/tap-version-13-specification.html) streams -as TAP14, as this specification is compatible with observed behavior of -existing TAP13 consumers and producers. That is, they _may_ treat this as -a valid Version line while parsing TAP14: +If there is no version line on the first line, the TAP version shall be 12. + +#### Backwards compatibility of TAP versions + +This specification is compatible with observed behavior of existing +[TAP13](https://testanything.org/tap-version-13-specification.html) consumers +and producers. + +Harnesses _may_ interpret ostensibly TAP13 streams as TAP14. That is, they +_may_ treat this as a valid Version line while parsing TAP14: ```tap TAP version 13 ``` -Harnesses _may_ treat any TAP stream lacking a version as a failed test. +Harnesses _may_ treat any ostensibly TAP12 stream as a failed test. ### Plan From f7de8df0dd5e54ef85aec189cf42cab1f09ddc95 Mon Sep 17 00:00:00 2001 From: Eli Schwartz Date: Wed, 28 Dec 2022 21:18:52 -0500 Subject: [PATCH 2/3] remove the difference between TAP12 and TAP13 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. --- tap-version-14-specification.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/tap-version-14-specification.md b/tap-version-14-specification.md index 8a54cc0..8eb7d14 100644 --- a/tap-version-14-specification.md +++ b/tap-version-14-specification.md @@ -167,17 +167,20 @@ If there is no version line on the first line, the TAP version shall be 12. #### Backwards compatibility of TAP versions This specification is compatible with observed behavior of existing +[TAP12](https://testanything.org/tap-specification.html) and [TAP13](https://testanything.org/tap-version-13-specification.html) consumers and producers. -Harnesses _may_ interpret ostensibly TAP13 streams as TAP14. That is, they -_may_ treat this as a valid Version line while parsing TAP14: +Harnesses _may_ interpret ostensibly older TAP streams as TAP14. That is, they +_may_ treat this as a valid and supported Version line while parsing TAP14: ```tap TAP version 13 ``` -Harnesses _may_ treat any ostensibly TAP12 stream as a failed test. +and likewise treat a missing Version line as implicitly TAP14. + +Harnesses _may_ instead treat any ostensibly older TAP stream as a failed test. ### Plan From 4837988cdddd3c692c0517579965c1d231839dc3 Mon Sep 17 00:00:00 2001 From: Eli Schwartz Date: Wed, 28 Dec 2022 23:02:26 -0500 Subject: [PATCH 3/3] upgrade harness support of older version streams from "may" to "should" 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-version-14-specification.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tap-version-14-specification.md b/tap-version-14-specification.md index 8eb7d14..5a5832b 100644 --- a/tap-version-14-specification.md +++ b/tap-version-14-specification.md @@ -171,8 +171,8 @@ This specification is compatible with observed behavior of existing [TAP13](https://testanything.org/tap-version-13-specification.html) consumers and producers. -Harnesses _may_ interpret ostensibly older TAP streams as TAP14. That is, they -_may_ treat this as a valid and supported Version line while parsing TAP14: +Harnesses _should_ interpret ostensibly older TAP streams as TAP14. That is, they +_should_ treat this as a valid and supported Version line while parsing TAP14: ```tap TAP version 13