Re: Working on the VCTF Use Cases

I hate long emails, but this one turned out long after all.


For the WebRTC work there were several issues.  First, the WebRTC
specification itself was to be developed by the WebRTC Working Group, while
the Media Capture and Streams specification was developed by a joint Task
Force of the WebRTC and Device APIs working groups.   Thus, the
intellectual property disclosures required were slightly different.  In
addition, both produced dated Editors’ Drafts, which were desired by the
group in order to be able to clearly reference static documents when
describing the status of support of early implementations and also in order
to ensure that intellectual property review by participants occured as the
work progressed.

Since the dated drafts of the two were needed at different times, it was
important to be able to tag the repository with the date of the one being
published without implying anything about the other.


Since then, others have created spinoff documents in separate repositories
themselves that operate completely independently.  There has been no need
to verify that pushes by a truly separate group of participants did not
somehow break those of another.  Use of Travis and similar tools can
address some of this, but in the end conflicts introduced because of
accidental changes elsewhere still require human beings to figure out what
happened.


Regarding common contents, that has not been much of an issue so far since
dependencies are largely one-way.  Glossary entries in one document can be
referred to by another merely by adding the former into the references
section.  Although there is some commonality in the references sections of
the documents, the fact that all use the common ReSpec document database is
usually sufficient to reduce duplication of work.


I think the more significant question is, “what workflow do we expect?”

-  With one librarian or master editor who has exclusive ability to check
in changes, there is very little risk that a change in one document will
adversely affect another.  Of course, this can slow down progress and lead
to claims of despotism.

-  With a small number of editors (those with ability to check into the
master), they can discuss fairly easily what to do with conflicts and
perhaps cross-check with each other to ensure only consensus-based changes
go in.

- With a large number of editors (more likely with more separate documents
in one repository), the coordination aspect is trickier.


I know that I said that I strongly advise having separate repositories.
Frankly, it may not matter much yet.  Perhaps we should just start with one
and see how it goes.  We can always move documents elsewhere if necessary.


-- dan

On Thu, Jan 21, 2016 at 12:08 PM, Gregg Kellogg <gregg@greggkellogg.net>
wrote:

> On Jan 21, 2016, at 3:41 AM, Daniel Burnett <danielcburnett@gmail.com>
> wrote:
>
> Guys, I'm checking into the possibility of duplicating the WebRTC github
> setup for our work.  Dominique Hazaël-Massieux, developer of many of the
> tools editors have been using, including the PubRules checker, has been
> building up tooling for us in WebRTC, including Travis scripts.  I think we
> could benefit from borrowing what he's set up.
>
> I will ask the WebRTC Chairs in today's WebRTC editors' call if they have
> any problems with it, and if not I'll talk with Dom to see what would be
> needed.  We have a few publication oddities that would need to be adjusted.
>
> Regarding repositories, many groups differ in opinion on how separated the
> different specs in their groupls should be.  Having started with the two
> primary WebRTC specs being together but eventually separating them because
> they progressed independently, I would highly recommend a separate
> repository for each but with a common initial name, e.g., vctf-use-cases
> for this document.
>
>
> I’d like to better understand the reasoning and experience behind using
> separate repositories for different specs. The CSV on the Web group (
> http://github.com/w3c/csvw) had four specs and three notes under way on
> different timelines with no real problems from using a single repository,
> and there were advantages from being able to share common examples,
> bibliographies, and other tools for synchronizing shared components among
> the specs.
>
> Gregg
>
> -- dan
>
> On Tue, Jan 19, 2016 at 3:11 PM, Shane McCarron <shane@halindrome.com>
> wrote:
>
>> No - I don't think they have been published yet.
>>
>> On Tue, Jan 19, 2016 at 2:08 PM, Ian Jacobs <ij@w3.org> wrote:
>>
>>>
>>> > On Jan 19, 2016, at 1:43 PM, Shane McCarron <shane@halindrome.com>
>>> wrote:
>>> >
>>> > Today in the VCTF call I and a few others offered to get the use cases
>>> into W3C form and cleaned up.  I would like to get started on this straight
>>> away.
>>>
>>> Hi Shane,
>>>
>>> Do you have a link to the minutes of the meeting? Thanks,
>>>
>>> Ian
>>>
>>> >
>>> > I know that we are working on github [1].  Is there any reason not to
>>> put the documents in that tree?  And if they are in that tree, does it make
>>> sense to put then under some top level folder (documents?) or should each
>>> document be in its own top level folder (usecases)?
>>> >
>>> > [1] https://github.com/w3c/vctf
>>> >
>>> >
>>> > --
>>> > -Shane
>>>
>>> --
>>> Ian Jacobs <ij@w3.org>      http://www.w3.org/People/Jacobs
>>> Tel:                       +1 718 260 9447
>>>
>>>
>>>
>>>
>>
>>
>> --
>> -Shane
>>
>
>
>