Rewrite Share interface docs and split into two APIs.

Rewrite Share interface docs and split into two APIs.

This changes the API surface from generic actions to a specific
share-only API called Web Share, and a follow-up proposal called Web
Share Target. The idea is to partition the Ballista project into
specialized interfaces that can be independently standardized.

R=benwells@chromium.org

Committed: https://github.com/chromium/ballista/blob/master4a66ebdc86d321cb916f25bd447a206eb2477e23

[Matt Giuca, 2016-05-30 03:04:59]

Description was changed from

==========
Rewrote interface_share for just share, no extensibility in mind.

Trying out this minimal API instead of the previous version, which was a
scaffold for the full API to come.
==========

to

==========
Rewrite Share interface docs and split into two APIs.

This changes the API surface from generic actions to a specific
share-only API called Web Share, and a follow-up proposal called Web
Share Target. The idea is to partition the Ballista project into
specialized interfaces that can be independently standardized.
==========

[Matt Giuca, 2016-05-30 03:05:06]

Description was changed from

==========
Rewrite Share interface docs and split into two APIs.

This changes the API surface from generic actions to a specific
share-only API called Web Share, and a follow-up proposal called Web
Share Target. The idea is to partition the Ballista project into
specialized interfaces that can be independently standardized.
==========

to

==========
Rewrite Share interface docs and split into two APIs.

This changes the API surface from generic actions to a specific
share-only API called Web Share, and a follow-up proposal called Web
Share Target. The idea is to partition the Ballista project into
specialized interfaces that can be independently standardized.
==========

[Matt Giuca, 2016-05-30 03:05:54]

mgiuca@chromium.org changed reviewers:
+ benwells@chromium.org

[Matt Giuca, 2016-05-30 03:05:56]

Ben, PTAL. Probably easier to just read the updated formatted documents:
https://github.com/mgiuca/ballista/blob/share-only-api/docs/interface_share.md
https://github.com/mgiuca/ballista/blob/share-only-api/docs/interface_share_t...
https://github.com/mgiuca/ballista/blob/share-only-api/docs/explainer.md

[benwells, 2016-06-01 00:48:33]

https://codereview.chromium.org/1963823003/diff/60002/docs/interface_share.md
File docs/interface_share.md (right):

https://codereview.chromium.org/1963823003/diff/60002/docs/interface_share.md...
docs/interface_share.md:7: for a website to receive share requests; only native
system services can
I think the statement 'only native system services can receive' is kinda false
and should be removed.

Maybe rephrase the whole thing as 'The basic Share API only allows share
requests to be sent; no capability for websites to receive share requests is
enabled by this API. For a follow-up plan ...'

https://codereview.chromium.org/1963823003/diff/60002/docs/interface_share.md...
docs/interface_share.md:13: [explainer document](explainer.md).
Can we move these into this document? This API proposal should be self
contained.

https://codereview.chromium.org/1963823003/diff/60002/docs/interface_share.md...
docs/interface_share.md:52: We may later expand this to allow image data or file
blobs.
Should this be a TODO, or at least more definite (like, <b>For
consideration:</b> Expand this to allow image data and / or file blobs).

https://codereview.chromium.org/1963823003/diff/60002/docs/interface_share.md...
docs/interface_share.md:57: [here](user_flow.md).
Again, these should be moved into this document to make it self contained.

[Matt Giuca, 2016-06-01 01:01:14]

https://codereview.chromium.org/1963823003/diff/60002/docs/interface_share.md
File docs/interface_share.md (right):

https://codereview.chromium.org/1963823003/diff/60002/docs/interface_share.md...
docs/interface_share.md:7: for a website to receive share requests; only native
system services can
On 2016/06/01 00:48:33, benwells wrote:
> I think the statement 'only native system services can receive' is kinda false
> and should be removed.
> 
> Maybe rephrase the whole thing as 'The basic Share API only allows share
> requests to be sent; no capability for websites to receive share requests is
> enabled by this API. For a follow-up plan ...'

Done.

https://codereview.chromium.org/1963823003/diff/60002/docs/interface_share.md...
docs/interface_share.md:13: [explainer document](explainer.md).
On 2016/06/01 00:48:33, benwells wrote:
> Can we move these into this document? This API proposal should be self
> contained.

Are you saying the explainer and interface doc should be merged into a single
doc? I am fully rewriting the explainer in a follow-up CL. Even so, I don't
think we necessarily want these spec-like interface details in what is otherwise
a high-level document.

https://codereview.chromium.org/1963823003/diff/60002/docs/interface_share.md...
docs/interface_share.md:52: We may later expand this to allow image data or file
blobs.
On 2016/06/01 00:48:33, benwells wrote:
> Should this be a TODO, or at least more definite (like, <b>For
> consideration:</b> Expand this to allow image data and / or file blobs).

Done.

https://codereview.chromium.org/1963823003/diff/60002/docs/interface_share.md...
docs/interface_share.md:57: [here](user_flow.md).
On 2016/06/01 00:48:33, benwells wrote:
> Again, these should be moved into this document to make it self contained.

The user_flow mocks are being moved (in the follow-up CL) into the explainer
document. Again, I don't think they make sense here in this more spec-like
document.

[benwells, 2016-06-01 01:28:11]

https://codereview.chromium.org/1963823003/diff/60002/docs/interface_share.md
File docs/interface_share.md (right):

https://codereview.chromium.org/1963823003/diff/60002/docs/interface_share.md...
docs/interface_share.md:13: [explainer document](explainer.md).
On 2016/06/01 01:01:13, Matt Giuca wrote:
> On 2016/06/01 00:48:33, benwells wrote:
> > Can we move these into this document? This API proposal should be self
> > contained.
> 
> Are you saying the explainer and interface doc should be merged into a single
> doc? I am fully rewriting the explainer in a follow-up CL. Even so, I don't
> think we necessarily want these spec-like interface details in what is
otherwise
> a high-level document.

I mean that this needs to end up in a repository just for share. That repository
should not have substantial content in other repositories, like a more general
ballista repository.

The examples and mocks can be in separate documents, but they should not be in
more general document which will end up being in another repo.

[Matt Giuca, 2016-06-01 01:31:57]

https://codereview.chromium.org/1963823003/diff/60002/docs/interface_share.md
File docs/interface_share.md (right):

https://codereview.chromium.org/1963823003/diff/60002/docs/interface_share.md...
docs/interface_share.md:13: [explainer document](explainer.md).
On 2016/06/01 01:28:11, benwells wrote:
> On 2016/06/01 01:01:13, Matt Giuca wrote:
> > On 2016/06/01 00:48:33, benwells wrote:
> > > Can we move these into this document? This API proposal should be self
> > > contained.
> > 
> > Are you saying the explainer and interface doc should be merged into a
single
> > doc? I am fully rewriting the explainer in a follow-up CL. Even so, I don't
> > think we necessarily want these spec-like interface details in what is
> otherwise
> > a high-level document.
> 
> I mean that this needs to end up in a repository just for share. That
repository
> should not have substantial content in other repositories, like a more general
> ballista repository.
> 
> The examples and mocks can be in separate documents, but they should not be in
> more general document which will end up being in another repo.

Oh OK, gotcha. Yes, that refactoring is the subject of my next gigantic
explainer-rewrite-and-move-everything-around CL.

[benwells, 2016-06-01 01:47:54]

lgtm

https://codereview.chromium.org/1963823003/diff/60002/docs/interface_share.md
File docs/interface_share.md (right):

https://codereview.chromium.org/1963823003/diff/60002/docs/interface_share.md...
docs/interface_share.md:13: [explainer document](explainer.md).
On 2016/06/01 01:31:57, Matt Giuca wrote:
> On 2016/06/01 01:28:11, benwells wrote:
> > On 2016/06/01 01:01:13, Matt Giuca wrote:
> > > On 2016/06/01 00:48:33, benwells wrote:
> > > > Can we move these into this document? This API proposal should be self
> > > > contained.
> > > 
> > > Are you saying the explainer and interface doc should be merged into a
> single
> > > doc? I am fully rewriting the explainer in a follow-up CL. Even so, I
don't
> > > think we necessarily want these spec-like interface details in what is
> > otherwise
> > > a high-level document.
> > 
> > I mean that this needs to end up in a repository just for share. That
> repository
> > should not have substantial content in other repositories, like a more
general
> > ballista repository.
> > 
> > The examples and mocks can be in separate documents, but they should not be
in
> > more general document which will end up being in another repo.
> 
> Oh OK, gotcha. Yes, that refactoring is the subject of my next gigantic
> explainer-rewrite-and-move-everything-around CL.

Acknowledged.

[Matt Giuca, 2016-06-03 05:11:44]

Description was changed from

==========
Rewrite Share interface docs and split into two APIs.

This changes the API surface from generic actions to a specific
share-only API called Web Share, and a follow-up proposal called Web
Share Target. The idea is to partition the Ballista project into
specialized interfaces that can be independently standardized.
==========

to

==========
Rewrite Share interface docs and split into two APIs.

This changes the API surface from generic actions to a specific
share-only API called Web Share, and a follow-up proposal called Web
Share Target. The idea is to partition the Ballista project into
specialized interfaces that can be independently standardized.

R=benwells@chromium.org

Committed:
https://github.com/chromium/ballista/blob/master4a66ebdc86d321cb916f25bd447a2...
==========

[Matt Giuca, 2016-06-03 05:11:47]

Committed patchset #6 (id:90001) manually as
4a66ebdc86d321cb916f25bd447a206eb2477e23 (presubmit successful).