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.
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 email@example.com (archives, subscribe).
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
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
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.
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.
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 ...
http://localhost:8000/tests/SpecRunner.html with any recent
browser will launch the test suite.
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
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).
git up; git checkout develop).
grep version package.json) and increment it in your head (or, you know, on a piece of paper).
git flow release start v3.1.61if you are currently on 3.1.60.
node tools/build-w3c-common.js). This should respond "OK!" (if not, fix the issue).
git add builds/respec-w3c-common-3.1.61.js).
git commit -am v3.1.61).
git flow release finish v3.1.61). This should prompt you to enter a message for the tag.
That should be all. Normally, within a few minutes the W3C server will have picked up, gzipped, and published the latest and greatest version.
In this chapter we look at how a plugin is structured and how it ticks, how to handle its
(including for asynchronous processing), what is available from the
plugin, and some general information about how the templating language is used.
XXX to be written
XXX to be written