Change Details

Initial note: I know it is a bit early to write this proposal, but I want to get this out as early as possible to get as much feedback as possible. In the next few weeks it is possible that I could edit this proposal both in term of timeline and tasks. Please let me know you opinion on this. = Refactoring the Quiz extension for modern standards = **Name**: Cristian Baldi **Email**: cristian@baldi.me or bld.cris.96@gmail.com **IRC or IM handle(s)**: crisbal **Portfolio**: https://github.com/crisbal/ **Web Page**: http://baldi.me/ (right now a bit outdated) **Location**: Milano, Italy **Time Zone**: [[ https://www.timeanddate.com/time/zone/italy | UTC+1 ]] **Typical working hours**: it depends on the day and on the period. During school days 8AM-12PM and 6PM-10PM, otherwise 8AM-12PM and 2PM-6+PM. == Synopsis == This project will consist in **updating and upgrading** the Quiz extension to get it on par with current MediaWiki standards in term of **style**, **code quality**, **tests** and **integration**. **Possible Mentors**: @Mvolz, @Reedy == Benefits == For developers: at the current state it is definitely possible to expand the extension with new features but it is not recommended (nor easy) due to the **bad state of the extension backend**. Implementing this project is a step in the right direction in building a **solid base to allow future expansions of the extension**. For users: at the current state the extension works but it has a lot of behaviors and bugs that are not healthy for the user experience, also it does not look at all like modern extensions. Building a **more stable**, **functional** and **better looking** extension is something that in my opinion is **really needed**, especially for Wikis like Wikiversity which use this extension daily. == Deliverables == # **Separate "logic" from "view" in the backend** * Right now the code mixes the logic of the quiz (parsing of the WikiText, verification of answers) together with the visualization (generation of HTML) * Aim of this deliverable is to separate and abstract the two parts resulting in **cleaner** and **less bug-prone code**. **Smaller and more atomic methods** would be produced as a result, as well as the needed classes and data structures to abstract the problem. * This deliverable is based on improving the work done on T152293, where no major change to separation of logic/view was implemented. * Critical points: the most critical part of this deliverable would be that some part of the code are quite obscure and would require some time to understand them. * Preparational work: comment the code, understand everything. # **Improve the rendered HTML** * At the current state the extension make improper use of various HTML tags (for example tables are widely used even for non-tabular data, or paragraphs are used for non-textual content), at the same time naming conventions for classes and identifiers are not respected, resulting in a quite confusing code. * The aim of this deliverable is to refactor the HTML output of the extension to make it **modern, clear and standardized**. Although it does not seem necessary (since it won't make a difference for the final user) it does make a difference for both **semantic** reasons and **future development**. # **Improve the design of the frontend** * Right now the quizzes look like a plain and simple online form. Little to no style is applied to the elements resulting in a boring, and more important, in a not well integrated look with the MediaWiki environment. * The aim of this deliverable is to **restyle the Quiz extension** to make it follow the WikiMedia style guides, resulting in a better user experience for the final user and in a more suitable look for a MediaWiki extension. Some time would also be spent in **re-organizing the code** to fully **use ResourceLoader** and for proper **right-to-left** support. * Preparational work: investigate possible UI solutions, develop mockups, investigate ResourceLoader right-to-left functionality. # **Improve User Documentation** * Some features of the documentation are not well explained or documented at all. It is very important to provide a clear and precise documentation, especially because the people which will use this extension are not the most technical people. # **Unit test for the backend** * The backend code right now is impossible to test. Big functions, undocumented features. * This deliverable will require refactoring of the code in order to make it unit-testable (part of this, or even all of this, would be taken care of in the first deliverable) and at the same time **build unit tests with PHPUnit**. * Possible unit-tests: test for parsing, HTML generation and for the checking logic. * I know that usually you write test before the code but at the current state of the extension we can't and should not do it. # **Unit test for the frontend** * It is also important to write front end tests, to ensure that with each release we don't break compatibility and features. * This deliverable will require a clean and clear frontend code (all of this will be taken care in previous deliverables). To achieve this we would need to combine **PHPUnit with Selenium**. * Critical point: I have never used Selenium before, but GSoC is also a learning experience, so I am fine spending some time learning this new technology. * Preparational work: get familiar with Selenium and Selenium integrated with MediaWiki test suite. # **Refactor and rework frontend JavaScript code** (optional) * At this state the JavaScript code that define some interaction with the quizzes is very ugly and not really easy to understand. Instead of jQuery (which is built in into MediaWiki's Resource Loader and basically free to use in term of resources) it uses plain JavaScript (which is not bad per se) but the code a bit difficult and unpleasant to work with. Inline CSS is also applied to the elements by the scripts. * The aim of this deliverable is to rewrite the JavaScript of the extension. This will result in **cleaner code, better performance and more stable functionality**. It is, again, not really a necessary task but it must be implemented sooner or later, if we want to expand more. * This is probably the lowest priority task, that's why we are leaving this as a last feature to implement, some changes to the JS would be required in the other steps (for example changing ids and classes selectors) but nothing more. If everything goes as planned we should have not any difficulty implementing it in time. # **Don't break compatibility** * It is **extremely important to maintain compatibility with previous quiz syntax**, so no changes to the Quiz syntax would be implemented. Even if this syntax is not perfect, there is nothing we can do to change it (at least without spending crazy amount of time fixing the already present quizzes). === Milestones and Timeline === * **Community bonding period**: comment and understand the code, design mockups for the frontend (get in touch with the UI and Design teams), understand Selenium integration in MediaWiki (get in touch with some WMF core developers to understand how to best implement frontend tests), investigate ResourceLoader RTL support. * **First evaluation** (1 month in): Deliverable 1 (separation of logic and view) complete, started some work on redesign (d. 2,3). * **Second evaluation** (2 months in): redesign complete (d. 2,3), documentation complete (d. 4), started to work on unit-testing the backend (d. 5) * **Final evaluation**: unit-testing the frontend and the backend complete (d. 5,6), eventually fixed the frontend JavaScript (d. 7, only if I have time), otherwise fixed other issues that presented in the 3 months. This timeline is not final, some things might be completed faster than predicted, or some might take longer: giving time estimation is not easy; In the event that any change in the schedule happens (in a good or in a bad way) I want to define better deadlines with my mentors. == Participation == I have been using Phabricator for some time (both for WMF projects and for other projects) and I think it is a great tool to help development. I plan on using Phabricator for every decision making activity and for discussing technological/technical choices. I also have been using git for quite some time and I am pretty comfortable with the basic and advanced concepts, but I never used Gerrit before a few weeks ago. Gerrit is a powerful tool which impose a rigorous workflow, I hope I can get a clear understanding of it, as soon as possible. I have no problem in communicating via mail (or mailing lists), IRC (or even Telegram). I am also very OK with voice/video chat. I have a blog (baldi.me/blog), I don't use it often, but this is a good reason to start using it. It would be very cool to show progresses (both in the backend and in the frontend) both to technical and non-technical users. I don't plan to write a blog every day, but maybe one blog post per milestone could be good: writing blogs takes tons of time! More important would be reporting my work on Meta pages, with weekly or bi-weekly updates. I hope I can get in touch directly with my mentors and other WMF developers if the need to do so arise. In my short experience it is best to ask on Phabricator, since messages in IRC are easy to miss. == About me == I am a 20 years old student from Milano, Italy. I at attending 2nd year of a Computer Science degree at University of Milano Bicocca. Last year I was a mentor at KDE for Google Summer of Code and have been a mentor again for KDE for the past two editions of Google Code In: all of these have been very positive and learning experiences. The most important thing I learnt was that communication is crucial: you can't expect to successfully the project if you don't communicate early and often with your mentors. For one reason or another I never tried to join Google Summer of Code as a student, but right now I am ready to embrace this amazing initiative. I really believe in the concept of open source, open knowledge and open education: in the past one year and an half I was involved with [[ https://en.wikitolearn.org/Main_Page | WikiToLearn ]], a KDE subproject, an Italian (and now international) open source project (similar, but also very different, to Wikiversity) which aims to build open, free and high quality university textbooks. I really think that knowledge is what empowers the people, and I am trying my best both as a student and as a software developer to create and share as much knowledge as possible, both to my peers and to the world. In my free time I enjoy reading, cooking and tinkering with software, infrastructures and similar cool things. === Other commitments === When the coding period start I will also be attending the last week of my university classes, before having to complete a week of exams. These first weeks might be a bit slow for development, I planned for these in the schedule, but after those I will have complete freedom to work on the project for as much time as needed. == Past Experience in Open Source == As an user I have been using open source software as my primary choice since I learnt about open source. I am a full time Linux user since more than 2 years and I have also contributed in a few wikis at the best of my possibilities. As a developer I have been involved with open source development for about 4 and an half years and with programming in general for about 5 and an half. In the beginning I had no idea how commits, branches or even git worked, but I quickly learned the way. I consider myself a self taught full stack web developer, having experience both with frontend technologies (the classic HTML, CSS, Javascript but also more advanced things like build tools (gulp, webpack), CSS preprocessors (Sass), frontend engines (Vue.js)) and with backend (both in term of programming languages (PHP, Python w/ Flask, Node) and databases (MySQL, SQLite and some Redis and MongoDB)). I also know some of the more "sysadmin" stuff: I love the command line, deployment and design of infrastructures and in the past year I also learnt to love Docker, for building and shipping applications. All of my experience and my work can be seen on my GitHub projects: http://github.com/crisbal The most important project related to this GSoC proposal is probably WikiToLearn. As I said above WikiToLearn is a website which objective is to build powerful tools for user to create open source university textbooks. The project is under the KDE umbrella. I worked on this project on my free time with a few other amazing developers for the past year and an half. Here are the various repos we created: http://github.com/WikiToLearn At the core of WikiToLearn is MediaWiki (currently version 1.28) with a bunch of extensions (some of which were built in-house) to allow user to build, organize and write textbooks and university courses in an unique and powerful way. At WikiToLearn I was a full stack developer. * In the beginning I built a pywikibot (Python and HTML scraping) to interact with the Collection extension, which is also in use on every WMF wiki. A simple bot that would check for pages that were not able to be converted to PDF. Even if it was simple it began very important to our infrastructure. This gave me experience on how to work with MediaWiki's API. https://github.com/WikiToLearn/PDFCheck * After that I moved on doing some sysadmin work, I helped a more experience sysadmin write scripts and design infrastructure for the development and production instances of our wiki. Mostly using Bash and technology like Docker, I learnt how the difference services of MediaWiki interact: The scale of MediaWiki just blew me away: I could have never imagined that so many services (Parsoid, Mathoid, Restbase, OCG) were needed to make even a simple wiki work. Digging in the documentation (that sometimes was not perfect or present) I started to love (and sometimes hate :) ) these services. * At the same time I also started to work on the Collection extension. We had to implement some new features both in the frontend and in the backend (for example support for custom templates and tags in the PDF generations, as well as implementing custom tweaks). Here, I started to work with some powerful code: a lot of the time was spent understanding the code written by some of the MWF core developers. https://github.com/WikiToLearn/mw-ocg-latexer * From September 2016, over two months, I designed and developed (together with another developer) the current skin of the Wiki. Using technologies such as Sass, Gulp and of course the MediaWiki Skin PHP functions: I had tons of fun and learnt a ton, both about frontend but mostly about MediaWiki's innver working. A lot of time was spent optimizing the skin and making the website as quick as possible. https://github.com/WikiToLearn/WikiToLearnSkin or live at https://en.wikitolearn.org/Main_Page * As soon as I finished the skin I also started developing a MediaWiki extension for VisualEditor. Even if it was simple enough (just a dropdown menu that would let user choose from a list of most frequent templates used) it was definitely not easy to implement: VisualEditor is a complex software and most of the time you have to rely on existing code to understand feature, I learnt that documentation is key for future developers. https://github.com/WikiToLearn/WikiToLearnVETemplates In those year and an half many times I got in contact with MediaWiki developers via Phabricator and via IRC: it was always a positive experience. And many, many times I had to read the MediaWiki's documentation in search of an answer: the answer is out there, somewhere, you just need to find the right page. == Other info == * Before applying for GSoC I worked on these microtasks: * T152293 * It would be cool if once the Extension is working after the initial refactor, which could take care on a separate branch, we could run it on betawikiversity, so we could test changes with real life pages.

Initial note: I know it is a bit early to write this proposal, but I want to get this out as early as possible to get as much feedback as possible. In the next few weeks it is possible that I could edit this proposal both in term of timeline and tasks. Please let me know your opinion on this. = Refactoring the Quiz extension for modern standards = **Name**: Cristian Baldi **Email**: cristian@baldi.me or bld.cris.96@gmail.com **IRC or IM handle(s)**: crisbal **Portfolio**: https://github.com/crisbal/ **Web Page**: http://baldi.me/ (right now a bit outdated) **Location**: Milano, Italy **Time Zone**: [[ https://www.timeanddate.com/time/zone/italy | UTC+1 ]] **Typical working hours**: it depends on the day and on the period. During school days 8AM-12PM and 6PM-10PM, otherwise 8AM-12PM and 2PM-6+PM. == Synopsis == This project will consist in **updating and upgrading** the Quiz extension to get it on par with current MediaWiki standards in term of **style**, **code quality**, **tests** and **integration**. **Possible Mentors**: @Mvolz, @Reedy == Benefits == For developers: at the current state it is definitely possible to expand the extension with new features but it is not recommended (nor easy) due to the **bad state of the extension backend**. Implementing this project is a step in the right direction in building a **solid base to allow future expansions of the extension**. For users: at the current state the extension works but it has a lot of behaviors and bugs that are not healthy for the user experience, also it does not look at all like modern extensions. Building a **more stable**, **functional** and **better looking** extension is something that in my opinion is **really needed**, especially for Wikis like Wikiversity which use this extension daily. == Deliverables == # **Separate "logic" from "view" in the backend** * Right now the code mixes the logic of the quiz (parsing of the WikiText, verification of answers) together with the visualization (generation of HTML) * Aim of this deliverable is to separate and abstract the two parts resulting in **cleaner** and **less bug-prone code**. **Smaller and more atomic methods** would be produced as a result, as well as the needed classes and data structures to abstract the problem. * This deliverable is based on improving the work done on T152293, where no major change to separation of logic/view was implemented. * Critical points: the most critical part of this deliverable would be that some part of the code are quite obscure and would require some time to understand them. * Preparational work: comment the code, understand everything. * Related tasks: T159378 * Technical details: * Create a method for parsing WikiText and building `ParsedQuiz` and `ParsedQuestion` objects * Create a method for validating/correcting the `ParsedQuiz` against the answers provided in `$wgRequest` * Create a method for rendering the `ParsedQuiz` into HTML, according to results from the eventual correction * Fix any already existing bug during implementation # **Improve the rendered HTML** * At the current state the extension make improper use of various HTML tags (for example tables are widely used even for non-tabular data, or paragraphs are used for non-textual content), at the same time naming conventions for classes and identifiers are not respected, resulting in a quite confusing code. * The aim of this deliverable is to refactor the HTML output of the extension to make it **modern, clear and standardized**. Although it does not seem necessary (since it won't make a difference for the final user) it does make a difference for both **semantic** reasons and **future development**. * Related tasks: T159378 # **Improve the design of the frontend** * Right now the quizzes look like a plain and simple online form. Little to no style is applied to the elements resulting in a boring, and more important, in a not well integrated look with the MediaWiki environment. * The aim of this deliverable is to **restyle the Quiz extension** to make it follow the WikiMedia style guides, resulting in a better user experience for the final user and in a more suitable look for a MediaWiki extension. Some time would also be spent in **re-organizing the code** to fully **use ResourceLoader** and for proper **right-to-left** support. * Preparational work: investigate possible UI solutions, develop mockups, investigate ResourceLoader right-to-left functionality. * Related tasks: T160070, T159373 * Technical details: * Use OOjs UI (via PHP) and MediaWikiUI to build the basic interface style * Implement custom style in LESS (or plain CSS), while keeping close to WMF' style guides, for non-standard elements like the score table * Implement media queries for mobile support # **Improve User Documentation** * Some features of the documentation are not well explained or documented at all. It is very important to provide a clear and precise documentation, especially because the people which will use this extension are not the most technical people. # **Unit test for the backend** * The backend code right now is impossible to test. Big functions, undocumented features. * This deliverable will require refactoring of the code in order to make it unit-testable (part of this, or even all of this, would be taken care of in the first deliverable) and at the same time **build unit tests with PHPUnit**. * Possible unit-tests: test for parsing, HTML generation and for the checking logic. * I know that usually you write test before the code but at the current state of the extension we can't and should not do it. * Related tasks: T159691 # **Unit test for the frontend** * It is also important to write front end tests, to ensure that with each release we don't break compatibility and features. * This deliverable will require a clean and clear frontend code (all of this will be taken care in previous deliverables). To achieve this we would need to combine **PHPUnit with Selenium**. * Critical point: I have never used Selenium before, but GSoC is also a learning experience, so I am fine spending some time learning this new technology. * Preparational work: get familiar with Selenium and Selenium integrated with MediaWiki test suite. * Features to test: * Elements being shown/hidden as needed * Forms working correctly * Related tasks: T159691 # **Refactor and rework frontend JavaScript code** (optional) * At this state the JavaScript code that define some interaction with the quizzes is very ugly and not really easy to understand. Instead of jQuery (which is built in into MediaWiki's Resource Loader and basically free to use in term of resources) it uses plain JavaScript (which is not bad per se) but the code a bit difficult and unpleasant to work with. Inline CSS is also applied to the elements by the scripts. * The aim of this deliverable is to rewrite the JavaScript of the extension. This will result in **cleaner code, better performance and more stable functionality**. It is, again, not really a necessary task but it must be implemented sooner or later, if we want to expand more. * This is probably the lowest priority task, that's why we are leaving this as a last feature to implement, some changes to the JS would be required in the other steps (for example changing ids and classes selectors) but nothing more. If everything goes as planned we should have not any difficulty implementing it in time. # **Don't break compatibility** * It is **extremely important to maintain compatibility with previous quiz syntax**, so no changes to the Quiz syntax would be implemented. Even if this syntax is not perfect, there is nothing we can do to change it (at least without spending crazy amount of time fixing the already present quizzes). === Milestones and Timeline === * **Community bonding period**: comment and understand the code, design mockups for the frontend (get in touch with the UI and Design teams), understand Selenium integration in MediaWiki (get in touch with some WMF core developers to understand how to best implement frontend tests), investigate ResourceLoader RTL support. * **First evaluation** (1 month in): Deliverable 1 (separation of logic and view) complete, started some work on redesign (d. 2,3). * **Second evaluation** (2 months in): redesign complete (d. 2,3), documentation complete (d. 4), started to work on unit-testing the backend (d. 5) * **Final evaluation**: unit-testing the frontend and the backend complete (d. 5,6), eventually fixed the frontend JavaScript (d. 7, only if I have time), otherwise fixed other issues that presented in the 3 months. This timeline is not final, some things might be completed faster than predicted, or some might take longer: giving time estimation is not easy; In the event that any change in the schedule happens (in a good or in a bad way) I want to define better deadlines with my mentors. == Participation == I have been using Phabricator for some time (both for WMF projects and for other projects) and I think it is a great tool to help development. I plan on using Phabricator for every decision making activity and for discussing technological/technical choices. I also have been using git for quite some time and I am pretty comfortable with the basic and advanced concepts, but I never used Gerrit before a few weeks ago. Gerrit is a powerful tool which impose a rigorous workflow, I hope I can get a clear understanding of it, as soon as possible. I have no problem in communicating via mail (or mailing lists), IRC (or even Telegram). I am also very OK with voice/video chat. I have a blog (baldi.me/blog), I don't use it often, but this is a good reason to start using it. It would be very cool to show progresses (both in the backend and in the frontend) both to technical and non-technical users. I don't plan to write a blog every day, but maybe one blog post per milestone could be good: writing blogs takes tons of time! More important would be reporting my work on Meta pages, with weekly or bi-weekly updates. I hope I can get in touch directly with my mentors and other WMF developers if the need to do so arise. In my short experience it is best to ask on Phabricator, since messages in IRC are easy to miss. == About me == I am a 20 years old student from Milano, Italy. I at attending 2nd year of a Computer Science degree at University of Milano Bicocca. Last year I was a mentor at KDE for Google Summer of Code and have been a mentor again for KDE for the past two editions of Google Code In: all of these have been very positive and learning experiences. The most important thing I learnt was that communication is crucial: you can't expect to successfully the project if you don't communicate early and often with your mentors. For one reason or another I never tried to join Google Summer of Code as a student, but right now I am ready to embrace this amazing initiative. I really believe in the concept of open source, open knowledge and open education: in the past one year and an half I was involved with [[ https://en.wikitolearn.org/Main_Page | WikiToLearn ]], a KDE subproject, an Italian (and now international) open source project (similar, but also very different, to Wikiversity) which aims to build open, free and high quality university textbooks. I really think that knowledge is what empowers the people, and I am trying my best both as a student and as a software developer to create and share as much knowledge as possible, both to my peers and to the world. In my free time I enjoy reading, cooking and tinkering with software, infrastructures and similar cool things. === Other commitments === When the coding period start I will also be attending the last week of my university classes, before having to complete a week of exams. These first weeks might be a bit slow for development, I planned for these in the schedule, but after those I will have complete freedom to work on the project for as much time as needed. == Past Experience in Open Source == As an user I have been using open source software as my primary choice since I learnt about open source. I am a full time Linux user since more than 2 years and I have also contributed in a few wikis at the best of my possibilities. As a developer I have been involved with open source development for about 4 and an half years and with programming in general for about 5 and an half. In the beginning I had no idea how commits, branches or even git worked, but I quickly learned the way. I consider myself a self taught full stack web developer, having experience both with frontend technologies (the classic HTML, CSS, Javascript but also more advanced things like build tools (gulp, webpack), CSS preprocessors (Sass), frontend engines (Vue.js)) and with backend (both in term of programming languages (PHP, Python w/ Flask, Node) and databases (MySQL, SQLite and some Redis and MongoDB)). I also know some of the more "sysadmin" stuff: I love the command line, deployment and design of infrastructures and in the past year I also learnt to love Docker, for building and shipping applications. All of my experience and my work can be seen on my GitHub projects: http://github.com/crisbal The most important project related to this GSoC proposal is probably WikiToLearn. As I said above WikiToLearn is a website which objective is to build powerful tools for user to create open source university textbooks. The project is under the KDE umbrella. I worked on this project on my free time with a few other amazing developers for the past year and an half. Here are the various repos we created: http://github.com/WikiToLearn At the core of WikiToLearn is MediaWiki (currently version 1.28) with a bunch of extensions (some of which were built in-house) to allow user to build, organize and write textbooks and university courses in an unique and powerful way. At WikiToLearn I was a full stack developer. * In the beginning I built a pywikibot (Python and HTML scraping) to interact with the Collection extension, which is also in use on every WMF wiki. A simple bot that would check for pages that were not able to be converted to PDF. Even if it was simple it began very important to our infrastructure. This gave me experience on how to work with MediaWiki's API. https://github.com/WikiToLearn/PDFCheck * After that I moved on doing some sysadmin work, I helped a more experience sysadmin write scripts and design infrastructure for the development and production instances of our wiki. Mostly using Bash and technology like Docker, I learnt how the difference services of MediaWiki interact: The scale of MediaWiki just blew me away: I could have never imagined that so many services (Parsoid, Mathoid, Restbase, OCG) were needed to make even a simple wiki work. Digging in the documentation (that sometimes was not perfect or present) I started to love (and sometimes hate :) ) these services. * At the same time I also started to work on the Collection extension. We had to implement some new features both in the frontend and in the backend (for example support for custom templates and tags in the PDF generations, as well as implementing custom tweaks). Here, I started to work with some powerful code: a lot of the time was spent understanding the code written by some of the MWF core developers. https://github.com/WikiToLearn/mw-ocg-latexer * From September 2016, over two months, I designed and developed (together with another developer) the current skin of the Wiki. Using technologies such as Sass, Gulp and of course the MediaWiki Skin PHP functions: I had tons of fun and learnt a ton, both about frontend but mostly about MediaWiki's innver working. A lot of time was spent optimizing the skin and making the website as quick as possible. https://github.com/WikiToLearn/WikiToLearnSkin or live at https://en.wikitolearn.org/Main_Page * As soon as I finished the skin I also started developing a MediaWiki extension for VisualEditor. Even if it was simple enough (just a dropdown menu that would let user choose from a list of most frequent templates used) it was definitely not easy to implement: VisualEditor is a complex software and most of the time you have to rely on existing code to understand feature, I learnt that documentation is key for future developers. https://github.com/WikiToLearn/WikiToLearnVETemplates In those year and an half many times I got in contact with MediaWiki developers via Phabricator and via IRC: it was always a positive experience. And many, many times I had to read the MediaWiki's documentation in search of an answer: the answer is out there, somewhere, you just need to find the right page. == Other info == * Gerrit contributions: https://gerrit.wikimedia.org/r/#/q/owner:Crisbal * Before applying for GSoC I worked on these microtasks: * T152293 * It would be cool if once the Extension is working after the initial refactor, which could take care on a separate branch, we could run it on betawikiversity, so we could test changes with real life pages.

Initial note: I know it is a bit early to write this proposal, but I want to get this out as early as possible to get as much feedback as possible. In the next few weeks it is possible that I could edit this proposal both in term of timeline and tasks. Please let me know your opinion on this. = Refactoring the Quiz extension for modern standards = **Name**: Cristian Baldi **Email**: cristian@baldi.me or bld.cris.96@gmail.com **IRC or IM handle(s)**: crisbal **Portfolio**: https://github.com/crisbal/ **Web Page**: http://baldi.me/ (right now a bit outdated) **Location**: Milano, Italy **Time Zone**: [[ https://www.timeanddate.com/time/zone/italy | UTC+1 ]] **Typical working hours**: it depends on the day and on the period. During school days 8AM-12PM and 6PM-10PM, otherwise 8AM-12PM and 2PM-6+PM. == Synopsis == This project will consist in **updating and upgrading** the Quiz extension to get it on par with current MediaWiki standards in term of **style**, **code quality**, **tests** and **integration**. **Possible Mentors**: @Mvolz, @Reedy == Benefits == For developers: at the current state it is definitely possible to expand the extension with new features but it is not recommended (nor easy) due to the **bad state of the extension backend**. Implementing this project is a step in the right direction in building a **solid base to allow future expansions of the extension**. For users: at the current state the extension works but it has a lot of behaviors and bugs that are not healthy for the user experience, also it does not look at all like modern extensions. Building a **more stable**, **functional** and **better looking** extension is something that in my opinion is **really needed**, especially for Wikis like Wikiversity which use this extension daily. == Deliverables == # **Separate "logic" from "view" in the backend** * Right now the code mixes the logic of the quiz (parsing of the WikiText, verification of answers) together with the visualization (generation of HTML) * Aim of this deliverable is to separate and abstract the two parts resulting in **cleaner** and **less bug-prone code**. **Smaller and more atomic methods** would be produced as a result, as well as the needed classes and data structures to abstract the problem. * This deliverable is based on improving the work done on T152293, where no major change to separation of logic/view was implemented. * Critical points: the most critical part of this deliverable would be that some part of the code are quite obscure and would require some time to understand them. * Preparational work: comment the code, understand everything. * Related tasks: T159378 * Technical details: * Create a method for parsing WikiText and building `ParsedQuiz` and `ParsedQuestion` objects * Create a method for validating/correcting the `ParsedQuiz` against the answers provided in `$wgRequest` * Create a method for rendering the `ParsedQuiz` into HTML, according to results from the eventual correction * Fix any already existing bug during implementation # **Improve the rendered HTML** * At the current state the extension make improper use of various HTML tags (for example tables are widely used even for non-tabular data, or paragraphs are used for non-textual content), at the same time naming conventions for classes and identifiers are not respected, resulting in a quite confusing code. * The aim of this deliverable is to refactor the HTML output of the extension to make it **modern, clear and standardized**. Although it does not seem necessary (since it won't make a difference for the final user) it does make a difference for both **semantic** reasons and **future development**. * Related tasks: T159378 # **Improve the design of the frontend** * Right now the quizzes look like a plain and simple online form. Little to no style is applied to the elements resulting in a boring, and more important, in a not well integrated look with the MediaWiki environment. * The aim of this deliverable is to **restyle the Quiz extension** to make it follow the WikiMedia style guides, resulting in a better user experience for the final user and in a more suitable look for a MediaWiki extension. Some time would also be spent in **re-organizing the code** to fully **use ResourceLoader** and for proper **right-to-left** support. * Preparational work: investigate possible UI solutions, develop mockups, investigate ResourceLoader right-to-left functionality. * Related tasks: T160070, T159373 * Technical details: * Use OOjs UI (via PHP) and MediaWikiUI to build the basic interface style * Implement custom style in LESS (or plain CSS), while keeping close to WMF' style guides, for non-standard elements like the score table * Implement media queries for mobile support # **Improve User Documentation** * Some features of the documentation are not well explained or documented at all. It is very important to provide a clear and precise documentation, especially because the people which will use this extension are not the most technical people. # **Unit test for the backend** * The backend code right now is impossible to test. Big functions, undocumented features. * This deliverable will require refactoring of the code in order to make it unit-testable (part of this, or even all of this, would be taken care of in the first deliverable) and at the same time **build unit tests with PHPUnit**. * Possible unit-tests: test for parsing, HTML generation and for the checking logic. * I know that usually you write test before the code but at the current state of the extension we can't and should not do it. * Related tasks: T159691 # **Unit test for the frontend** * It is also important to write front end tests, to ensure that with each release we don't break compatibility and features. * This deliverable will require a clean and clear frontend code (all of this will be taken care in previous deliverables). To achieve this we would need to combine **PHPUnit with Selenium**. * Critical point: I have never used Selenium before, but GSoC is also a learning experience, so I am fine spending some time learning this new technology. * Preparational work: get familiar with Selenium and Selenium integrated with MediaWiki test suite. * Features to test: * Elements being shown/hidden as needed * Forms working correctly * Related tasks: T159691 # **Refactor and rework frontend JavaScript code** (optional) * At this state the JavaScript code that define some interaction with the quizzes is very ugly and not really easy to understand. Instead of jQuery (which is built in into MediaWiki's Resource Loader and basically free to use in term of resources) it uses plain JavaScript (which is not bad per se) but the code a bit difficult and unpleasant to work with. Inline CSS is also applied to the elements by the scripts. * The aim of this deliverable is to rewrite the JavaScript of the extension. This will result in **cleaner code, better performance and more stable functionality**. It is, again, not really a necessary task but it must be implemented sooner or later, if we want to expand more. * This is probably the lowest priority task, that's why we are leaving this as a last feature to implement, some changes to the JS would be required in the other steps (for example changing ids and classes selectors) but nothing more. If everything goes as planned we should have not any difficulty implementing it in time. # **Don't break compatibility** * It is **extremely important to maintain compatibility with previous quiz syntax**, so no changes to the Quiz syntax would be implemented. Even if this syntax is not perfect, there is nothing we can do to change it (at least without spending crazy amount of time fixing the already present quizzes). === Milestones and Timeline === * **Community bonding period**: comment and understand the code, design mockups for the frontend (get in touch with the UI and Design teams), understand Selenium integration in MediaWiki (get in touch with some WMF core developers to understand how to best implement frontend tests), investigate ResourceLoader RTL support. * **First evaluation** (1 month in): Deliverable 1 (separation of logic and view) complete, started some work on redesign (d. 2,3). * **Second evaluation** (2 months in): redesign complete (d. 2,3), documentation complete (d. 4), started to work on unit-testing the backend (d. 5) * **Final evaluation**: unit-testing the frontend and the backend complete (d. 5,6), eventually fixed the frontend JavaScript (d. 7, only if I have time), otherwise fixed other issues that presented in the 3 months. This timeline is not final, some things might be completed faster than predicted, or some might take longer: giving time estimation is not easy; In the event that any change in the schedule happens (in a good or in a bad way) I want to define better deadlines with my mentors. == Participation == I have been using Phabricator for some time (both for WMF projects and for other projects) and I think it is a great tool to help development. I plan on using Phabricator for every decision making activity and for discussing technological/technical choices. I also have been using git for quite some time and I am pretty comfortable with the basic and advanced concepts, but I never used Gerrit before a few weeks ago. Gerrit is a powerful tool which impose a rigorous workflow, I hope I can get a clear understanding of it, as soon as possible. I have no problem in communicating via mail (or mailing lists), IRC (or even Telegram). I am also very OK with voice/video chat. I have a blog (baldi.me/blog), I don't use it often, but this is a good reason to start using it. It would be very cool to show progresses (both in the backend and in the frontend) both to technical and non-technical users. I don't plan to write a blog every day, but maybe one blog post per milestone could be good: writing blogs takes tons of time! More important would be reporting my work on Meta pages, with weekly or bi-weekly updates. I hope I can get in touch directly with my mentors and other WMF developers if the need to do so arise. In my short experience it is best to ask on Phabricator, since messages in IRC are easy to miss. == About me == I am a 20 years old student from Milano, Italy. I at attending 2nd year of a Computer Science degree at University of Milano Bicocca. Last year I was a mentor at KDE for Google Summer of Code and have been a mentor again for KDE for the past two editions of Google Code In: all of these have been very positive and learning experiences. The most important thing I learnt was that communication is crucial: you can't expect to successfully the project if you don't communicate early and often with your mentors. For one reason or another I never tried to join Google Summer of Code as a student, but right now I am ready to embrace this amazing initiative. I really believe in the concept of open source, open knowledge and open education: in the past one year and an half I was involved with [[ https://en.wikitolearn.org/Main_Page | WikiToLearn ]], a KDE subproject, an Italian (and now international) open source project (similar, but also very different, to Wikiversity) which aims to build open, free and high quality university textbooks. I really think that knowledge is what empowers the people, and I am trying my best both as a student and as a software developer to create and share as much knowledge as possible, both to my peers and to the world. In my free time I enjoy reading, cooking and tinkering with software, infrastructures and similar cool things. === Other commitments === When the coding period start I will also be attending the last week of my university classes, before having to complete a week of exams. These first weeks might be a bit slow for development, I planned for these in the schedule, but after those I will have complete freedom to work on the project for as much time as needed. == Past Experience in Open Source == As an user I have been using open source software as my primary choice since I learnt about open source. I am a full time Linux user since more than 2 years and I have also contributed in a few wikis at the best of my possibilities. As a developer I have been involved with open source development for about 4 and an half years and with programming in general for about 5 and an half. In the beginning I had no idea how commits, branches or even git worked, but I quickly learned the way. I consider myself a self taught full stack web developer, having experience both with frontend technologies (the classic HTML, CSS, Javascript but also more advanced things like build tools (gulp, webpack), CSS preprocessors (Sass), frontend engines (Vue.js)) and with backend (both in term of programming languages (PHP, Python w/ Flask, Node) and databases (MySQL, SQLite and some Redis and MongoDB)). I also know some of the more "sysadmin" stuff: I love the command line, deployment and design of infrastructures and in the past year I also learnt to love Docker, for building and shipping applications. All of my experience and my work can be seen on my GitHub projects: http://github.com/crisbal The most important project related to this GSoC proposal is probably WikiToLearn. As I said above WikiToLearn is a website which objective is to build powerful tools for user to create open source university textbooks. The project is under the KDE umbrella. I worked on this project on my free time with a few other amazing developers for the past year and an half. Here are the various repos we created: http://github.com/WikiToLearn At the core of WikiToLearn is MediaWiki (currently version 1.28) with a bunch of extensions (some of which were built in-house) to allow user to build, organize and write textbooks and university courses in an unique and powerful way. At WikiToLearn I was a full stack developer. * In the beginning I built a pywikibot (Python and HTML scraping) to interact with the Collection extension, which is also in use on every WMF wiki. A simple bot that would check for pages that were not able to be converted to PDF. Even if it was simple it began very important to our infrastructure. This gave me experience on how to work with MediaWiki's API. https://github.com/WikiToLearn/PDFCheck * After that I moved on doing some sysadmin work, I helped a more experience sysadmin write scripts and design infrastructure for the development and production instances of our wiki. Mostly using Bash and technology like Docker, I learnt how the difference services of MediaWiki interact: The scale of MediaWiki just blew me away: I could have never imagined that so many services (Parsoid, Mathoid, Restbase, OCG) were needed to make even a simple wiki work. Digging in the documentation (that sometimes was not perfect or present) I started to love (and sometimes hate :) ) these services. * At the same time I also started to work on the Collection extension. We had to implement some new features both in the frontend and in the backend (for example support for custom templates and tags in the PDF generations, as well as implementing custom tweaks). Here, I started to work with some powerful code: a lot of the time was spent understanding the code written by some of the MWF core developers. https://github.com/WikiToLearn/mw-ocg-latexer * From September 2016, over two months, I designed and developed (together with another developer) the current skin of the Wiki. Using technologies such as Sass, Gulp and of course the MediaWiki Skin PHP functions: I had tons of fun and learnt a ton, both about frontend but mostly about MediaWiki's innver working. A lot of time was spent optimizing the skin and making the website as quick as possible. https://github.com/WikiToLearn/WikiToLearnSkin or live at https://en.wikitolearn.org/Main_Page * As soon as I finished the skin I also started developing a MediaWiki extension for VisualEditor. Even if it was simple enough (just a dropdown menu that would let user choose from a list of most frequent templates used) it was definitely not easy to implement: VisualEditor is a complex software and most of the time you have to rely on existing code to understand feature, I learnt that documentation is key for future developers. https://github.com/WikiToLearn/WikiToLearnVETemplates In those year and an half many times I got in contact with MediaWiki developers via Phabricator and via IRC: it was always a positive experience. And many, many times I had to read the MediaWiki's documentation in search of an answer: the answer is out there, somewhere, you just need to find the right page. == Other info == * Gerrit contributions: https://gerrit.wikimedia.org/r/#/q/owner:Crisbal * Before applying for GSoC I worked on these microtasks: * T152293 * It would be cool if once the Extension is working after the initial refactor, which could take care on a separate branch, we could run it on betawikiversity, so we could test changes with real life pages.