Re: Thoughts on starting the SVG 2.0 spec

Jonathan Watt:
> 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.

After discussing this with Jonathan, I agree with him and would prefer
the start-with-SVG-1.1-text approach, for the above reasons.  We have a
choice between two approaches to track how 1.1 text is modified as it is
reviewed and brought into 2.0.  The separate documents approach requires
explicit linking, whereas having the text initially in the 2.0 document
does not.  Both allow us to see how the text was changed, but the start-
with-SVG-1.1-text approach doesn’t require any additional, manual work;
the VCS tracks this for us.

One of the concerns raised was that if we start off with all of the 1.1
text in the 2.0 document that we will be less likely to make the bold
changes to the specification we need to improve its quality.  I think we
just need to bear this in mind, and not be content to promote old 1.1
text to “reviewed” 2.0 text with only a cursory look over.  I know I
will do my part not to let 1.1 text in there unchanged unless it’s
perfect! :-)

I don’t think this approach even constrains us to use the same document
structure.  If we wanted to structure the document radically
differently, we can still create entirely different sections and move 
the old or old-but-modified-and-reviewed text to these new sections as
we go.  These changes would still be tracked by the VCS.

> Review:
… 
> 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.

Currently, when a WG member wants to get review of some text we have
tended to either send out proposed wording (but not a proposed exact
patch) to the mailing list to solicit comments on it, or to make the
change in the specification and solicit comments on it afterwards.  If
we want to require review of changes (for those changes that the
individual makes the judgement that they require review), we can’t
continue to use either of these.

In the telcon, Doug was talking about a “commit then review” policy
where changes would be committed to the specification, marked as
unreviewed, and then someone would be asked to review it explicitly.
(Correct me if I’m not quite right about what we discussed.)  I’ll note
though that traditionally, “commit then review” means that people commit
changes at will, and after the fact if anyone notices something they
don’t like, they can ask for it to be removed and then changed subject
to review:

  http://www.apache.org/foundation/glossary.html#CommitThenReview

If we want to ensure every substantial change gets review, then RTC is
probably a better model.

One advantage of making changes directly to the specification is that
you get to see the changes in context.  Jonathan’s proposal for showing
proposed changes in context (the “hg pb-diff” command) would ameliorate
this.  It also means that the specification history in the VCS isn’t
cluttered with “bad” unreviewed text.

-- 
Cameron McCormack ≝ http://mcc.id.au/

Received on Thursday, 24 March 2011 22:21:43 UTC