I would like to propose converting the specification to use the Bikeshed spec pre-processor.

Bikeshed produces specification documents that are equivalent to ReSpec that we currently use, but instead of transforming the source document at load-time (through content JavaScript) it pre-processes the source document into a complete, finished HTML document as a build step.

As many of you know I have a distaste for hard-to-explain build steps and a love for the mutable what-you-see-is-what-you-get web, so I am not the natural proponent of this kind of change. But I have come to the realisation that some of the forthcoming changes we need to make for the bi-directional protocol would be easier to tackle if we can run tasks as build steps.

One of the takeaways from TPAC 2019 in Nagoya, Japan was that we need to make WebDriver more discoverable for web authors, client maintainers, and browser developers. There are various things we could do, but I believe the most effective is to make the specification machine-readable.

With the proliferation of APIs that we expect to see with the bi-directional work, we will be moving from a human-managable set of endpoints to a reality where computer automation would be necessary to assist with ingesting changes. Having formalised schema definitions for the different interfaces, methods, and types will enable wider and earlier adoption of new APIs because the specification is offering a useful service to implementors.

Now to the point of this issue and why it means we need a pre-processor:

I picture that the schemas should be defined in separate files/artifacts, rather than be inlined in the source spec document. This would allow generation of API documentation (using Swagger or something equivalent) to serve as client maintainer documentation, MDN browser compat data and API documentation, and—most importantly!—generation of source files ready for use in browser implementations (for example into C++ or Rust) for schema validation, or local-end clients (Go/C#/Java).

With schema definitions as separate artifacts, ingesting them into the document would require a build step. We could hack together the inlining of interfaces for ReSpec with m4(1) or sed(1), but if there’s already a necessity to add a build step it would seem more obvious to adopt a spec authoring tool that already supports inclusion of files.

Here are some arbitrary examples of Bikeshed-backed specs from W3C, WHATWG, and non-affiliated:

• Encoding
• HTML
• Subresource Integrity
• URL
• WTF-8

Pros:

• Syntax is not too different from ReSpec
  • … and Bikeshed arguably has better documentation than ReSpec
• Allows interface definitions to live separately from the spec, enabling their use for other purposes:
  • MDN browser compat data
  • MDN API listings
  • API documentation generation (Swagger or similar)
  • Source code generation for browsers (C++/Rust) and clients (Go/C#/Java)
• Correctness checks can be done when PRs are created because pre-processor validates source document for parsing
• Loading https://w3c.github.io/webdriver/ should be a lot quicker
  • Compare with https://encoding.spec.whatwg.org/
  • We should experience less “juttering” because document has been pre-processed
• Spec can be viewed locally without internet connection
  • With ReSpec we rely on a bunch of remote resources from www.w3.org
• We won’t be hit by upstream ReSpec bugs
  • We rely on ReSpec from a remote server, meaning upstream bugs hit us immediately and retroactively affects already published documents

Cons:

• Requires build step to try out changes locally (view in browser)
  • Installation of Bikeshed dependency shouldn’t be necessary with internet access because we can have remote HTML generation
• Cannot make real-time changes (e.g. with DevTools) and see the transformed result immediately
• The conversion itself is a bit of busy-work, as we could hack the inlining of interfaces with ReSpec

Overall I don’t think the change should impact our workflow too much.