[gmscore] Add Google Play services documentation

docs/google_play_services.md

Index: docs/google_play_services.md
diff --git a/docs/google_play_services.md b/docs/google_play_services.md
new file mode 100644
index 0000000000000000000000000000000000000000..3fad754f41fecaacb6e948922d5eb17a5b4c8dbf
--- /dev/null
+++ b/docs/google_play_services.md
@@ -0,0 +1,53 @@
+# Google Play services in Chrome for Android
+
+[TOC]
+
+Google employee? See [go/chrome-gms](https://goto.google.com/chrome-gms) for
+more info.
+
+## General setup
+
+The Google Play services are a combination of [services][play_store] exposed on
+Android devices, and [libraries][dev_doc] to interact with them. Chrome relies
+on them for critical features like Sign in, Feedback or Cast.
+
+The standard way of adding the Google Play services as a dependency to a project
+is to import it through the Android SDK manager, as a Maven repository. That
+repository contains multiple versions of the library, split into separate APIs
+(for example Cast, GCM, Android Pay, etc.) To avoid downloading a lot of data we

[jbudorick, 2016/11/29 16:09:35]

nit: . outside )

[dgn, 2016/12/06 18:19:21]

Done.

+won't need to build Chrome, android checkouts of Chromium will download an
+archive containing only the APIs we currently need in Chrome, and in a single
+version.
+
+The up to date list of clients and version used can be seen in
+[//build/android/play_services/config.json][config_json_rel_path].
+
+> If you are working on a feature that requires different or more recent APIs,
+> you will need to locally download the Google Play services SDK repository.

[mcasas, 2016/11/24 22:19:12]

nit: probably these two lines don't need to be quoted.

[dgn, 2016/11/25 16:53:52]

I just wanted to make that more visible. (preview:
https://user.git.corp.google.com/dgn/md-tests/+/master/google_play_services.md)

unnecessary?

[jbudorick, 2016/11/29 16:09:35]

I'm fine with this as-is, though you could also consider something like

**Note**: If you are working ...

[dgn, 2016/12/06 18:19:21]

Done.

+
+The simplest way to download the latest SDK is to run:
+
+```
+$CHROMIUM_SRC/build/android/play_services/update.py sdk
+```
+
+Check out the help of that script for more info.
+
+[play_store]: https://play.google.com/store/apps/details?id=com.google.android.gms
+[dev_doc]: https://developers.google.com/android/guides/overview
+[config_json_rel_path]: ../build/android/play_services/config.json
+
+## Adding a dependency on new APIs
+
+As explained above, the default checkout has access to only a specific set of
+APIs during builds. If your CL depends on some APIs that are not included in the
+build, you will need to make a request to update our dependencies.
+
+Just [file an issue][bug_link] and assign it to dgn@chromium.org

[jbudorick, 2016/11/29 16:09:35]

Nit: I would just incorporate this into the previous sentence as [make a
request][bug link] and leave your email address out of the visible text since
it's already in the bug template.

[dgn, 2016/12/06 18:19:21]

Done.

+
+Not doing so could make the CL fail on the trybots and commit queue. Even if it
+passes, it might fail on the internal bots, and result in the CL getting
+reverted. So please make sure the APIs are available to the bots before
+submitting.
+
+[bug_link]:https://bugs.chromium.org/p/chromium/issues/entry?labels=Restrict-View-Google,pri-1,Hotlist-GooglePlayServices&owner=dgn@chromium.org&os=Android

[mcasas, 2016/11/24 22:19:12]

Great stuff, if you want you could also link as example the use
case we're dealing with, i.e. vision APIs, where you landed the
new package and BUILD.gn [1] and gmscore update in [2], 
to be used in [3].

For local development and before landing all that code, I 
essentially needed [1] and `update.py sdk` (l.28).

[1] https://crrev.com/2524063002
[2] https://chrome-internal-review.googlesource.com/#/c/307576/
[3] https://crrev.com/2512123002

[dgn, 2016/11/25 16:53:52]

I don't really want to explain exactly how to roll out the update yourself here
because you need internal access to update the library anyway. I'll update the
internal doc to include the example, there it would be more useful I think.

[jbudorick, 2016/11/29 16:09:35]

This would be great.

[dgn, 2016/12/06 18:19:21]

Acknowledged.