Split doc into identity.html and actions.html

[jan-ivar]

At the chairs meeting today, as a compromise to adopt working on APIs for both identification and actions, we agreed to merge #7 and #8, and then split this document into two documents to live in the same repo, then adopt both:

• identity.html to cover the existing identification API, and
• actions.html to cover actions (as outlined in #15).

This should allow actions.html to mature independently from identity.html, hopefully assuaging concerns that one might hold up the other (even though there are issues with both). The WG can then consider merging them at a later stage, if that makes sense then.

I'll create a new PR to do so based on #15. In the interest of completing adoption, I suggest we open new issues for the remaining feedback discovered in #15 (hopefully in a w3c repo shortly!)

Appologies if this precedes an announcement in public-webrtc, as we want to get the PR ready. cc @alvestrand @aboba

[eladalon1983]

I've split into two separate directories, which will help us keep demos, README files and other things separate. (A shared README file that discusses things overall is possible, but when discussing the APIs themselves, it helps to keep separate files.)

[jan-ivar]

@eladalon1983 This is not what we agreed to in Monday's chairs meeting. The chairs agreed to rejigger #15 into identity.html and actions.html, with Elad any myself as editors of both. cc @dontcallmedom @alvestrand, @aboba

This means all the other files should stay where they are.

I like the index.html overview doc that links to both docs, which should work regardless of directory structure.

I think we need to undo the directory changes, and merge #17 instead.

[jan-ivar]

See https://lists.w3.org/Archives/Public/public-webrtc/2022Feb/0066.html

[jan-ivar]

I like the index.html overview doc that links to both docs, which should work regardless of directory structure.

But it should not auto-redirect.

[eladalon1983]

• The redirection was introduced before the Actions spec file was merged. Since it's now merged, the redirection is now gone.
• We'll both be editing both documents initially (PR). In the future, more people may join our efforts, and the list of editors for each document might diverge.
• More importantly, the demos, the explainers, the security questionnaires - all of these things will be distinct, and are more easily organized in separate directories.

[jan-ivar]

When a compromise is negotiated which straddles concerns, details matter:

• one side wanted both APIs in the same document, and
• the other side wanted them in separate repos.

The compromise reached was quite explicitly to split the document into identity.html and actions.html. This precariously balanced the concerns of both sides, to where agreement was reached, because both sides saw something they could live with. Hopefully what they saw was the same thing, but these recent changes suggest perhaps not.

... the list of editors for each document might diverge.

This assumes we split all the files, which was literally not the compromise struck. This wouldn't have been the case if the two APIs were in the same document, so there are two mindsets on whether this is desirable. My understanding of the compromise was that the same editors would be responsible for driving both APIs.

PR #17 (which is mentioned explicitly in the stated chairs agreement), faithfully split the doc into two, duplicating the intro and use cases (maybe I should have taken out use cases 2-4), and updated the README.md to briefly mention Actions. Crucially, it kept all the following files shared:

CHANGELOG.md
README.md
CODE_OF_CONDUCT.md
security-privacy-questionnaire.md
CONTRIBUTING.md
capture-handle.js
w3c.json
LICENSE.md
demos

As a representative of the side that wished this to be a single document in the first place, this matters, and is a big part of why I agreed to the compromise: The WG will pursue and standardize both APIs to solve the same use case 1, and readers will discover both APIs.

(@dontcallmedom informs me capture-handle.js cannot be shared, but a separate capture-actions.js file (name TBD) in the same directory should suffice to solve that).

Lastly, we have a process to follow that's supposed help in situations where there are different mindsets. As co-editor of both documents, I would expect to discuss changes in regular Editor's Meetings, intead of reacting to unilateral pushes.

I propose we follow that process and do what we said we would do to get these documents adopted and into the w3c repo ASAP where we will have the benefit of this process to track and aid further changes.

[eladalon1983]

The compromise reached was quite explicitly to split the document into identity.html and actions.html.

I did not consent to this.

As a representative of the side that wished this to be a single document in the first place

Could I please know whom you are representing in this matter? Are there additional parties other than yourself?

The WG will pursue and standardize both APIs

This has not changed.

it kept all the following files shared

The explainer, security questionnaire and demos should remain distinct. At the moment, only one API is implemented, has demos, etc. Combining things would sow confusion over what is implemented and what is not. It would not serve readers well.

When this changes - Actions is specified and prototyped - we can revisit the topic and see if merging the explainers yields a result that serves the readers.

[jan-ivar]

I did not consent to this.

This was a chairs' agreement.

[eladalon1983]

I did not consent to this.

This was a chairs' agreement.

Then it would be good to avoid the word "we" so as not to create the impression that I am going back on my word.

I am not aware of a chairs' decision to NOT put identity.html and actions.html in their own directories, nor would I have supported such a decision. I have given you objective reasons for why I think this should be done. I suggest we discuss this objective matter. Why do you NOT want separate directories?

[eladalon1983]

Lastly, we have a process to follow that's supposed help in situations where there are different mindsets. As co-editor of both documents, I would expect to discuss changes in regular Editor's Meetings, intead of reacting to unilateral pushes.

This process will apply once the repo is adopted by the W3C.

[alvestrand]

My interpretation of the discussion on the chairs' call was that the critical agreement was that there would be two documents. The chairs agreed that there would be issues that needed to be discussed across both documents, and therefore keeping them in one repo with one bug tracker had advantages over splitting them into two different repos; the possibility of splitting into two different repos if it turned out that there were no such issues was deliberately left open.

I must admit that I did not think about the files apart from the specs themselves while discussing the disposition; since the existing README and security-privacy-questionnaire have been written with identity in mind and do not have references to actions, it makes sense to keep them together with identity for now.

I'm happy with the split being done on a directory level.

[jan-ivar]

AFAICT the README and demos cover use case 1 which can be covered by both APIs, so I see no reason to have separate conversations for them.

[alvestrand]

The README and demos, as presently written, cover using identity to satisfy use case 1. The use of actions with these use cases is not described in the current README and demos.

The argument for using actions in this use case has been made verbally, but not in the README.

[jan-ivar]

The use of actions with these use cases is not described in the current README ...

@alvestrand https://github.com/WICG/capture-handle/pull/17 adds a single paragraph to the README:

Capture Handle is a mechanism that allows a display-capturing web-application to
ergonomically and confidently identify the web-application it is display-capturing
(provided that the captured application has opted-in). Such identification allows
these two applications to collaborate in interesting ways.

+ Capture Actions is a mechanism that allows a display-capturing web-application to issue
+ predefined standard actions like "next" and "previous" to the web-application it is display-
+ capturing (provided that the captured application has opted-in).

For example, if a VC application is capturing a presentation, then the VC application can
expose user-controls for previous/next-slide directly in the VC application. This lets the user
navigate presentations without having to jump between the VC and presentation tabs.

...because this seemed the minimum needed to establish scope. That the rest of the README.md is not finished, shouldn't block adoption IMHO which is the start of standardization, not the end.

The README.md is the repo landing page, and it's important to me that readers can find both documents from it.

This repo doesn't currently have an explainer.md (which is what the TAG looks for) so that's thankfully one less file we need to agree on ahead of adoption.

For the security questionaire @dontcallmedom proposed identity/security-questionaire.md this morning, which I would be OK with (even though it's a directory with one file).

For the demos folder, I would prefer it be at the top level, for visibility. This is where many folks go before they even look at documents. Since it's a folder, it can already contain multiple files, which seems sufficient to house all demos that exist today, as well as all demos we can come up with in to the future for either API.

Disclaimer: my statements here are based off the state of this repo Monday of this week, which is the last time I felt I had a good overview of the state of things. Specifically, there have been some duplication of files done this week that I think is unfortunate and should not have been made (like individual README.mds inside directories, which should be discouraged as they distract from the repo's top-level README.md and creates confusion and the impression that directories are somehow to be navigated as "sub-repos").

Is this something we could adopt?

[eladalon1983]

It is natural to have separate explainers for separate spec files. Insisting on a single shared explainer goes against the grain of separating the APIs into spec files - which was the compromise @jan-ivar has earlier agreed to.

[jan-ivar]

@eladalon1983 This repo doesn't have an explainer.md, so I'm not "Insisting on a single shared explainer".

In fact I said "...that's thankfully one less file we need to agree on ahead of adoption".

Let's avoid characterizations as they do not seem productive.

[eladalon1983]

@eladalon1983 This repo doesn't have an explainer.md, so I'm not "Insisting on a single shared explainer".

In fact I said "...that's thankfully one less file we need to agree on ahead of adoption".

Let's avoid characterizations as they do not seem productive.

My message was posted shortly after we[*] held a video conference about this that lasted 60 minutes. I believed I had a firm grasp of what you want, albeit not why. If I misunderstood you, or if you've changed your mind, or if anything else has taken place, and you are in fact willing to have two separate explainers, one for Identity and one of Actions, then that would be very good news indeed. Is that the case?

-- [*] Attendees - you, me, Dom, Bernard and Youenn.

[jan-ivar]

@eladalon1983 I'm proposing a way forward in https://github.com/WICG/capture-handle/issues/16#issuecomment-1058246851. I would like someone to engage with that.

My already stated view is we not block adoption on figuring out where a future explainer.md should live or whether there will be more than one.

I notice I keep saying explainer.md and you keep saying "explainer", which makes it not clear to me what you are talking about.

For instance, I was explicit above about not wanting "individual README.mds inside directories" to avoid the github "impression that directories are somehow ... "sub-repos"".

To which it looks to me like your response was: "It is natural to have separate explainers for separate spec files."

To me it sounds like you're conflating README.mds with explainer.mds. These are not the same things to me. Are they to you? Help me understand where the rub is.

[eladalon1983]

@eladalon1983 I'm proposing a way forward in #16 (comment). I would like someone to engage with that.

My already stated view is we not block adoption on figuring out where a future explainer.md should live or whether there will be more than one.

I notice I keep saying explainer.md and you keep saying "explainer", which makes it not clear to me what you are talking about.

For instance, I was explicit above about not wanting "individual README.mds inside directories" to avoid the github "impression that directories are somehow ... "sub-repos"".

To which it looks to me like your response was: "It is natural to have separate explainers for separate spec files."

To me it sounds like you're conflating README.mds with explainer.mds. These are not the same things to me. Are they to you? Help me understand where the rub is.

0. During our video meeting today, you have mentioned that it was hard to follow all of the moving files, and you suggested that we revert to an earlier version that you were more familiar with. It might be that you were looking exactly at the time that I was committing a few changes. Things are stable now. Could you please take another look? There is only a handful of files. I believe you'll find the structure very simple to understand and discuss.

1. Security-questionnaires: I think we're aligned on these being separate documents in separate directories. Could you please let me know if my memory is correct?

2. Explainers: Presently, the file named identity/README.md is the explainer for the Identity mechanism. We can keep that name, or we can rename it to identity/Explainer.md. In either case, I want separate spec-files to be matched to separate explainers. If you oppose this, please explain why. If you're OK with it - great, we're aligned.

3. Demos: Could you please explain why we should have the existing demos, that are all associated with the Identity API, in a shared directory? My position for wanting separation, is that a shared directory creates confusion over what API is used in those demos. What's your rationale for a shared directory for demos?

4. Spec files: Depending on the conclusion of the previous bullet-points, the sense of putting these in the base directory or sub-directories changes. Let's follow up immediately after settling 1-3.

[jan-ivar]

@eladalon1983 The issue is clarity not familiarity. I'm basing my statements off of Monday's state, to be unambiguous about what I describe. I'm not comfortable referencing the current repo for this due to how it's being handled right now (changes aren't going through PRs or review, making it an unstable reference unfortunately).

I've looked at the structural changes made since Monday, and, based on what I've already written, disagree with most of them. But if it would help understanding, undoing them would include:

1. identity/security-privacy-questionnaire.md can stay
2. Undo the README.md split (I've already explained why):
   • Move identity/README.md back to README.md, and add the #17 paragraph to it
   • Remove the empty actions/README.md
   • Defer deciding on location of any new explainer.md until after adoption, so we have the w3c process to help
3. Undo the Demos split (I've already explained why).
4. Top-level identity.html and actions.html. Other files should probably move out as well.

TL;DR: I'd like to remove any appearance of nested repos.

The spirit of the chairs' compromise that appealed to me was that these documents could live side by side, with a common README.md. This should satisfy any w3c process concerns, according to @dontcallmedom, so I'm not sure what other concerns there are.

[jan-ivar]

I also noticed the actions document is just a bunch of WebIDL with algorithms now, which isn't readable. So add

5. Restore actions.html to #17 state (with https://github.com/WICG/capture-handle/pull/8 which was never merged as agreed), which reused the intro and use cases from identity.html, which fit surprisingly well (I'll accept removing use cases 2-4).

It doesn't need to be perfect, but I see no reason to do less than the work I already did on this, so it'll look presentable out of the gate.

[alvestrand]

We have agreed that we have two specification documents, accepting that these may move up the W3C process cycle at different speeds, and we have agreed that they should live in the same repo for now since the assertion has been made (strongly, by Jan-Ivar) that there are sufficient couplings between them that there needs to be the ability to file issues on them in the same bug tracker.

I don't understand the insistence on appearing to increase the linkage between them by manipulating the shape of the repository to make it more difficult to handle ancillary documents that pertain to only one of the main documents.

In short: I don't think the objections to separate directories makes sense.

[jan-ivar]

... sufficient couplings between them that there needs to be the ability to file issues on them in the same bug tracker

The sufficient couplings between them run deeper than that: they solve the same primary use case, which is why I preferred a single document. Either solution telling this user story in isolation seemed a disservice to readers looking for solutions.

That's why there remains a shared story to tell about that use case in the top-level README.md before readers are cast into either solution. This is where they'll hopefully learn the pros and cons of the different approaches.

I agreed to split the documents for w3c process reasons. I rely on @dontcallmedom as the expert here, but I believe he's said most of the directory changes are unneeded for that, suggesting ancillary documents are easily handled either way.

... insistence on appearing to increase the linkage between them by manipulating the shape of the repository

I don't accept the characterization about who is "manipulating the shape of the repository". My PRs were comparatively minimal and never merged.

My remaining comments are about the unilateral changes made after Monday's chairs agreement to adopt:

1. A folder/README.md structure is an anti-pattern that undermines the top-level README.md, by confusing people about where they're supposed to land in GitHub to start reading. People have short attention spans and need to find things quick.

2. The same seems to hold for demos. People often explore these first, to find solutions to their problems. Having people pre-choose one solution to see demos of potential solutions to their problem, seems backwards. Side-note: while it's nice that one implementation has demos, demos seems premature for w3c adoption. We're not even at FPWD.

3. Separate explainer.md files seems reasonable to aid the w3c process, but they don't exist yet. However, my willingness to adopt without resolving this today seems to be misinterpreted. So in good faith, how about we copy README.md (minus #17) into identity/explainer.md, with the understanding that we'll refine the narrative split later (even allowing for some duplication)?

4. I still prefer actions.html and identity.html at the top level to not confuse people about where the home directory is.

[alvestrand]

Let's just say that I don't find the argument that "they solve the same primary problem" convincing, and I don't hear anyone but Jan-Ivar making that argument.

It is possible to solve one of the scenarios described using both components. It is possible to solve the same scenario using only one of the components + some other components using already existing standardized mechanisms, and it is possible (I think; I haven't yet started spitting PRs at it to point this out) to solve other interesting problems using only the other mechanism.

Reminder: Nobody (including Jan-Ivar) has committed to implementing the -actions mechanism; Chrome has had the -identity mechanism implemented and in origin trials since July 2021.

[jan-ivar]

The chairs have resolved adoption, so some of this is water under the bridge, but I do want to respond.

Reminder: Nobody (including Jan-Ivar) has committed to implementing the -actions mechanism;

Mozilla is committed to implementing the -actions mechanism, because it promises to provide the significant subset of the functionality that identity provides, but to a broader set of parties, which seems good for users. We hope other vendors join us in supporting this, to avoid users experiencing product lock-in.

Chrome has had the -identity mechanism implemented and in origin trials since July 2021.

I noticed that. Should this diagram perhaps be updated then?

[alvestrand]

"Formal spec" is not identical to "accepted by WG", so no.

I don't think it's accidental that this diagram does not mention the W3C at all - the kind of excessive delay that we've seen both here and with Breakout Box is one of the reasons why it's not reasonable to gate shipping on W3C adoption.

(I hope you can link to Mozilla's commitment to shipping the -action mechanism. I'd like to see what you've committed to.)

[eladalon1983]

Mozilla is committed to implementing the -actions mechanism

What about the -identity mechanism? You argued repeatedly for the two to be one of the same spec, objected to them appearing like sub-repos, etc. Will you implement both then?

[jan-ivar]

Answered offline.

[eladalon1983]

Answered offline.

There are other interested parties watching this repo. For their benefit, could you answer publicly?