==Project
====Possible Mentors
- Primary Mentor: @Parent5446
- Co-mentor: @01tonythomas
====Synopsis
HTML emails have a lot of advantages over plain text emails; being responsive to screen size and supporting fonts other than monospace (difficult to read for dyslexics) are some of the many [[https://lists.wikimedia.org/pipermail/foundation-l/2011-April/065375.html | pointed out]] by Tim Starling. In the same email, another serious issue he points out is that plain-text does not work well with bidirectional languages, since plain-text just follows visual order. In addition, certain clients fail to correctly identify links in plaintext, leading to serious inconvenience for the users.
Given the fact that MediaWiki has a very large and diverse user base, these issues really ought to be taken care of - there is no reason to continue using only plain-text emails given the benefits of HTML emails.
As of now, MediaWiki has support only for plain text email. A few extensions (such as Echo) have their own mechanism for sending out HTML emails, but core as such does not, which means any mails that core sends (such as change notification emails) cannot be sent as HTML Emails. This project plans to implement this functionality in MediaWiki's core.
====Prior Art
MediaWiki’s core already has a provision for sending HTML email, as long as one is being provided to it. Some extensions using it are:
- [[https://www.mediawiki.org/wiki/Extension:Echo | Extension:Echo]] - This extension already has HTML email support implemented. Once core has support for this, the extensions can use it instead of writing their own.
- [[https://www.mediawiki.org/wiki/Extension:EmailPage | Extension:EmailPage]] - This extension sends rendered HTML pages to email addresses using PHP Mailer. This is different from what we want to do, as we do not want to be email wiki pages, we wish to convert a given text email into an html email.
- Patches - Some [[https://gerrit.wikimedia.org/r/#/q/owner:%22VitaliyFilippov+%253Cvitalif%2540yourcmc.ru%253E%22+bug:15303,n,z | patches]] have been submitted trying to implement support for HTML email. We should probably be working with these and extending them.
====Phases
Note: Testing and review will be done as and when the phases are being developed.
- **Phase I** : The MVP
- Feed text coming from wfMessage as is, i.e., assume the text given has no HTML tags in it.
- Implement very basic plain text to HTML conversions:
- Use nl2br to convert newlines to `<br/>` tags
- Include links in `<a>` tags. Account for links being in brackets (`()`), in quotes (`‘’` or `“”`) and any other format that we find people tend to mention links in plain text.
- In order to reduce redundancy and allowing extensions to reuse/alter their existing HTML email support, a new global `$wgCoreHTMLEmail` could be added to allow Wiki Administrators to send plain text emails if they want to (send plain text email if $wgCoreHTMLEmail is set to false, and send multipart email if it is true) , besides $wgAllowHTMLEmail, which decides whether the Wiki allows anybody (core or extension) to send an HTML Email. To explain the different cases more clearly,
- if (`$wgAllowHTMLEmail == false`) only plain text emails go
- if (`$wgAllowHTMLEmail == true and $wgCoreHTMLEmail == false`) Anybody *except core* can send an HTML email.
- if (`$wgAllowHTMLEmail == true and $wgCoreHTMLEmail == true`) Everybody can and core *will* send an HTML email.
- The server will send emails to the client depending upon user preferences:
- The user will be given a “Receive plain text email only” option in Special:Preferences. When this is ticked, the server will send only plain text emails to that specific user.
- When the above option is unticked, the server will send a multipart email (both HTML and plain text) when both $wgAllowHTMLEmail and $wgCoreHTMLEmail are set to true.
- **Phase II** : Preliminary styling
- Integrate [[http://foundation.zurb.com/emails/email-templates.html | templates from Zurb Foundation]], decide on which ones to keep, which ones to leave.
- Include branding of any kind that might be required
- Add the official MediaWiki logo at the beginning of the mail.
- A default sign-off message, perhaps.
- Ask community for design suggestions, something like a wish-list
- **Phase III** : Wish-list and translations
Some alternative implementations might exist that achieve what I am trying to in a better way. I will take some time to look around for those. For now, my proposed solution for translations is as follows:
- When generating a key to be passed to wfMessage(), it will be assumed that if the key does not end with `-html`, the text is wikitext/plaintext. If the caller of the function wishes to include html in the text, the key must be appended by `-html`.
- When the key sent ends with `-html`, we can run `wfMessage($key)->exists()` on it, and if it does not exist, we can use the key without the ending `-html`, assuming that version exists. This will be done so that even if an html version of the text exists and the caller wants to use the plaintext version, they have an option to do so. This will require discussion with the i18n team. Allowing arbitrary HTML in the messages will have security concerns that will need to be looked into and taken care of.
- I will try to implement the necessary features that come up on the wish-list, and any other features that may be very useful, if time permits.
- **Phase IV** : Wrap-up
- Robust testing, to see if any possibility of a security breach has not been accounted for.
- Create/Edit the required documentation pages for this functionality.
- Announce the introduction of the functionality on `wikitech-l` mailing list.
===Deliverables
- **The MVP**: Ability to be able to send plain text as an HTML email with minimal conversions of plaintext to HTML. (Phase I)
- **Tests and Patches**: They will be submitted on gerrit, and will be available for review and testing to the community.
- **Documentation**: Explaining in detail how the functionality is to be used, in terms of variables, functions and classes.
====Timeline
| **Time Period** | **Task(s)**
|--------------------|--------------
| Apr 22 - May 23 | Community Bonding Period. Go through existing art and decide structure of the source code.
| **Weeks 1, 2, 3** (May 23 - Jun 13) | Work on and finish the MVP (inclusive of the tests) and finalise decisions with regard to the structure of the functionality (methods, classes, global variables, etc). Begin to gather a community wishlist. (Phase I)
| **Week 4, 5** (Jun 14 - Jun 27) | Discussing and integrating templates agreed upon, and gathering community review on them. (Phase II)
| **Week 6, 7** (Jun 28 - Jul 12) | Get community review and design team suggestions on branding of the email, and look at any other possibly better templates. (Phase II)
| **Weeks 8, 9** (Jul 13 - Jul 26) | Work on translation of content, discuss the best solutions for our scenario with the i18n team. Security loop-holes created by allowing HTML in the text provided will be worked on fixed. (Phase III)
| **Weeks 10, 11** ( Jul 27 - Aug 9) | Robust testing, security review, work on refactoring the code to make it better and more efficient. (Phase IV)
| **Weeks 12, 13 **( Aug 10 - Aug 23) | Fix minor issues, file bugs. Complete documentation wikipages. Send mail on wikitech-l announcing the functionality. (Phase IV)
==Profile
**Name:** Smriti Singh
**Email:** smritis.31095@gmail.com
**IRC handle (freenode):** galorefitz
**Internet Presence** : [[https://www.mediawiki.org/wiki/User:Galorefitz | MediaWiki user page]]
**Location:**
I'll be visiting 2 places this summer, India (+05:30 GMT), and Kuwait (+03:00 GMT)
**Typical Working Hours:**
1. **May-July**: 6-8 hours a day, between 6:30 a.m - 8:30 p.m (GMT) (at least 40 hours a week)
2. **August** : 5-6 hours a day, between 3:30 a.m - 11:30 p.m (GMT) (at least 40 hours a week)
====Communication
I will be submitting reports weekly on a phabricator task, tracking the progress of the project, on Phabricator. I will be available on `#wikimedia-dev` and `#wikimedia-tech` on IRC (freenode) during my working hours, so I can be reached there. I will also be responding on the relevant phabricator tasks. The source code will be pushed to Gerrit, and will be accessible, viewable and reviewable there.
====Contributions
Microtasks: T31856 T48109
My contributions to the community can be viewed [[https://gerrit.wikimedia.org/r/#/q/owner%3A%22Galorefitz%22,n,z | here]] and [[https://phabricator.wikimedia.org/p/Galorefitz/ | here]]. I haven't contributed to any other FOSS organisations yet, but plan to in the future.
====About Me
**Education:** In progress. I am a Computer Science Student (currently in my third year), studying at the International Institute of Information Technology (IIIT), Hyderabad, India.
**How did you hear about this program?** From senior year students in college.
**Why MediaWiki?** I started contributing to MediaWiki in May, 2015. The people here were quick to respond, very encouraging, and amazingly helpful. Contributing, seeing my work make a difference to the community, felt great. Not many communities have all of the above, and this is what encouraged me to choose MediaWiki.
**Why this project?** HTML emails have a lot of advantages over plain text emails; being responsive to screen size, supporting fonts other than monospace (difficult to read for dyslexics), supports bidirectional languages, unlike plaintext, which only supports visual order. Certain clients fail to correctly identify links in plaintext, leading to serious inconvenience for the users. Given the fact that MediaWiki has a very large and diverse user base, these issues really ought to be taken care of - there is no reason to continue using only plain-text emails given the benefits of HTML emails.
===Additional Information (as mandated by [[https://wiki.gnome.org/Outreachy#Application_Form | Gnome]])
**Do you meet the eligibility requirements outlined [[https://wiki.gnome.org/Outreachy#Eligibility | here]]** ? - Yes.
**Preferred pronoun** - she
**Prior Commitments** -
May-July, 2016 : None.
11th August, 2016 - 23rd August, 2016 : College, will take approximately 25 hours a week
**Course details**
From 11th August, 2016 - 23rd August, 2016 : My college has a system of electives for every semester, and so I am not sure right now what courses I’ll be taking and how many credits they’ll be. The total number of credits, though, 16 (normal, full-time course load is of 20-24 credits). For more information, please refer to https://www.iiit.ac.in/academics/curriculum/undergraduate/BTech-CSE (Year IV, Semester I)