Gaia/Email: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(→‎Sprint Demos: Set up.)
 
(48 intermediate revisions by 8 users not shown)
Line 1: Line 1:
The Email app offers access to a user's favorite email services while maintaining a client-like experience.  This app will support IMAP and (a little later) ActiveSync.  POP3 is not a priority because of its poor sync characteristics, but patches should be accepted.
== Design Specs ==


== Status ==
==== Interaction ====
* Feature Name: Gaia Email App
For the latest UX specifications, please visit:  
* Stage: Development
https://mozilla.box.com/applications
* Release Target: M3 Alpha


== Team ==
[[Gaia/Email/UX/Decisions]] - Notable UX Decisions and rationales
* UX: Casey Yee (IRC: cyee)
* Dev: Andrew Sutherland (IRC: asuth)


== Dependencies ==
==== Visual ====
* [https://wiki.mozilla.org/Gaia/Design/BuildingBlocks new building blocks page]
* [http://mozilla-b2g.github.com/Gaia-UI-Building-Blocks/ old building blocks page, fairly broken]
* Things you can look at but are not canonical; these are inputs to the building blocks / UX process:
** [http://buildingfirefoxos.com/index.html some building block proposals you can look at]
** [http://buildingfirefoxos.com/transitions.html#deeper visual demonstration of some proposed transitions]
 
== Development ==
 
The e-mail app consists of a back-end which is developed in https://github.com/mozilla-b2g/gaia-email-libs-and-more and a front-end which is developed as part of Gaia at https://github.com/mozilla-b2g/gaia/tree/master/apps/email.  The intent of separating the library from the UI is to make the back-end reusable.  The primary motivation is to allow a keyboard-friendly desktop UI to be developed against the library without trying to have a single UI trying to meet two radically different use cases.
 
To re-cap, check out these projects / repositories:
* https://github.com/mozilla-b2g/gaia
* https://github.com/mozilla-b2g/gaia-email-libs-and-more
 
== Features ==
 
See [[Gaia/Email/Features]] for a partial list of things we currently support or don't support.
 
== Implementation ==


https://wiki.mozilla.org/Gaia/Email/ActiveSync
The following pages are an attempt to describe how the e-mail implementation works without requiring you to read the block comments in the source code in order to understand. The goal is to provide context of the e-mail problem domain and our approach to dealing with it.  We are not going to go into low-level details because those can change frequently, but we will try to strike a balance by linking to the source code and its block comments.


== Use Cases ==
* [[Gaia/Email/Implementation/Limits]]: Maximum sizes of things, stuff like that.
*Tom sees email just as critical as his ability to make/receive phone calls and text messages
* [[Gaia/Email/Implementation/MailSynchronization]]: General sync strategy, how we sync IMAP, and how we sync ActiveSync.  Sadly, these are very different things because they are very different protocols.
*Tom is a Hotmail user (~40% share in Brazil) and often checks his email on his desktop computer, but wants to stay connect to his family/friends so an email client is very important to him
* [[Gaia/Email/Implementation/MessageDisplayAndAttachments]]: Plaintext mail, HTML mail, quoting, attachments!
*Tom has the ability to check if he received new messages
*Tom wants to be able to compose a new email directly from the Email app or from other Core Apps like the Contacts app
*Tom wants to be able to reply/replay all to messages as well as forward messages to his friends
*Tom uses ActiveSync with his Hotmail service, and the setup was extremely easy because all he had to do was enter his Hotmail email address and password and the Email app did all the setup for him
*Tom has the ability to mark messages as read/unread
*With ActiveSync, Tom has access to all his folders and messages moved and deleted between folders are automatically synced regardless of what client he accesses his inbox from
*Because Tom loves staying connected, he also has a 2nd email address that he has setup through his work - Tom's work supports Exchange and because the Email app also supports this protocol, by entering just his work email address and password, he is able to easily setup his account
*Tom's Email app support multiple accounts and offers his a unified inbox view of all messages from all accounts


nb: The above example used to say IMAP, but hotmail doesn't support IMAP, just POP and ActiveSync.  We are aiming for ActiveSync support.
* [[Gaia/Email/Implementation/FakeServers]]: Fake IMAP and ActiveSync servers for testing purposes.


== Requirements ==
== Standardization Efforts ==
;Gaia v1
*The Email app here offers key functionality that users would expect from existing email apps in the smartphone market today
*In the setup flow, the user has the ability to select from some of the largest global email providers/enterprise support:
**Hotmail
**Yahoo! Mail
**Gmail (Google Mail)
**Exchange (ActiveSync) support
*The user is offered the ability to just enter their email address and password and the Email app should automatically configure their settings
**The Email app should default to IMAP if the service supports it and POP3 as a back-up
**For Exchange users, the Email app should automatically detect the incoming/outgoing server settings
*The user has the ability to check their messages in their inbox and folders
**We offer 4 intervals for pulling messages - 15 mins, 30 mins, 1 hr, 4 hrs
*When composing messages, the user has the ability to compose directly from:
**The Email app by auto-filtering names from the Contacts list or by manually entering in a name
**Another Core App such as the Contacts app when selecting an email address (this is defined in the Contacts app requirements)
*In the compose view, the user has the ability to compose to the :
**'To:' field
**'Cc:' field
**'Bcc:' field
*The user has the ability to reply/reply all to messages:
**Original format preserved with the reply text above the message body
*The user has the ability to forward messages
**Original format preserved with the forwarded text above the message body
*The user has the ability to delete messages
*The user has the ability to mark messages read/unread
*The user has the ability to select multiple messages at one and perform the following actions:
**Move messages to a specific folder
**Delete messages
**Mark messages read/unread
*Email messages should appear in HTML and rich text if messages are sent in that format
**Plain text messages should default to a core font that is available in Gaia
*The user has the ability to pinch-to-zoom in on messages to improve readability
*Message body initial download should be <250kb with the option to 'download the rest of the message'
* Search
** Filters (search by)
*** To
*** From
*** Subject
*** All
** Search local folders
** Extend search onto server (IMAP)
* Settings
** Search Sub-folders
** Search Sent folders
** Search Deleted
** Search on server


;Gaia v2
* [[Gaia/Email/Standards/PushNotifications]]: We want to try and get IMAP servers to support our [[WebAPI/SimplePush]] API, which just means being able to PUT/POST a small amount of data to a URL.
*The user has the option to push email messages to their email account
*The user has the ability to select multiple messages and "forward as an attachment"
*Selecting text, copy, paste support for email messages
*The user has the ability attach photos from their Gallery app to draft email (new/reply/forward)


==Design Specs==
== QA / Filing Bugs ==
* [https://wiki.mozilla.org/images/e/ec/B2g-mail-DRAFTv3.pdf Email Application Wireframes and Flows v3 DRAFT]
* [https://wiki.mozilla.org/images/c/ce/B2g-mail-DRAFTv2.pdf Email Application Wireframes and Flows v2 DRAFT]
* [https://wiki.mozilla.org/images/f/f7/B2g-mail-DRAFTv1.pdf Email Application Wireframes v1 DRAFT]


== Milestones ==
Bugs should be filed in bugzilla.mozilla.org under the "Boot2Gecko" product and "E-Mail" component.  When filing a bug, be sure to provide the details requested in [[Gaia/Email/RequiredBugInfo]].  It's preferred if you do a search within the component first to look for any bugs that might already be filed on the problem.  Unfortunately, there are still a lot of known bugs :(


An attempt to break the v1 functionality into smaller milestones:
Resources on how to provide information for bugs:
* [[Gaia/Email/RequiredBugInfo]]: What we need to be able to properly investigate a bug.
* [[Gaia/Email/ProvidingEmailsForDebugging]]: How to provide problematic e-mails so developers can directly reproduce problems.  You can either attach the e-mails as attachments to the bug or e-mail them directly to the developers working on the bug if you are somewhat concerned about the world seeing any of the information in the e-mail (but not concerned enough that you have a problem providing it to a developer.)
* [[Gaia/Email/DebuggingTricks]]: Trying to help reproduce a problem?  Here are some tricks you can use to make your life easier.


=== Core Functionality ===
== Testing ==


{| border="1"
* Front-End Tests
|-
** live in the [https://github.com/mozilla-b2g/gaia gaia repo]
! milestone
** Tests by default run against
! details
* Back-End Tests
! est. effort
** live in the [https://github.com/mozilla-b2g/gaia-email-libs-and-more gaia-email-libs-and-more repo] (aka GELAM). For info on the tests in general, see: [[Gaia/Email/LoggestTestFramework]]
! status
** run against JS implemented fake-servers by default, but can be run against real servers as well.
|-
** contain a mixture of test types:
! Network
*** unit tests. examples: test_intl_unit.js (simple), test_folder_storage.js (complex)
| Connection loss recovery
*** higher level tests. ex: test_imap_general.js
| We need tests for connection loss during various points and the logic that makes those tests pass. Sync, mutation (no mutations dispatched), mutation (mutations dispatched).
*** end-to-end-ish tests. ex: test_compose.js (creates a message with an attachment, sends mail to itself, checks the messages and the attachment, sends a reply, etc.)
| 3 days
|-
! Accounts
|-
| account probing
| Ability to test logins for IMAP and SMTP.
|
| done
|-
| account creation
| Create an account as part of the initial setup process.
|
| done, w/back-end tests
|-
| account maintenance
| list/add/change/modify account definitions from the setup screen.  UI and tests.
| 1 day
|-
| option: Hard-coded auto-config database
| Less work than Thunderbird's autoconfig database lookup.  Just type in the popular options.  This should be a fallback or stop-gap.
| 0.5 day
|-
| option: Full manual setup (provide username, hosts, ports, crypto)
| Part of Thunderbird's autoconfig process/fallback, let the user actually enter all the relevant details rather than trying to infer them.
| 0.5 day
|-
| Thunderbird-ish autoconfiguration
| Use Thunderbird's autoconfig database and MX lookup support to port (as much as possible) Thunderbird's autoconfig.
| 3 days
|-
! Folders
|-
| folder tree list - simple
| just Inbox / Sent for the accounts, no labels/data.
|
| done w/back-end tests
|-  
| folder tree list - complex
| Need UX definition, but probably more hierarchical and with some message counts. UI and tests
| 2 days
|-
! Messages
|-
| core live query logic - IMAP no CONDSTORE
| no combined inbox, no persistence
* issue time-bounded queries to get ranges of messages, and fill-in the key message attributes: sender, flags, attachment, first line of summary without quoting magic.  text/plain bodies only.
* viewslice-ish model anchored from 'NOW'
|
| done w/back-end tests
|-
| cached/persisted/syncable query logic - IMAP
| stash our chunked results in the DB
|
| done w/back-end tests
|-
| on-demand syncing/scrolling: UI, back-end, tests
| Have scrolling or button pressing extend our time horizon when we haven't fully synchronized the folder. Unit tests are a lot of this.
| 2 days
|-
| data eviction from cache: back-end, tests
| Mark data as discardable and discard it. UIprovided by settings.
| 1 day
|-
| message flag mutation (starred, read/unread), no offline persistence, no undo, no UI
|
|
| done w/back-end tests
|-
| message flag mutation w/persistence, offline persisted, undo, no UI, tests
|
| 2 days
|-
| message flag mutation UI hookup
| single and batch mutations from the message list, single mutation from the reader.
| 1 day
|-
| message moves (same account) and deletion: offline persisted, undo, no UI, tests
| move, delete (varying by server/account: gmail just wants delete/expunge to end up in all mail, everyone else probably wants a move to a trash folder)
| 1.5 days
|-
| message moves and deletion UI hookup
| Hook the move button up to the folder picker UI, and the deletion button to its logic.
| 1 day
|-
| message moves (different accounts): offline persisted, undo, no UI
| moving a message across accounts is basically a download from A and append to B type thing, which is different from a normal move and so its own item.
| 1.5 days
|-
| Local search: back-end, tests
| Perform a local regexp search of the local contents of the folder.
| 1 day
|-
| Local search: UI, UI tests
|
| 1 day
|-
| IMAP search on server: back-end, tests, UI
| upgraded from local search
| 2 days
|-
! Message Contents
|-
| Censor and display HTML bodies
| Implement sanitization logic with cid URL transformation using [https://github.com/brianloveswords/bleach.js bleach.js]
| 3 days
|-
| message quoting detection (plaintext): back-end, tests, UI
| Quote detection logic for message display and useful summary lines. Start from Thunderbird gloda and Thunderbird Conversations logic.
| 2 days
|-
! Composition / Sending
|-
| trivial message composition/sending, no contact integration
| to/cc/bcc are just text fields, message not placed in the sent folder
|
| done
|-
| compose puts messages in sent folder
| probably just APPEND into sent, text/plain.
| 0.5 days
|-
| reply performs quoting: back-end, tests
| Top-post reply, greater-than insertion.
| 0.5 days
|-
| settings: UI, back-end
| simple settings API and UI, integrate with the account list
| 1.5 days
|-
! ActiveSync
! see https://wiki.mozilla.org/Gaia/Email/ActiveSync for details
|-
| Phase 1: WBXML Parser
|-
| Phase 2: ActiveSync core protocol
|-
| Phase 3: Simple e-mail application protocol support
|-
| Phase 3.5: Autodiscovery/autoconfig support
|-
| Phase 4: High level sync
|}


=== Extended Functionality ===
== Dependencies ==


Improvements that can be made to the core functionality. Order does not matter, although like things are clustered.  These are all great things to help out with.
(or rather, dependencies with wiki pages that tell you stuff)
 
https://wiki.mozilla.org/Gaia/Email/ActiveSync


{| border="1"
== Sprint Demos ==
|-
! milestone
! details
! effort / status
|-
| contact auto-completion in composition
| Auto-complete contacts when composing e-mails.
|-
| initiate mail composition from the contacts UI
| Is this a WebIntent, or an actual WebAPI?
|-
| easy signup using Thunderbird's autoconfiguration
| Port the Thunderbird logic: https://developer.mozilla.org/en/Thunderbird/Autoconfiguration
|-
| HTML composition
| Allow sending HTML messages
|-
| file attachments
| Allow attaching things from whatever filesystem B2G has?
|-
| take and attach picture
| Trigger the camera app to take a picture and immediately attach it.
|-
| mail signatures / signature editor
|
|-
| show in conversation view (when server-supported)
| In cases where the server can provide conversation information for cheap, for example on gmail, leverage it to be able to go from a message to its context in the list of messages in the conversation.


|}
Coming soon.


== Mail server/service compatibility ==
== Historical ==


Mail services:
* [[Gaia/Email/HistoricalReqs]]: Historial requirements and use cases that are misleading to keep on this page.
{| border="1"
! Provider !! Protocols Supported !! IMAP capability strings
|-
|Hotmail || POP, ActiveSync
|-
|Yahoo Mail, desktop access (free, outside Asia?) || none
|-
|Yahoo Mail, desktop access (free, in Asia?) || POP
|-
| [http://help.yahoo.com/l/us/yahoo/mail/yahoomail/mailplus/ Yahoo Mail Plus], desktop access ($19.99 US, £11.99 UK, ...)  || POP
|-
| Yahoo Mail, mobile access (free)
| [http://mobile.yahoo.com/mail IMAP]
|
; pre-login: CAPABILITY IMAP4rev1 ID NAMESPACE X-ID-ACLID UIDPLUS LITERAL+ CHILDREN XAPPLEPUSHSERVICE XYMHIGHESTMODSEQ AUTH=PLAIN AUTH=LOGIN AUTH=XYMCOOKIE AUTH=XYMECOOKIE AUTH=XYMCOOKIEB64 AUTH=XYMPKI
; post-login: CAPABILITY IMAP4rev1 ID NAMESPACE X-ID-ACLID UIDPLUS LITERAL+ XAPPLEPUSHSERVICE XYMHIGHESTMODSEQ MOVE


|-
== Security Review ==
| Google Mail/gmail
The security review of this app can be found [https://wiki.mozilla.org/Security/Reviews/Gaia/email here].
| IMAP (custom mapping w/[https://developers.google.com/google-apps/gmail/imap_extensions custom extensions])
|
; pre-login: CAPABILITY IMAP4rev1 UNSELECT IDLE NAMESPACE QUOTA ID XLIST CHILDREN X-GM-EXT-1 XYZZY SASL-IR AUTH=XOAUTH
|-
| fastmail.fm
| IMAP (Cyrus)
|
; pre-login: CAPABILITY IMAP4 IMAP4rev1 LITERAL+ COMPRESS=DEFLATE ACL RIGHTS=kxte QUOTA MAILBOX-REFERRALS NAMESPACE UIDPLUS NO_ATOMIC_RENAME UNSELECT CHILDREN MULTIAPPEND BINARY SORT SORT=MODSEQ THREAD=ORDEREDSUBJECT THREAD=REFERENCES ANNOTATEMORE CATENATE CONDSTORE LIST-EXTENDED WITHIN QRESYNC SCAN XLIST SPECIAL-USE CREATE-SPECIAL-USE DIGEST=SHA1 IDLE SASL-IR AUTH=PLAIN
|}

Latest revision as of 19:39, 12 November 2014

Design Specs

Interaction

For the latest UX specifications, please visit: https://mozilla.box.com/applications

Gaia/Email/UX/Decisions - Notable UX Decisions and rationales

Visual

Development

The e-mail app consists of a back-end which is developed in https://github.com/mozilla-b2g/gaia-email-libs-and-more and a front-end which is developed as part of Gaia at https://github.com/mozilla-b2g/gaia/tree/master/apps/email. The intent of separating the library from the UI is to make the back-end reusable. The primary motivation is to allow a keyboard-friendly desktop UI to be developed against the library without trying to have a single UI trying to meet two radically different use cases.

To re-cap, check out these projects / repositories:

Features

See Gaia/Email/Features for a partial list of things we currently support or don't support.

Implementation

The following pages are an attempt to describe how the e-mail implementation works without requiring you to read the block comments in the source code in order to understand. The goal is to provide context of the e-mail problem domain and our approach to dealing with it. We are not going to go into low-level details because those can change frequently, but we will try to strike a balance by linking to the source code and its block comments.

Standardization Efforts

QA / Filing Bugs

Bugs should be filed in bugzilla.mozilla.org under the "Boot2Gecko" product and "E-Mail" component. When filing a bug, be sure to provide the details requested in Gaia/Email/RequiredBugInfo. It's preferred if you do a search within the component first to look for any bugs that might already be filed on the problem. Unfortunately, there are still a lot of known bugs :(

Resources on how to provide information for bugs:

  • Gaia/Email/RequiredBugInfo: What we need to be able to properly investigate a bug.
  • Gaia/Email/ProvidingEmailsForDebugging: How to provide problematic e-mails so developers can directly reproduce problems. You can either attach the e-mails as attachments to the bug or e-mail them directly to the developers working on the bug if you are somewhat concerned about the world seeing any of the information in the e-mail (but not concerned enough that you have a problem providing it to a developer.)
  • Gaia/Email/DebuggingTricks: Trying to help reproduce a problem? Here are some tricks you can use to make your life easier.

Testing

  • Front-End Tests
    • live in the gaia repo
    • Tests by default run against
  • Back-End Tests
    • live in the gaia-email-libs-and-more repo (aka GELAM). For info on the tests in general, see: Gaia/Email/LoggestTestFramework
    • run against JS implemented fake-servers by default, but can be run against real servers as well.
    • contain a mixture of test types:
      • unit tests. examples: test_intl_unit.js (simple), test_folder_storage.js (complex)
      • higher level tests. ex: test_imap_general.js
      • end-to-end-ish tests. ex: test_compose.js (creates a message with an attachment, sends mail to itself, checks the messages and the attachment, sends a reply, etc.)

Dependencies

(or rather, dependencies with wiki pages that tell you stuff)

https://wiki.mozilla.org/Gaia/Email/ActiveSync

Sprint Demos

Coming soon.

Historical

Security Review

The security review of this app can be found here.

Retrieved from "https://wiki.allizom.org/index.php?title=Gaia/Email&oldid=1033048"