ReSpec v3 is composed of many small and (mostly) simple plugins that perform one task (sometimes two) and do that well. You can think of it as a set of small Unix command-line utilities through which content is piped (except that in some cases they can operate asynchronously). Removing or adding plugins is trivial, and defining new ones is very simple. The only difficulty is that there are quite a few files and that you need to know where to look for what. This guide will explain the basic layout and architecture, introduce you to writing plugins, and tell you how to create your own ReSpec profile so as to be able to edit your own document types.

Project Basics

The source for ReSpec can be found at https://github.com/w3c/respec/. That is also where issues and pull requests are made. More general discussion about ReSpec development takes place on spec-prod@w3.org (archives, subscribe).

How to contribute

ReSpec has a healthy and lively contributor base and we are happy for you to join the gang. You certainly are welcome to submit whatever change you wish to. Note however that if it is a complex feature or add substantial syntax to the language please try to coordinate with others first to avoid working long on something that will then be rejected).

If you're familiar with GitHub then contributing is simple: just fork and make pull requests. Please just be careful to note that the primary branch is gh-pages and not master (this ensures that the result gets published on the Web). More importantly, please note that the development branch is develop. If you are making patches and pull requests, please base them off this branch.

If you're not familiar with GitHub, you need to follow the following steps:

If you have an existing fork, please make sure to synchronise it with the upstream repository before you make a pull request.

Running the test suite

ReSpec runs a number of high level, end-to-end tests using Jasmine. These tests are run by Travis, a hosted continuous integration solution, on each pull requests.

There are two options to run these tests locally: in a browser or using PhantomJS.

In a browser

The tests need to be served using a proper Web server, from the root of the repository to function properly. Any server will do. For instance, if you're one of those people who like Python, this will work:

            $ cd /path/to/repo/
            $ python -m SimpleHTTPServer
            Serving HTTP on 0.0.0.0 port 8000 ...
          

Navigating to http://localhost:8000/tests/SpecRunner.html with any recent browser will launch the test suite.

In PhantomJS

PhantomJS is a headless, WebKit-based browser. It allows running the tests directly from the command line.

In order to run the test from the command line, you need to install Node, npm and PhantomJS. Note that npm comes bundled with recent versions of Node.

Once these dependencies are installed, running the test suite should be as simple as:

$ npm test

Building ReSpec

Normally, producing a build of ReSpec should not be necessary for anyone, unless you're on the core development team (and even then, mostly Robin does this). Certainly don't bother with this if you are providing pull requests. But on occasion it can be useful in order to debug a painful corner-case, so here are the instructions. This not being something normally exposed to the world, they are a bit convoluted (and may be simplified).

  1. Make sure you are up to date and on the develop branch (git up; git checkout develop).
  2. You will need to have git flow.
  3. Get the current version (grep version package.json) and increment it in your head (or, you know, on a piece of paper).
  4. Start a new release in git flow using v$NEW_VERSION as the name, e.g. git flow release start v3.1.61 if you are currently on 3.1.60.
  5. Update the version in package.json.
  6. Run the build script (node tools/build-w3c-common.js). This should respond "OK!" (if not, fix the issue).
  7. Add the new build (git add builds/respec-w3c-common-3.1.61.js).
  8. Commit your changes (git commit -am v3.1.61).
  9. Finish the release git flow (git flow release finish v3.1.61). This should prompt you to enter a message for the tag.
  10. Push everything back to the server (make sure you are pushing at least the develop and gh-pages branches).

That should be all. Normally, within a few minutes the W3C server will have picked up, gzipped, and published the latest and greatest version.

Anatomy of a Plugin

In this chapter we look at how a plugin is structured and how it ticks, how to handle its dependencies including to non-Javascript resources, how context and continuations work (including for asynchronous processing), what is available from the utils plugin, and some general information about how the templating language is used.

XXX to be written

Defining Your Own Profile

Creating your own profile is trivial: it can often consist of a very simple Javascript file, a little bit of CSS, and perhaps a straightforward HTML template. This chapter covers all of this, plus important information about plugin ordering and how to build and release your profile.

XXX to be written