Implement HTML e-mail support in MediaWiki
Name: Perside Mondjo Rosalie
Working Hours: I plan to spend 40 hours a week in my Outreach 2016 project and my intended start date to end date is from: May 23 - August 23, 2016. Working hours will be from 11:00pm – 5:00am (GMT + 01) Central Africa Time Zone
Due to the advancement of technology and also the rate at which people(developers, users and more ...) communicate using emails online, there is the need for various formats of email support to be used in communication to enhance and better the information transmitted from source to destination. Email supports are the forms that emails can take before, during or after transmission and all formats have their advantages and disadvantages.
Most popularly, there exist;
- HTML email support and
- Text Emails support
In addition to the two listed above, from research I have done, I found out a bunch of other email formats used and a few are listed below;
- MIME (Multipurpose Internet Mail Extensions) format: which is an email support to handle attachment like; sounds, pictures. So this is just a merge of both RTF(plain text) email support and HTML email support. I will really like to implement this email support for MediaWiki after Outreachy if they accept to use this email format.
Email Format Types that exist and their descriptions.
Currently, MediaWiki has the Text support for emails where information is transmitted in the form of plain text and no styles are applied to such emails and my project is to build an HTML email support. On the users perspective, the HTML email supports is really friendly and enables emails to be well formatted such that information with specificity will be conveyed correctly like; source codes, commands and more.... Using the HTML email support, emails sent form source to destination will be styled in a nicer way for users to easily interpret the meaning of the message and isolate particular parts of the message if need be. Also, HTML emails make a big difference with RTL languages. Since HTML uses the (LTR, RTL) as its base directions for text, it is easier to double check and make sure everything is marked up. So this multi-directional or directional(bidi) way makes HTML better than RTL languages.
This article is interesting and also list some advantages for email support: https://www.campaignmonitor.com/blog/email-marketing/2007/09/why-we-need-web-standards-supp-1/
Experience with MediaWiki
So far, I can say MediaWiki is my first Open source organisation that i have seen that gives a lot of help to their developers and those who are willing to contribute. Also, I like MediaWiki because of the fact that it is a platform that powers free information sharing technologies and also their coding style is clean enough to new comers in the community.
List of what I have done;
- Set up my development environment(MediaWiki code base) and also some extensions
- Created a phabricator account and phabricator sub-task (my project proposal).
- Created a MediaWiki unified account.
- Own a Gerrit(developer access) account for code review and bug fixes.
- Worked with the CentralNotice extension and fixed a bug.
- Reported a bug i found in the Math extension.
Available for Communication
Like i briefly mention in my personal information section, I will make sure to spend at least 40 hours on my project every week and i will mostly working in the above mentioned time. But since there are some days that can be favorable, I might spend more than 7 hours working on my project and will make sure to stay online all the time even if i'm not on my computer so I can read the logs when i get back on my screen.
For other commitments, i don't think i will have any other activities that will disturb me during the program because since i work during the night and in the day, i do all my activities, i don't think there will be any interference. Also for holidays and/or vacation, there isn't anyone that i am going to, so i will only be in the house concentrating every night till the project and program is over.
In addition to this, I will make sure to always have meeting everyday with my mentors and say in touch with them from time to time through email, irc channel during this program. Also, I will make sure to respect time for meetings and deliver the tasks for everyday as mentioned in my timeline. Reporting too is a major key to update my mentors on what I have done weekly. I will make sure i submit weekly reports so that they can be up to speed on what has been done for the whole week.
Project Time Line
Once selected on this project, it is certain that I will focus on it till the program is over i.e. 23 August 2016(end of Outreach Round 12).
Brief Time Line with milestones and duration
|Tasks||Period in days (Duration)||Milestone||Deliverable|
|Prerequisite Work||May 23 - May 30||Familiar with implementation of existing email supports in MediaWiki||Knowledge about Emails in MediaWiki and familiar with the current email support implementation|
|Week 1 (Start Coding and fix existing patches)||May 31 - June 6||Choice of Email option used are set, Preference configuration and Server side configuration. Fix existing HTML email patches that exist and it should be merged.||Email Support Config available for users. Merged existing patches for HTML email.|
|Week 2 (Template building)||June 7 - June 14||HTML templates built and global variables set to hold the configurations in week 1, templates tested and bugs fixed, weekly report.||HTML email templates and weekly report|
|Week 3 (Template building continues, testing||June 15 - June 22||Templates tested, i18n applied in the templates, building of templates continues, weekly report.||HTML email templates and weekly report.|
|Week 4 - Week 6 (Testing, Bug fix, work continues)||June 23 - July 7||Set of templates working as planned, tested templates which are bug free, initial codes on Gerrit, Week report.||Source codes on gerrit, Tested email templates, bug free templates.|
|Week 7 - Week 12 ( Final Coding and Documentation)||July 8 - August 22||Updating codes on gerrit, templates added, Logic improved, bugs fixed, Manual or Documentation written, Final report for project .||HTML Email support complete, Manual/Documentation, Final project report.|
Below is the full timeline with detailed explanation of the sub-tasks above and weekly report also submitted. This table explains the brief tabulated timeline above.
At this point, the coding for the program has not yet began but I will have to do some research and information gathering to make sure that I have all what I need to kick start with implementing the project once the program officially begins.
During this period, I'll be thinking and designing the following issues;
- Design for the HTML email template that various emails for MediaWiki will take like; reset password email, welcome to MediaWiki email, confirm account emails, etc..
- Since HTML emails is all about inline styling, I will make sure me and the mentors decide on the way we will design the editor / parser that will read the emails and format it for HTML support mode. But if HTML support option is enabled, then the parser will read the email and format it in the appropriate way.
- In an online editor like in phabricator, there are tools in the editor used to edit text, once these tools are used, it will be parsed and formatted to the correct HTML message before send.
- With reference to what Mattflaschen said, I will have a discussion whether to extend the Echo extension that already has HTML email support(avoid redundancy) or come up with a new extension to handle HTML emails or just integrate HTML email support into the MediaWiki core. Either ways are still ok but the best will be decided and used for this project.
- Read documentation about the previously implemented text email support here:
- Other more information i will get from Googling concerning this project, i will also make sure i go through.
First and far most, there exist HTML emails patches submitted by other developers in MediaWiki. As discussed with the mentors, it has been agreed to first fix and work on the existing HTML email patches that have been submitted. If there are any bugs, we have them fixed and the code merge and expand on the code rather than to start coding from scratch. This task (T15303) already has a patch that was submitted by VitaliyFilippov and some other related patches. Once this is done, I can then move forward to implement the rest of the project.
Read about the already implemented email support core, I have to make sure I keep the initial implementation of the mailing support that already exist so far. Also, I will use both option (b) and (c) for implementing the HTML email support as mention in the project description. HTML email support in MediaWiki to be in the following approaches.
- There should be an Option to set the use of HTML support in the preference area by the user and also another option to set it back to default, so something like two mutually exclusive radio buttons to choose the options.
- Server side configuration whether to send HTML emails or Text emails based on the users Internet connection(advanced idea) or by default. Here, if the internet is very slow(rate of data transfer) i the server will use text email mode but if the rate of data transfer is high, HTML email is used
At the end of this week, I will have to submit a report for the work done.
- Start building the HTML email templates for each of the email alerts that shall be used in MediaWiki, based on what me and my mentors we decide, if we decide to use the same design for all emails, then I shall just modify the content of the design based on the parameters sent to it, else I will need to build different email template for different emails. Also the templates will be very user friendly
- Also, I will add some global variables in the DefaultSettings.php file in the include/ folder of MediaWiki to hold the mode of email support. By default, email will be text and if HTML email is set, then the variables will be check before the HTML emails will be sent or plain text depending on its value. Variable would be
$wgDefaultUserOptions['htmlemail'], and it shall have two values,
- $wgDefaultUserOptions['htmlemail'] = 0; default for using plain text emails
- $wgDefaultUserOptions['htmlemail'] = 1; will be the value to use HTML emails.
This is a preference variable, so it will be the one to use.
- Unit testing and regression testing will be done for all the templates designed and work done for each week.
- Submit a weekly report to the mentors.
Continue with the implementation of the email templates and make sure that if an editor(wiki editor like VisualEditor) is used to write the emails, based on the content of the email, processing the email content by using a parser(Parsoid) to get the email content(wiki text) with predefined formatting to be converted to HTML format. For example, ` some code ` will mean <code> some code </code> in HTML. So this will enable people to know the syntax used for the email conversion, Parsoid will really be useful at this point.
So, writing the message in the editor, the parser will take the message and interpret it, translating everything required for translation and then putting it in the right template and HTML format before sending.
- Unit testing and regression testing will be done for the work done.
- Weekly report submitted to the mentors.
Week 4 to Week 6
- Unit testing, Regression testing, Integration testing(each week after a sub-mileston) and fixing of bug for the entire templates and translation(i18n for general text on the templates) of the message. At this level, I will have to push some codes to my branch online so that my mentors can see the work I have been doing so far.
- Continue working on the templates to make it perfect and also fix some bugs if found in the templates.
- Submit reports for each weeks, starting from week 4 to week 13(weekly report for each week).
Week 7 to Week 12
- Make the emails responsive and the same for all browsers. At least for the most popular, Google Chrome, Mozilla Firefox, Safari, IE10 etcc...
- Integrate the existing emails on the HTML support mode so that confirmation email, reset password email and other existing emails will benefit from the HTML support.
- Continue testing and fixing bugs to make sure everything works properly and continue implementation on the templates.
- Submit Final Outreachy report and submit at the end of the program.
Accomplishment of the Project
This project is to accomplish the task of MediaWiki having an HTML email support. This project will be integrated in MediaWiki in such a way that when a MediaWiki user has an account, based on the implementation of the choice we choose above, then we shall have the following results.
- If the user's configuration for HTML email support is set to true, then he/she can send emails using HTML support else he/she will use the default which is Text emails.
But generally, this project aims at making MediaWiki have HTML email support.
I was so convicted within and was not happy that with all these skills, I have not contributed to a real live project and I heard about Open Source communities, and decided to give it a try. I found this organisation matching my skill set in what they do so i decided to contribute code for them by participating in the Outreach Round 12 program.
For more information about me, check out my mediawiki About me page
Being in MediaWiki is really cool and the rate at which I saw other developers contributing to the code makes me really motivated and made me to work like them too. Below is a list of my submitted patches for both extensions and the wiki core.
- Bug: T72462 | Patch Set: https://gerrit.wikimedia.org/r/#/c/247990/ (Merged)
- Bug: T106247 | Patch Set: https://gerrit.wikimedia.org/r/#/c/248803/ (Merged)
- Bug: T68673 | Patch Set: https://gerrit.wikimedia.org/r/#/c/273228/ (Merged)
- Bug: T41266 | Patch Set: https://gerrit.wikimedia.org/r/#/c/248612/ (In Review)
- T116351 ( Confirmed )