User:01tonythomas/Hackathons/ExtensionHack

This short guide helps you to build a working extension on the Mediawiki platform. This doc is written to help run the talk on 'Developing a working Mediawiki extension in 80 minutes' talk at FOSSASIA Summit 2017, Singapore.

Workshop agenda

The short 120 minutes workshop aims at the following:

1. Installing and configuring a Mediawiki extension
2. Developing a new extension using the barebone Extension:BoilerPlate
3. Understanding a Manual:Hooks usecase, and using it to solve real life needs (like an event listener)
4. Making your extension lively by adding in notifications via Extension:Echo

You can find the original program agenda here - http://2017.fossasia.org/tracks.html#2942

We will be building an extension with the name `ArticleEditNotify` which would:

1. Notify the admins of a wiki on any edit on any of its pages.
2. Later make the notification limited to edits in the `User` namespace

Prerequisites

Its always better if you have the following things covered up/done. Please do not worry if you do not have anything setup - we can even help you from the scratch during the workshop - good luck!

Recommended

1. Attend Srishti Seth's talk http://2017.fossasia.org/tracks.html#2948 on 18th March on The Wikimedia free software community: Learn ways to get involved.
2. Attend Srishti Seth's workshop on 19th March titled 'A beginner-level workshop on how to get started with MediaWiki development' - http://2017.fossasia.org/tracks.html#2947
3. Read through How to become a MediaWiki hacker/Extension Writing Tutorial

Required Prerequisites

We can even help you out to get this done, but it would be loads better if we can have this done before the workshop! The rest of the document assumes that the participant would be using a Linux machine. The same can be done via other OS too, but we are not covering the instructions here.

1. Have LAMP stack installed in your Linux distro. You can find the instructions here for Ubuntu - https://help.ubuntu.com/community/ApacheMySQLPHP
2. Have PHPstorm or another working IDE in your machine. PHPstorm has Mediawiki extensions, which can make your development life easy. Find instructions here - https://www.jetbrains.com/help/phpstorm/2016.2/installing-and-launching.html
3. Follow Gerrit tutorial at Gerrit/Tutorial topdown until Gerrit/Tutorial#Setting up git-review. You would probably need to create accounts in gerrit.wikimedia.org/ and https://wikitech.wikimedia.org as part of the tutorials. Please also consider installing `git`, `git-review` and other packages. Uploading your SSH keys can get complicated, but its doable (we can debug this during the session as well).
4. Clone `mediawiki-core` - using the instructions at Gerrit/Tutorial#Download code using Git. This is the main Mediawiki project, and we will be later developing an extension to add to it.

Vagrant or LAMP stack ?

Well - some tutorials ask you to just setup Mediawiki development environment using vagrant, following MediaWiki-Vagrant - but you can even have similar stuff by installing LAMP stack and manual clone of project repositories. Setting up vagrant can take couple of hours and high speed internet, so just select between your best options. I would recommend LAMP stack + project clone due to the time constraint.

Developing your new extension

Now that you have your working clone of Mediawiki, we can start with the extension development. You can take a look at existing Mediawiki extensions in your install by moving over to `Special:Version`. This woud probably be at http://localhost/core/index.php/Special:Version or somewhere similar depending on where you clone it etc.

1. Clone the BoilerPlate extension by following Extension:BoilerPlate#Usage - for our reference, lets call our new extension - `ArticleEditNotify`. Rename all variables etc accordingly, and make sure it shows up with your name in Special:Version
2. Read about Mediawiki hooks at https://github.com/wikimedia/mediawiki/blob/master/docs/hooks.txt. We will be using `PageContentSaveComplete` for this demo. You can read about using the extension here Manual:Hooks#Writing an event handler. Just add the required stuff to `extension.json`, and add your event handler to ArticleEditNotify.hooks.php. You can just have `var_dump("Hello world");` there on the hook implementation function.
3. Install the Echo extension following Extension:Echo and read about Extension:Echo/Creating a new notification type - and think about where exactly to place 'EchoEvent::create' (HINT: You have your hook implementation which would run on a page edit. Placing the create-notification-code there would be the best option ?).
4. Alter your extension to react only when there is an edit in 'User' namespace.