[gnome-online-accounts/ebassi/docs-update: 2/3] docs: Add goals and services

[Emmanuele Bassi <ebassi src gnome org>]

commit 86f685cdb34493616217c61edd4c8eb24b2cc701
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Fri Jun 17 18:44:47 2022 +0100

    docs: Add goals and services
    
    Import documentation from the wiki and refresh it a bit.

 doc/goals.md    | 52 +++++++++++++++++++++++++++++++++++++++++++++
 doc/services.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 117 insertions(+)
---
diff --git a/doc/goals.md b/doc/goals.md
new file mode 100644
index 00000000..42ee093f
--- /dev/null
+++ b/doc/goals.md
@@ -0,0 +1,52 @@
+Title: Goals
+
+GNOME Online Accounts aims to provide a way for users to setup online accounts
+to be used by *the core system and applications*.
+
+System usage of online accounts includes GNOME Shell's calendar, cloud file
+storage in file selection dialogs (through GIO), cloud printing and Kerberos
+credentials. Core application integration includes things like Calendar,
+Contacts, Files and Photos.
+
+*While third-party applications can access the accounts setup through GNOME
+Online Accounts today, maintainers of third-party applications should contact
+the GNOME Online Accounts maintainers as well as the GNOME design and release
+team first*.
+
+Accounts offered through GNOME Online Accounts should appeal to a wide range
+of users.
+
+Account policy
+--------------
+
+Online Accounts uses a predefined list of online accounts that users can setup.
+Accounts are included that conform to the following policy:
+
+- Must be used by the core GNOME system and apps
+- Should ideally provide multiple services that can be consumed by multiple
+  apps and services
+- Should provide generic, common functionality that is readily recognised by
+  users 
+
+As a rule, specialist single-purpose accounts are avoided. Accounts which are
+only consumed by non-core or non-GNOME apps are similarly avoided.
+
+The following principles inform this policy:
+
+- Protect GNOME's access to online services. Applications using Online Accounts
+  use GNOME's profile to access those online accounts. It is the GNOME project's
+  responsibility to ensure that any access through its profiles follows the
+  account provider's terms and conditions. Breaching those terms and conditions
+  could result in GNOME's access being revoked. It is therefore important that
+  GNOME restricts access to its profiles, in order to mitigate any risk of this
+  happening.
+- Maintain the identity of third party applications. Applications which have
+  their own brands and identities ought to be exposed to services and users
+  using those identities, and should not be falsely advertised as "GNOME".
+- Ensure that online accounts are readily understood by users. A long list of
+  specialised account types would become burdensome for users.
+- Ensure that setting up an account has value for users. If a user sets up an
+  account, the services it provides ought to be accessible in obvious and
+  useful ways. People shouldn't be left wondering what the point was.
+- Work towards the goal of application sandboxing, in order to protect user
+  privacy and security. 
diff --git a/doc/services.md b/doc/services.md
new file mode 100644
index 00000000..70816e14
--- /dev/null
+++ b/doc/services.md
@@ -0,0 +1,65 @@
+Title: Services
+
+## Supported providers and services
+
+| Provider           | Mail | Calendar | Contacts | Maps | Photos | Files | Ticketing | Printers | Music |
+|--------------------|------|----------|----------|------|--------|-------|-----------|----------|-------|
+| Google             | yes  | yes      | yes      | no   | yes    | yes   | no        | yes      | no    |
+| Microsoft Personal | yes  | no       | no       | no   | no     | no    | no        | no       | no    |
+| Microsoft Exchange | yes  | yes      | yes      | no   | no     | no    | no        | no       | no    |
+| NextCloud          | no   | yes      | yes      | no   | no     | yes   | no        | no       | no    |
+| IMAP/SMTP          | yes  | no       | no       | no   | no     | no    | no        | no       | no    |
+| Kerberos           | no   | no       | no       | no   | no     | no    | yes       | no       | no    |
+| Last.fm            | no   | no       | no       | no   | no     | no    | no        | no       | yes   |
+
+## API Keys
+
+The list of API keys used in GNOME is available [on the 
wiki](https://wiki.gnome.org/Initiatives/OnlineServicesAPIKeys).
+
+## Google
+
+### OAuth 2.0
+
+- https://developers.google.com/accounts/docs/OAuth2InstalledApp
+- https://developers.google.com/apis-explorer/
+- https://developers.google.com/oauthplayground/
+
+### Scopes
+
+- https://developers.google.com/accounts/docs/OAuth2Login
+- https://developers.google.com/google-apps/calendar/auth
+- https://developers.google.com/google-apps/contacts/v3/
+- https://developers.google.com/drive/web/scopes
+- https://developers.google.com/google-apps/gmail/oauth_protocol
+- https://developers.google.com/picasa-web/docs/2.0/developers_guide_protocol
+- https://developers.google.com/talk/jep_extensions/oauth
+- https://developers.google.com/cloud-print/docs/devguide
+
+Sometimes the documentation is lacking. In such cases, the following can be
+useful:
+
+- https://developers.google.com/apis-explorer/
+- https://developers.google.com/oauthplayground/
+- https://discovery-check.appspot.com/
+
+### Notes
+
+We are allowed to embed the client_secret in the source code. See
+https://developers.google.com/accounts/docs/OAuth2InstalledApp#overview
+
+## Windows Live
+
+### OAuth 2.0
+
+- http://msdn.microsoft.com/en-us/library/live/hh243647.aspx
+
+### Scopes
+
+- http://msdn.microsoft.com/en-us/library/live/hh243646.aspx
+- http://blogs.office.com/b/microsoft-outlook/archive/2013/09/12/outlook-com-now-with-imap.aspx
+
+### Notes
+
+We do not need the client_secret because we are marked as a desktop or mobile
+application, and we use https://login.live.com/oauth20_desktop.srf as the
+redirect_uri.