User:SamanthaNguyen/Guides/Writing an extension

The very first step
To ease this process, you will start off writing your very own extension by cloning the BoilerPlate extension. It is intended to provide a template for new extensions. This extension follows the best practices for extensions, such as using the standard directory structure and following Wikimedia's standard coding conventions. We will remove Git information from Boilerplate. In your local MediaWiki environment, run the following commands, starting from the very top to the very bottom:

After these steps, you should rename the /MyExtension folder to the name of your actual extension. After you have finished step, continue reading on!

Understanding the files
MediaWiki's directory and file structure is unique for extensions, and may contain many files you may not be familiar with yet. This section attempts to help clarify what each folder and file is meant to do. Some notes:
 * Files ending in the  file extension mean they are written in Markdown, a language for formatting plain text.
 * Files ending in the  file extension mean they are written in JSON, an open format for storing information. These are meant to be readably by humans as well as machines.
 * Files ending in the  file extension mean they are written in XML, a markup language meant for also storing information. These are meant to be readable by humans as well as machines. The XML syntax looks similar to HTML, but is not exactly the same.

Markdown and text files

 * : This file is the default file that users go to to see a summary of what the extension is about.
 * : All software hosted on Wikimedia are covered under the Code of Conduct. If your software is hosted on Wikimedia, this file must be included to explicitly denote this fact.
 * : This file contains legal information about the license this software is covered under. For an open-source extension, you must use an open-source license, such as the MIT License, GNU GPL license, or the Apache License. You can read more about licensing your software at https://choosealicense.com/. Most MediaWiki extensions use GNU GPL version 2 or later, but you are free to choose any open-source license.

.gitignore, .gitreview
These files are both related to Git, where Git is a version-control system that helps keep track of changes made in software.
 * The  file specifies which files should be ignored by Git. For the most part, you will usually not need to modify this file, and can freely ignore it.
 * The  file is a file used by Gerrit, which is the platform that Wikimedia uses to review code. Feel free to also ignore this file. You will never need to modify this file.

extension.json
This file is used by MediaWiki to allow registering an extension or skin, so that MediaWiki can load the extension or skin.

Your  file should look like this:

composer.json
The  file is a file for managing PHP packages published under Composer, a package manager for PHP. In MediaWiki, we use this file to install tools to help us lint our code to conform to the standard PHP coding conventions using Codesniffer, as well as check for executable files with MinusX.

As an extension developer, you usually don't have to worry about keeping up with the latest version for each package. When an extension is hosted in Wikimedia, a tool called Libraryupgrader will periodically update all repositories to use the latest versions of the packages.

You will need to run  when you copy the BoilerPlate extension into your own extension, as Composer allows running automated tasks that can be defined in the   file, under.

Your  file should look like this:

.phpcs.xml
This file is the configuration file used by Codesniffer. A sniff is a unit of code meant to look for code styling issues in PHP, and let the developer know how they should format their code.
 * Developers can detect code style issues automatically by running, which will automatically run PHPCS as well as MinusX.
 * Some code styling issues in PHP can be automatically fixed, which can be done by running . MinusX will also fix any issues with files that are detected to be executable.

Gruntfile.js, .eslintrc.json, .stylelintrc.json

 * is a configuration file used by Grunt, which is a tool written in JavaScript meant to help run automated tasks. It is also used to detect undocumented i18n messages, which will be discussed later.
 * is a configuration file used by ESLint, which is a tool used to detect code style issues in JavaScript files.
 * is a configuration file used by Stylelint, which is a tool used to detect code style issues in CSS and Less. (It also detects other CSS-like languages, but CSS and Less are the only types used in MediaWiki).