test framework + spec #10

marcoscaceres · 2021-07-05T07:18:17Z

@dontcallmedom, @tidoust, as we discussed last week. Here is the initial version + testing framework.

For testing, I'm just using Karma + Jasmine.

I'm generating the BS specs via curl and doing a local respec build.

My idea is just to add various definitions to src files, and make sure ReSpec and Bikeshed do the same thing (already found a bug :)) .

dontcallmedom · 2021-07-05T07:38:51Z

could the generated files be built on demand rather than committed to the repo?

README.md

dontcallmedom · 2021-07-05T07:42:44Z

README.md

+A a dfn-definition MUST have the following attributes:
+
+- `id` attribute, unique to the document.
+- `data-dfn-type`, with one of type values.


I think we should recognize it as optional for <dfn> elements (that's how reffy handles it, and I suspect shepherd too)

I was going by 4 of the contract:

data-dfn-type MUST be provided, and set one of the accepted values.

I don't have a strong preference tho. ReSpec treats them as optional, but I sent a PR to ReSpec to always include them: https://github.com/w3c/respec/pull/3667.

It is a reasonable default especially if we consider that people could possibly create spec markup manually (no one really does that, but the intro suggests that is a possibility): <dfn data-dfn-type="dfn"> looks very redundant when compared to <dfn>.

+1 on it being super-redundant. And there are manually maintained specs, e.g. WebGL 1 & 2.

Shepherd does some inference if it's missing, for legacy specs. I don't think we want to specify those inference rules; they're heuristic and kinda complex and specific to the styles that happen to be used by the legacy specs in question. (They're based on examining the text, the ID, and I think there's some matching to WebIDL in the document as well.)

So I def prefer continuing to require it.

dontcallmedom · 2021-07-05T07:43:48Z

README.md

+
+### Exporting definitions (`data-export`)
+
+Exported definitions MUST include a `data-export` attribute. The attribute's value can be missing or the empty string.


this should recognize the intersection with dfn-type that makes some definitions exported without a data-export attribute

Hmm... that seems to be a Bikeshed-ism that relies on tree structure (ReSpec doesn't support dfn-type on container elements).

I think the tooling should be adding data-export in those situations.

I agree with @marcoscaceres and think that's already the case in practice, dfn-type being just a tooling artefact to produce data-dfn-type attributes in the resulting spec. Typically, Reffy does not know anything about dfn-type and only looks for data-dfn-type attributes. I don't think that the contract document should mention dfn-type at all.

let me clarify what I meant - I wasn't arguing about dfn-type vs data-dfn-type (I was just foolishly saving typing 5 characters). I was saying some value of data-dfn-type are exported by default, some are not exported by default, and this should be reflected in the definition of exported definitions.

Got it, thanks for clarifying @dontcallmedom.

So, let's reframe this because I think this is really important. Tooling can add data-dfn-type, but (!!!) they must add data-export="" for a definition to actually be classified as exported.

Put differently, if a definition is "exported" must not be implied by the presence of data-dfn-type. Only the explicit presence of data-export="" makes something exported.

Agree?

I know that adds redundancy, but it also gets rid of any ambiguity.

Ah, I understand what you're suggesting now: the fact that some data-dfn-type are automatically exported is not a rule of the type, but a default that authoring tools apply when generating the output.

This has the merits of disentangling the two axes; I'm a bit worried of the impact on making this work for non-bikeshed / non-respec maintained documents, but we can revisit this when this becomes a more realistic question to consider :)

Yeah, putting the dfn-* attributes on ancestors is a Bikeshed-ism; it gets turned into data-dfn-* attributes directly on the <dfn> by generation time.

A mention of this is very likely reasonable, in case people run into this document when looking for how to format their dfns, but it's definitely not part of the contract itself.

Put differently, if a definition is "exported" must not be implied by the presence of data-dfn-type. Only the explicit presence of data-export="" makes something exported.

I dunno if I agree with this. I think in the absence of an explicit export/noexport, it's reasonable to apply the same defaulting that Bikeshed does. (But we should still require tooling to add it explicitly.)

dontcallmedom · 2021-07-05T07:47:06Z

README.md

+No other HTML elements are recognized as defining a term.
+
+#### dfn
+A a dfn-definition MUST have the following attributes:


I wonder if rather than MUST (which ideally should apply to agent, not to models) if we should declare what a conforming definition is (a dfn element with an id attribute, or or h* element with an id and a dfn-type attribute).

Yeah, agree. I'll change them to statements of fact.

dontcallmedom · 2021-07-05T07:47:51Z

README.md

+
+A `data-noexport` attribute means a definition is intended for private use by a specification.
+
+Other specifications MUST NOT reference or link to definitions marked as `data-noexport`.


specs aren't part of the conformance landscape :)

CSS has put requirements on spec authors before. ^_^ Since this doc is explicitly about writing specs, I think having conformance requirements is just fine, and in fact exactly correct.

(That said, this should be downgraded to a SHOULD NOT. It can be appropriate to refer to an unexported term sometimes, but it needs a good reason.)

dontcallmedom · 2021-07-05T07:50:14Z

README.md

+### Types of definitions (`data-dfn-type`)
+
+Every exported definition MUST have a `data-dfn-type`.
+


it would be good to insert a summary table that for each type indiciates:

whether it's exported by default or not

whether it's case sensitive or not

whether data-dfn-for is required for the said type

I definitely agree with this. But for each type, there are specific requirements that I need to work out... like I don't know what data-dfn-for for "argument" is right now... I guess it would be "interface/method", but need to check.

Yes, that's correct. The for is just whatever construct is namespacing the value; arguments clearly are unique only up to their method (in fact, to within one overload of a method).

spec/definition-export-spec.js

README.md

Co-authored-by: François Daoust <[email protected]>

marcoscaceres · 2021-08-04T06:22:01Z

Alright... this is probably enough for us to start to incrementally build on.

README.md

Co-authored-by: Tab Atkins Jr. <[email protected]>

spec/definition-export-spec.js

spec/helpers/test-utils.js

jyasskin · 2023-02-01T00:46:47Z

How would you feel about merging this, and then iterating on the details?

tidoust · 2023-02-01T07:17:28Z

That would be good. Do we still have a maintainer for this, though? @marcoscaceres, are you still able to lead the effort? If not, @jyasskin, would you be able to take that on?

jyasskin · 2023-02-02T18:58:10Z

I think @tabatkins and I can take care of this, and probably @sidvishnoi can keep track of the Respec side even if @marcoscaceres turns out not to have time. I'm not 100% confident of maintaining a unified test suite, but the documentation work is just moving the work Tab was doing in the Bikeshed docs anyway.

tidoust · 2023-03-09T09:41:27Z

Not sure if you're waiting on further feedback, @jyasskin. That sounds like a good plan to me, and the lack of responses suggests that no one else is willing to step up ;)

jyasskin · 2023-03-09T17:09:33Z

I'd lost track of the fact that I can merge it now. Doing so.

marcoscaceres · 2023-03-10T00:21:28Z

Sorry for missing this... yeah, I won't have time :(

test framework + spec

6b6633f

marcoscaceres requested a review from dontcallmedom July 5, 2021 07:18

dontcallmedom reviewed Jul 5, 2021

View reviewed changes

README.md Outdated Show resolved Hide resolved

dontcallmedom reviewed Jul 5, 2021

View reviewed changes

README.md Outdated Show resolved Hide resolved

dontcallmedom reviewed Jul 5, 2021

View reviewed changes

spec/definition-export-spec.js Show resolved Hide resolved

tidoust reviewed Jul 5, 2021

View reviewed changes

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

README.md Show resolved Hide resolved

README.md Show resolved Hide resolved

marcoscaceres and others added 8 commits July 7, 2021 15:43

Apply suggestions from code review

bfdd1f7

Co-authored-by: François Daoust <[email protected]>

format doc

1d3e148

Fixup README.md

8d21c3c

Remove generated files

218a1ba

Cleanup tests

b428bd5

ignore out/ folder's html files

82248ae

rename source files

38b8339

More cleanup

162adf3

marcoscaceres marked this pull request as ready for review August 4, 2021 06:22

Remove task sources and premissions

625d9f6

marcoscaceres mentioned this pull request Aug 13, 2021

Move definition contrat to Spec Editors Community Group speced/bikeshed#2088

Open

tabatkins requested changes Aug 25, 2021

View reviewed changes

Apply suggestions from code review

a1626ce

Co-authored-by: Tab Atkins Jr. <[email protected]>

marcoscaceres commented Aug 27, 2021

View reviewed changes

spec/definition-export-spec.js Outdated Show resolved Hide resolved

Update spec/definition-export-spec.js

2f42897

marcoscaceres commented Aug 27, 2021

View reviewed changes

spec/helpers/test-utils.js Outdated Show resolved Hide resolved

Update spec/helpers/test-utils.js

ffee7fd

dontcallmedom mentioned this pull request Feb 1, 2023

add "abstract-op" to the spec #17

Open

jyasskin merged commit 1cedbe1 into main Mar 9, 2023

jyasskin deleted the base_stuff branch March 9, 2023 17:10

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

test framework + spec #10

test framework + spec #10

marcoscaceres commented Jul 5, 2021 •

edited

Loading

dontcallmedom commented Jul 5, 2021

dontcallmedom Jul 5, 2021

marcoscaceres Jul 6, 2021

marcoscaceres Jul 6, 2021

tidoust Jul 6, 2021

dontcallmedom Jul 6, 2021

tabatkins Aug 20, 2021

dontcallmedom Jul 5, 2021

marcoscaceres Jul 6, 2021

tidoust Jul 6, 2021

dontcallmedom Jul 6, 2021

marcoscaceres Aug 4, 2021

dontcallmedom Aug 4, 2021

tabatkins Aug 20, 2021

dontcallmedom Jul 5, 2021

marcoscaceres Jul 6, 2021

dontcallmedom Jul 5, 2021

tabatkins Aug 20, 2021

tabatkins Aug 20, 2021

dontcallmedom Jul 5, 2021

marcoscaceres Aug 5, 2021

tabatkins Aug 20, 2021

marcoscaceres commented Aug 4, 2021

jyasskin commented Feb 1, 2023

tidoust commented Feb 1, 2023

jyasskin commented Feb 2, 2023

tidoust commented Mar 9, 2023

jyasskin commented Mar 9, 2023

marcoscaceres commented Mar 10, 2023


		### Exporting definitions (`data-export`)

		Exported definitions MUST include a `data-export` attribute. The attribute's value can be missing or the empty string.


		A `data-noexport` attribute means a definition is intended for private use by a specification.

		Other specifications MUST NOT reference or link to definitions marked as `data-noexport`.

		### Types of definitions (`data-dfn-type`)

		Every exported definition MUST have a `data-dfn-type`.

test framework + spec #10

test framework + spec #10

Conversation

marcoscaceres commented Jul 5, 2021 • edited Loading

dontcallmedom commented Jul 5, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcoscaceres commented Aug 4, 2021

jyasskin commented Feb 1, 2023

tidoust commented Feb 1, 2023

jyasskin commented Feb 2, 2023

tidoust commented Mar 9, 2023

jyasskin commented Mar 9, 2023

marcoscaceres commented Mar 10, 2023

marcoscaceres commented Jul 5, 2021 •

edited

Loading