ExtensionHowTo

Has someone marked one of your bugs RESOLVED NEEDSINFO and suggested you should write an extension specification? Don't panic!

Are you interested in writing an extension specification but don't know where to start? Don't panic!

Extension specifications are what the HTML WG uses to review new features or modifications that are too large to be adequately captured in a single bug or to sit comfortably in a single email. The basic idea is that the proponent(s) for this new feature will write up a standalone document that can then be reviewed and improved easily on its own, based on discussions on the public-html mailing list and in the HTML WG's bug tracker.

What is the goal of an extension specification?

The primary goal of an extension specification (ES from now on) is to facilitate contributions from a larger community without requiring anyone to jump through the hoops involved in editing the monolithic source of the HTML specification which can prove a daunting exercise.

Once an ES is proposed to the HTML WG a period of review and discussion follows. There is no duration for this, it will end when it feels that the discussion has been sufficient to move on. At that point, multiple things can happen.

The ES might get dropped. We'd be lying to you if we told you that everything gets accepted, sometimes it might just not work out. We'd rather be upfront about that so that you're not surprised down the line if it happens to you. An ES is no guarantee of integration. Most importantly, see our discussion of use case throughout the rest of this document.

The ES may get published on its own. Releasing a standalone document with the group's imprimatur is typically used as a way of obtaining further feedback. This doesn't mean that the ES will always remain standalone (it may eventually get folded into the core specification) nor that it will necessarily succeed: it could be that the additional feedback is negative, or it might never gain traction with implementers.

That being said, some ESs will remain standalone documents that will proceed on their own towards Recommendation status without ever being integrated into the core HTML specification. It should be very clear that this is not at all a failure. Your goal in producing an ES should be to improve the Web Platform by getting implementers to support the great feature you have in mind. Which document it sits in at the end of the day really doesn't matter. The decision to fold an ES in or maintain it separately will largely be based on how strongly it interacts with the core specification (if it monkey-patches parts of it then it probably shouldn't stay separate), on implementation schedules, and on editorial convenience.

The ES may get folded into the core HTML 5.1 specification. If it proves popular and the group wants it, and we generally agree that it would be better off integrated rather than in a document of its own, then it will be integrated into the core specification. Note that if it is broadly implemented and enjoys wide support fast enough, then it can also be folded into the HTML 5.0 specification. This, however, is likely to be exceptional.

What should be in my extension specification?

There are several forms that an ES may take. Please don't jump to conclusions as to the form you should use before reading this section in its entirety.

A use cases document. Your ES may very well only contain use cases and possibly some code examples showing the sort of code you would like to see becoming possible if your use cases are addressed.

Do not dismiss this option. First, you will have to do it anyway since the alternatives require use cases anyway. Second, if you have great use cases and a poor solution, you run the risk of your proposal being disliked because of the latter. A great example of this is the Use Cases and Requirements for Standardizing Responsive Images.

Before you move on, please take the time to look at the following picture:

A standalone extension. If you do decide to write up a technical solution in addition to the use cases, then we recommend you do so as a standalone document. This does not in any way constrain whether it may be folded into the core specification later or not, it is simply a description of the way in which you edit your specification.

A modification of the main specification. If you are feeling particularly brave (or foolish) you may fork the primary specification and make the edits you plan on making in a dedicated branch of your fork. This is not recommended. You can, really, if you want to. But make sure that you have overwhelmingly strong reasons to do so before you do so. This will make it harder to write, harder to maintain, and harder to review. For this, you will want to have the html-tools repository checked out too.

How do I write the actual specification?

If you don't already have an idea of how a specification is written, it is probably better to stick to use cases since getting the solution parts wrong will likely prove detrimental to your case (even if your use cases are great they risk being tainted by association). For that we recommend looking at the example cited above.

For the rest, do not worry about writing things in such a way that they integrate well with the HTML specification. If your ES gets integrated, someone from the editorial team will go through it to clean it up anyway. If it does not get integrated, then trying to conform will have wasted your time. Focus on awesome use cases and (if you want to) a great technical solution. Don't go off shaving editorial yaks.

Have you thought about testing?

Testing matters. It really does. Keep in mind that your goal is to convince implementers that they want to support this, and the group that it is a good idea. Tests will help the former implement, and the latter review (since code speaks loud). The process to produce a test suite is as follows:

Create a new directory at the root of the test suite, the name of which should be ext-$yourSpecShortName. If your specification is a clear addition or change to a section in the HTML specification, then reproduce the directory structure matching that section under the new directory. If not (or if you can't figure that out) then just lay it out in whichever way feels logical.

How do I propose an extension specification to the group?

First, make sure that you are properly covered by the Royalty Free policy. The simplest way to do so is to join the HTML WG. If your company is not a W3C member, you're welcome to join as an invited expert.

Second, have you read everything we wrote about use cases? Are you sure? Are you confident you've done a good job there? Have you properly understood how important this is? Okay, read on then.

Just make sure your ES is online somewhere (using GitHub's gh-pages is a popular choice) and email the group with a pointer to your specification, not forgetting to place the use cases well up front (you remember those, right?). The appropriate mailing list for this is public-html.

What tool should I use for specification writing?

Use whatever you are most comfortable with. The two most popular tools for this are Anolis and ReSpec. Since the author of this page wrote ReSpec, he declines to go into a discussion of which is best.

Note that whichever tool you chose, we strongly recommend that you use the "Unofficial Draft" style (example). With ReSpec, this is done by setting the specStatus configuration variable to "unofficial". With Anolis the simplest is probably to find an existing such document and copy from it.