Thoughts on starting the SVG 2.0 spec

Hi WG,

I've been spending a bunch of time thinking through how we should start the SVG
2.0 spec, and how the tools, infrastructure and processes to support it should
work. This email would be way too long if I tried to cover everything, but
here's a summary of some of some of what I'm personally thinking:

Directory structure:

Talking with Cameron I think we should get rid of the 'master' and 'publish'
directories and just have a 'spec' directory. Any files that need to be
processed by the build script to produce a page can be marked with ".src." in
their name (e.g. index.src.html).

This has several advantages. It Eliminates duplication of files that are in both
master and publish, such as the relatively large 'images' directory. This in
turn makes the repository smaller, makes diffs smaller, makes the build script
run faster (no copying), and eliminates the need for rsync to be installed to
build the spec.

Tools:

I want to vastly simplify the setup required to be able to work on the spec.
Amongst other things I'm working on a new build script that will eliminate the
need for cygwin.

Starting point:

I think that once 1.1 2nd edition is done, we should start with the files from
2nd Ed, and commit those *initially unmodified in any way* to the Mercurial
repository. (And in the same directory structure as 1.1 2nd Ed!! -- we can 'hg
move' them into any new directory structure as the next step.) There are a few
reasons for wanting to start with the 2nd Ed files.

 * I want to be able to see and track how the spec that browsers have
   implemented/are implementing changes, and what's different in 2.0.
   Specifically I want to be able to see *diffs* for the changes as
   people make them, starting right back from the 2nd Ed text. Starting
   with a blank document for 2.0 and moving sections across from 1.1
   to 2.0 would not provide anything like the same level of
   transparency/insight.

 * Cameron tells me that on the last telcon you discussed having two docs;
   a 2.0 doc, and a 1.1 2nd Ed doc that gets modified in some way, with
   links between the two showing what came from where and what changed.
   This seems like a lot of work to add/maintain the links, will be
   error prone, will clutter the source, and it will often be unclear
   what to do when text is broken up or text is combined from various
   places. Starting with the 2nd Ed files would make this manual
   work unnecessary and eliminate its problems.

Review:

There seems to be two types of review under discussion, and I want to clearly
distinguish between the two:

 1) review of a section of text originating from 1.1 2nd Ed as being
    accepted for 2.0

 2) review of individual commits

For #1, I suggest that in a 2.0 clone of the 2nd Ed files we change the style
sheet for the page to turn the entire background of the document red, and as
work progresses and we're satisfied with sections (for some definition of
"satisfied") we add a class to those sections to turn their background white (or
green, or whatever).

For #2, I don't think we should be putting anything in the markup to say "this
commit needs review". If anyone disagrees, I think we really need to talk. :)

For changes that have been reviewed by another WG member /before/ the commit is
made, I think we should put "r=<reviewer's name>" in the commit message. This
means that a change's reviewer is tracked by mercurial in addition to the
author, and we can easily distinguish between reviewed and unreviewed changes.

To support lightweight review-before-commit I think we can have a little
mercurial extension so you can type:

  $ hg pb-diff
  http://example.com/2342

pb-diff would take your changes, upload them to a pastebin type site, and print
the URL of the page where they can be found which you can message to your
reviewer. The site would display a side-by-side diff of the changes, you'd be
able to get full document context by having the site query a clone of the
repository, and even display the resulting document with the changes applied.

Regarding changes made without review before the commit, I think we should start
out by allowing people to do that, using their discretion about whether or not
other members of the WG would like to review the change before it's committed.

-Jonathan

Received on Thursday, 24 March 2011 04:20:21 UTC