ReSpec: Evolution

Hi all,

if you use ReSpec, or participate in a group that uses ReSpec and think that your editors might not be on this list, please take the time to read this email as it contains important information on the topic.

Before I delve in: if there is any part of this email that makes you worried, panicked, angry, fills you with angst, or generally spoils your mood then please jump straight to the "WHAT THIS MEANS FOR YOU" section. All is fine and dandy.

There has recently been a flurry of questions in various parts about ReSpec, mostly to do with what the status of v2 is, how to load it, what to patch.

I started work on v2 not because it was fun to make a new version but because the v1 code was grown all the way up from a 50 lines script into a tentacular monster. I recently had to fix a bug in the v1 WebIDL code and some parts of my brain fried. Some of the configuration options interact in ways that I don't understand and dare not touch. It is also constrained to a single type of document (W3C specifications) when many people are asking for the same stuff for different documents; and even within the restricted scope of W3C documents there are variants that were hard to accommodate without (even more of) a combinatorial explosion in configuration options.

I didn't feel like I could fix any of that without taking all the pieces apart on the floor and finding a new, better way of putting them all together.

That's what happened with v2. I figured out how to make this maintainable and flexible. But the problem was that this was a rather large undertaking to carry out within bits and pieces of spare time. The v2 that's available today is very roughly usable (some people do) but there are still a thousand paper cuts that need fixing before it can replace v1. This would all be fine were it not that in the meantime, people still need fixes and new features in what they use. So over time, v1 has kept moving and all of those changes need to be integrated into v2, which takes time since it's a different code base. This has made it impossible for me to reach the point where v2 could take over.

Not happy with any of this, I decided to take both versions and slam them together to see what would happen. It turns out that with the experience from v2 I now know how I can evolve v1 towards a refactored version. And so that's what I did.

For those who are interested in the details, v1 was mostly one big ugly script that hand-loaded a few dependencies and ran on its own indirection layer atop the DOM; v2 on its side is a set of independent modules that can be loaded based on a profile definition using RequireJS, and it uses jQuery (it also has a build tool that can bundle and compress all of that into a single file, which helps a lot for various issues). What I've done with v3 is take the basic framework defined for v2 and created one humongous ugly independent module called "w3c/legacy" that works just like any of the other small elegant modules but just happens to contain all the code in v1. As small modules in the v2 style are progressively added to v3, the corresponding code can be deleted from the legacy module — hopefully until it's gone entirely. This provides us with an evolutionary strategy based on a single unified code base.

It even has a test suite. There isn't much there (none of the legacy code is tested) but each module to make the transition will come with tests. Since there is no pressure to move fast, this can actually happen for real.

But enough talking. What you need to go to start using v3 is simply replace whatever current location you are loading ReSpec from with either of the below:

    http://darobin.github.com/respec/builds/respec-w3c-common.js
    http://darobin.github.com/respec/builds/respec-w3c-common-3.0.0.js

The first is the latest build (and will always be that), the second is a version snapshot that will never change. Which one you use is up to you. The latest version ought to remain compatible, but there's always the risk that bugs could happen without you knowing since it changes beneath your feet. The snapshot version is trustworthy but you'll have to remember to point to a newer version once in a while if you want to benefit from fixes (notably the code size reduction that's coming up).

You are invited to test this transition *NOW*. If there are issues, you can revert to pointing to whichever previous version you prefer, but as of today neither v1 nor v2 will be maintained, not even for bug fixes (unless some massive unforeseen problem prevents the v3 transition).


WHAT THIS MEANS FOR YOU

• If you use ReSpec (either v1 or v2)

Please try updating your document to include http://darobin.github.com/respec/builds/respec-w3c-common.js (or http://darobin.github.com/respec/builds/respec-w3c-common-3.0.0.js) and look at the result to see if everything looks fine. If it looks bad, email me with a pointer to your document. If it looks good, email me with a pointer to your document (it helps to know how many people have tested something).

• If you contribute to the ReSpec bibliography

For the time being, you can keep updating the CVS version and I will move over the changes by hand (which is manageable) until the biblio system is updated to be more easily patched. If you want, you can head to https://github.com/darobin/respec/blob/gh-pages/bibref/biblio.js and make your change directly by hitting "Edit this file".

• If you contribute code to ReSpec v1

Your code has been absorbed into the new version (unless your patch happened in the past few days in which case I am about to integrate it). Please don't patch that version anymore — I won't be keeping up (if you are right now working on some changes that you haven't committed, tell me, we'll sort it out). You can now head for https://github.com/darobin/respec/, fork that project, and submit changes as pull requests with the usual GitHub flow.

• If you contribute code to ReSpec v2

Your code is in the process of being absorbed into the new version. It may take a little while to move everything, but it will happen so don't worry — your contributions are not lost. Please don't patch that version anymore though, see previous bullet for contribution details under the new setup.


QUESTIONS THAT COULD BE FREQUENTLY ASKED

• Won't this evolutionary transition bloat the code and make things slower?

With the first release of v3 you get a bundle weighing in at 497K over one single request (which includes all dependencies, including CSS). Yes, that's way too much. But with v1 you were loading 469K over eleven requests so all things considered I believe that overall the new version is already a little bit faster. As I progressively transition the v2 code over, I believe that I can shave off ~300K from that. If you have suggestions on how to served gzipped content from GitHub I'll take them (v3 is 123K gzipped so it's worth it). Or if there's a simple release script I can use to push the releases to another site where this would be served gzipped, I'm certainly open to it.

• Are there any incompatibilities?

In theory, very few to none. If you are using v1 in a regular fashion, nothing should change beyond the URI from which you load. If you are using v1 with dirty tricks (I've seen you do it) such as monkey patching the code or trying to inject changes using timeouts or by spying on what's going to console.log() then I make no promises — some of it probably works now but more and more of it will break. If you are using v2 then it's possible that some small features have not been properly ported yet. If you bump into that, ping me.

Note that the extraCSS configuration parameter has been removed. I couldn't find anyone using that for anything other than loading the ReSpec core CSS which is now always loaded for you.

• Where do I report bugs?

https://github.com/darobin/respec/issues. The W3C team had very kindly set up a Trac instance for this but no one apart from me ever used it.

• Where is this discussed?

Still here, on spec-prod.

• Where do I find the documentation?

The v1 documentation still applies (though it can be improved), it is now at http://darobin.github.com/respec/docs/. I will be injecting the v2 documentation into that as well.

-- 
Robin Berjon - http://berjon.com/ - @robinberjon

Received on Thursday, 24 May 2012 13:26:58 UTC