Re: TTML2 Editing Process

On Tue, May 10, 2016 at 10:02 AM, Glenn Adams <glenn@skynav.com> wrote:

>
>
> On Tue, May 10, 2016 at 9:29 AM, Nigel Megitt <nigel.megitt@bbc.co.uk>
> wrote:
>
>> From: Glenn Adams <glenn@skynav.com> Date: Monday, 9 May 2016 23:58
>>
>>
>> On Mon, May 9, 2016 at 10:53 AM, Glenn Adams <glenn@skynav.com> wrote:
>>
>>>
>>>
>>> On Mon, May 9, 2016 at 5:24 AM, Nigel Megitt <nigel.megitt@bbc.co.uk>
>>> wrote:
>>>
>>>> Hi Glenn,
>>>>
>>>> Thank you for this – it'll be great to start using pull requests like
>>>> this, and I appreciate your flexibility in changing the editorial process,
>>>> and thoroughness in documenting it. A couple of questions and a request:
>>>>
>>>> 1. The process excludes the possibility of merging into a PR branch
>>>> from another branch: I think there could be a legitimate reason for doing
>>>> this occasionally, so I'm not sure why we would prohibit it?
>>>>
>>>
>>> OK, I will relax the guideline to allow this
>>>
>>
>> After further consideration, I don't see an apparent reason to do this.
>> PR branches should remain issue specific. And each PR branch is associated
>> (by name) with a given issue. So if you merged a PR branch associated with
>> issue 1 with a PR branch associated with issue 2, then merged that result
>> into gh-pages, you will have two issues which PR have been intermixed from
>> the perspective of gh-pages history. This sounds like a bad idea indeed.
>>
>>
>> I agree that would be bad, but that isn't the use case. The use case is
>> where someone wants to make a change to a branch that's the source for a PR
>> for an issue, as described at
>> https://lists.w3.org/Archives/Public/public-tt/2016May/0028.html This
>> could occur if there's contention regarding the correct way to resolve an
>> issue, or a complex further edit is proposed by someone other than the
>> original creator of the branch. It's also possible to commit directly to
>> the source branch of course, by agreement.
>>
>> This is an edge case though, so I propose we continue with the scheme
>> you've outlined and address any issues with the process if they arise.
>>
>>
>> So I think the best option for now is leave the current guideline in
>> place until someone has a real case where merging a  PR branch into another
>> PR branch makes more sense than not.
>>
>>
>>>
>>>
>>>>
>>>> 2. Since the process requires an issue number, do you plan to create
>>>> issues for each editorial note that needs further work? Some of those
>>>> editorial tasks could usefully be completed by group members via PRs.
>>>> Alternatively a different naming format for non-issue editorial fixes could
>>>> work.
>>>>
>>>
>>> I plan to create issues for existing editorial notes.
>>>
>>
>> Thank you!
>>
>>
>>>
>>>>
>>>> The other thing to note is that since this process does not require
>>>> consensus prior to merging, we will need a separate review phase for every
>>>> snapshot that we wish to consider for publication as a WD.
>>>>
>>>
>>> That is a necessary requirement for publishing in any case.
>>>
>>
>> Actually it would be satisfied by reviewing each PR with WD publication
>> in mind – then after the pull request has been merged the new version on
>> gh-pages would be suitable for automated publishing as a WD on /TR. This
>> doesn't prevent a parallel branch from being maintained representing an
>> editor's draft, which could be some commits ahead.
>>
>> However, since each PR and its merge can be reviewed incrementally, and
>>> follow-on issues can be created to address post-merge problems, then that
>>> "separate review phase for every snapshot" can be of a very short duration
>>> provided folks are paying attention to PR merge notifications and doing
>>> post-merge reviews in a timely fashion, rather than waiting for the
>>> "separate review phase" to catch up with their reviews.
>>>
>>
>>>
>>>> I'm guessing you've chosen that route so that you can resolve any
>>>> temporal blockages caused by waiting for consensus, as discussed in last
>>>> week's meeting.
>>>>
>>>
>>> I've chosen to retain CTR policy because that is what we have been using
>>> since 2003, and because I believe this lies at the heart of an editor's
>>> privileges and responsibilities.
>>>
>>
>> I'm not proposing a change to the policy, just the mechanism for
>> executing it.
>>
>>
>>>
>>>>
>>>> I suppose I'd just request that where possible you do wait for a
>>>> consensus prior to merging, since that will reduce our incremental review
>>>> time prior to publishing new WDs.
>>>>
>>>
>>> Incremental review prior to publishing a new WD is not increased by this
>>> process.
>>>
>>
>> I wasn’t clear what I meant by "incremental": I meant the extra time
>> needed post pull request merge in order to get to WD publication. When
>> we're able to confirm consensus prior to the merge then zero incremental
>> time is needed to publish a new WD – the Editor or Chair can just do it. If
>> we need to go back and check we have consensus then some incremental review
>> is introduced.
>>
>
> The echidna process requires a group decision [3]. So the Editor or Chair
> can't simply pull the trigger. Again, by lazy consensus, if a team member
> has not objected to a prior PR merge, then consensus is present.
>
> [3]
> https://www.youtube.com/watch?v=yI-7mQUTiXI&src_vid=0SRonXlRHXk&annotation_id=annotation_880483967&feature=iv
>

Oops. I appear to have pasted in a link from a FB thread from yesterday
rather than the echidna documentation. Please disregard this link, and use
the following instead:

[3] https://github.com/w3c/echidna/wiki/How-to-use-Echidna#group-decision


>
>
>>
>> It is still amortized as if RTC were used. The only difference is that
>>> the review increments start at the time each PR is created, and may
>>> continue after the PR merge, while in the RTC approach PR merge doesn't
>>> occur until review is complete.
>>>
>>
>>>
>>>> If we can keep track of those PRs that you merge without consensus,
>>>> that would be helpful.
>>>>
>>>
>>> I have assume that "silence means agreement", i.e., "lazy consensus"
>>> applies; so it will be the responsibility of a reviewer to speak up if
>>> there is an issue with the results of a PR merge. They can do that
>>> incrementally as PRs are proposed and merged.
>>>
>>
>> I'd be interested to know how group members feel about this. If there are
>> no objections to this way of working then it can indeed work.
>>
>
> This is how all the work on TTML1 and TTML2 were done to date. I agree it
> may not have been documented well, but it was certainly discussed and
> agreed upon long ago. So this isn't nothing new.
>
> What is new, is that the group membership has changed in recent years, and
> we haven't managed to fully articulate the principles that we were
> operating under, including that of lazy consensus.
>
> I thought it appropriate now to document this fact to avoid confusion in
> the future.
>
>
>>
>> The potential difficulty is that it makes it harder for keen but busy
>> people to track which PRs they need to review, since some of them may
>> already be closed.
>>
>
> They should have the initial PR creation email notification in their
> mailbox. They can use that as an index of what to review.
>
>
>>
>>
>>> Clearly, it would be a bad idea for the editor to preemptively merge a
>>> PR he knows ahead of time will be controversial or produce an objection. It
>>> will be his judgement about whether to merge and when that may occur (if at
>>> all).
>>>
>>
>> Good point.
>>
>>
>>>
>>>>
>>>> Kind regards,
>>>>
>>>> Nigel
>>>>
>>>>
>>>>
>>>> From: Glenn Adams <glenn@skynav.com>
>>>> Date: Sunday, 8 May 2016 22:56
>>>> To: TTWG <public-tt@w3.org>
>>>> Subject: TTML2 Editing Process
>>>> Resent-From: <public-tt@w3.org>
>>>> Resent-Date: Sunday, 8 May 2016 22:57
>>>>
>>>> I have documented the (new) TTML2 Editing Process [1]. This process
>>>> adopts the standard github pull-request mechanism; therefore, it provides
>>>> the advantages of fine-grained review of issue-based merges.
>>>>
>>>> The only variation to what has been followed with IMSC1 is that I have
>>>> retained the commit-then-review (CTR) process that has been used for TTML1
>>>> and TTML2 to date.
>>>>
>>>> [1] https://github.com/w3c/ttml2/blob/gh-pages/EDITING.md
>>>>
>>>>
>>>>
>>>> ----------------------------
>>>>
>>>> http://www.bbc.co.uk
>>>> This e-mail (and any attachments) is confidential and may contain
>>>> personal views which are not the views of the BBC unless specifically
>>>> stated.
>>>> If you have received it in error, please delete it from your system.
>>>> Do not use, copy or disclose the information in any way nor act in
>>>> reliance on it and notify the sender immediately.
>>>> Please note that the BBC monitors e-mails sent or received.
>>>> Further communication will signify your consent to this.
>>>>
>>>> ---------------------
>>>>
>>>
>>>
>>
>>
>> ----------------------------
>>
>> http://www.bbc.co.uk
>> This e-mail (and any attachments) is confidential and may contain
>> personal views which are not the views of the BBC unless specifically
>> stated.
>> If you have received it in error, please delete it from your system.
>> Do not use, copy or disclose the information in any way nor act in
>> reliance on it and notify the sender immediately.
>> Please note that the BBC monitors e-mails sent or received.
>> Further communication will signify your consent to this.
>>
>> ---------------------
>>
>
>