Licença (em inglês)

MediaWiki is an open-source project and users are encouraged to make any MediaWiki extensions under an Open Source Initiative (OSI) approved license compatible with GPL-2.0-or-later (Wikimedia's standard software license).

We recommend adopting one of the following compatible licenses for your projects in Gerrit:

• GNU General Public License, version 2 or later (GPL-2.0-or-later)
• MIT License (MIT)
• BSD License (BSD-3-Clause)
• Apache License 2.0 (Apache-2.0)

For extensions that have a compatible license, you can request developer access to the MediaWiki source repositories for extensions. To specify the licence in code and with "license-name" a key should be used to provide its short name, e.g. "GPL-2.0-or-later" or "MIT" adhering to the list of identifiers at spdx.org.

Tornando sua extensão configurável pelos usuários

wfLoadExtension( 'MyExtension' );

Se você deseja fazer com que sua extensão seja configurável pelos usuários, será necessário definir e documentar alguns parâmetros de configuração. A configuração dos seus usuários deve estar desta maneira:

wfLoadExtension( 'MyExtension' );
$wgMyExtensionConfigThis = 1;
$wgMyExtensionConfigThat = false;

Caso queira que os usuários possam configurar sua extensão, será necessário fornecer uma ou mais variáveis de configuração. É uma boa ideia dar um nome único para cada variável. Também devem ser seguidas as convenções para nomes do MediaWiki (p. ex.: variáveis globais devem começar com $wg).

Por exemplo, se sua extensão se chamar MinhaExtensao, tente nomear todas as suas variáveis de configuração para começarem com $wgMinhaExtensao. É importante que nenhuma outra extensão do núcleo do MediaWiki comece as variáveis da mesma maneira que a sua, e que você tenha feito um bom trabalho em verificar se nenhuma das extensões publicadas comecem suas variáveis da mesma maneira. Os usuários não ficarão tão felizes em ter de escolher entre a sua e outras extensões pelo fato de você ter usado os mesmos nomes que as outras.

Uma outra boa ideia é incluir uma documentação completa de quaisquer variáveis de configuração nas suas notas de instalação.

{
	"config": {
		"BoilerPlateEnableFoo": {
			"value": true,
			"description": "Enables the foo functionality"
		}
	}
}

Observe que após chamar wfLoadExtension( 'BoilerPlate' );, a variável global $wgBoilerPlateEnableFoo não existe. Se a variável for definida em algum lugar —como o LocalSettings.php—, o valor padrão contido no extension.json não será utilizado.

Para mais detalhes sobre como utilizar uma variável global dentro de extensões personalizadas, consulte Configuration for developers .

Preparando classes para o carregamento automático

Caso escolha ter de usar classes para implementar sua extensão, o MediaWiki fornece um mecanismo simplificado para auxiliar o PHP em encontrar o arquivo-fonte onde sua classe está localizada. Na maioria dos casos, isso deverá eliminar a necessidade de escrever seu próprio método __autoload($classname).

Para usar o mecanismo de carregamento automático do MediaWiki, adicione algo ao campo AutoloadClasses . A chave para cada adição é o nome da classe; o valor é o arquivo armazenador da definição da classe. Para uma extensão de uma só classe, a classe tem geralmente o mesmo nome que a extensão. Dessa maneira, sua seção de carregamento automático deve parecer assim (nesse exemplo, a extensão se chama MyExtension):

{
	"AutoloadClasses": {
		"MyExtension": "includes/MyExtension.php"
	}
}

O nome do arquivo é relativo ao diretório onde se encontra o arquivo extension.json.

Para extensões mais completas, considere namespaces do PHP. Veja Manual:Extension.json/Schema#AutoloadNamespaces para mais detalhes.

Lidando com dependências

Imagine que uma extensão necessita da existência de uma outra, talvez por causa das funcionalidades ou tabelas de banco de dados criadas por essa outra, e que determinadas mensagens de erro não precisem aparecer caso essa outra não esteja instalada.

Podemos pegar como exemplo a extensão CountingMarker , que requer a presença da extensão HitCounters para realizar determinadas funções.

Uma forma de especificar essa dependência é através da chave requires no extension.json .

	if ( ExtensionRegistry::getInstance()->isLoaded( 'HitCounters', '>=1.1' ) {
		/* do some extra stuff, if extension HitCounters is present in version 1.1 and above */
	}

Currently (as of February 2024, MediaWiki 1.41.0) the name of the extension-to-be-checked needs to exactly match the name in their extension.json.^[2][3]

Example: if you want to check the load status of extension OpenIDConnect, you have to use it with a space

	if ( ExtensionRegistry::getInstance()->isLoaded( 'OpenID Connect' ) {
    ...
	}

Adicionando tabelas de bancos de dados

Certifique-se de que a extensão não modificará as tabelas de banco de dados do núcleo. Em vez disso, a extensão deverá criar novas tabelas contendo chaves estrangeiras (foreign keys) às tabelas do MediaWiki relevantes.

Atenção:

Se sua extensão for usada em alguma wiki mantida pela WMF, siga o Guia de mudança de esquema (em inglês).

Se sua extensão precisar adicionar suas próprias tabelas de bancos de dados, use o hook LoadExtensionSchemaUpdates . Veja a página do manual para mais informações de uso.

Attributes allow extensions to register something, such as a module, with another extension. For example, extensions can use attributes to register a plugin module with the VisualEditor extension. For more information, see Registro de extensões .

Armazenando mensagens em <chave-idioma>.json

Armazene as definições de mensagens em arquivos de localização JSON, um para cada chave de idioma em que sua extensão será traduzida. As mensagens serão salvas com uma chave de mensagem e a própria mensagem, usando o formato padrão JSON. Todo ID de mensagem deve estar em letras minúsculas e sem espaços. Cada chave deve começar com o nome da extensão em letras minúsculas. Um exemplo pode ser encontrado na extensão MobileFrontend. Aqui está um exemplo de um arquivo JSON mínimo (neste caso, en.json):

en.json

{
	"myextension-desc": "Adds the MyExtension great functionality.",
	"myextension-action-message": "This is a test message"
}

Armazenando a documentação das mensagens em qqq.json

A documentação das chaves das mensagens pode ser armazenada num arquivo JSON com o código qqq. Uma documentação do exemplo acima pode ser:

qqq.json:

{
	"myextension-desc": "The description of MyExtension used in Extension credits.",
	"myextension-action-message": "Adds 'message' after 'action' triggered by user."
}

Carregando o arquivo de localização

Na sua extension.json, defina a localização dos seus arquivos de mensagem (p. ex. no diretório i18n/):

{
	"MessagesDirs": {
		"MyExtension": [
			"i18n"
		]
	}
}

Usando wfMessage no PHP

No seu código de configuração e implementação, substitua todo uso da mensagem com uma chamada para wfMessage( $msgID, $param1, $param2, ... ). Em classes que implementam a IContextSource (assim como algumas subclasses das páginas especiais, por exemplo), pode-se usar $this->msg( $msgID, $param1, $param2, ... ). Exemplo:

wfMessage( 'myextension-addition', '1', '2', '3' )->parse()

Usando mw.message no JavaScript

Também é possível usar funções de i18n no JavaScript. Veja Manual:Messages API para mais detalhes.

Implementando e registrando

Em termos de desempenho e segurança, se você pretende que sua extensão seja implementada nos websites da Wikimedia (incluindo possivelmente a Wikipédia), garanta a ela uma análise adicional. Consulte Escrevendo uma extensão para implantação .

Se sua extensão adiciona espaços nominais, experimente registrar os espaços nominais padrões dela. Da mesma forma, se ela adiciona tabelas de bancos de dados ou campos, experimente registrá-los em database field prefixes .

Tenha em mente que a revisão e a implementação de novas extensões nos websites da Wikimedia podem ser extremamente lentas, em alguns casos tendo levado mais de dois anos para serem concluídas.^[4]

Documentação de ajuda

Forneça uma documentação de ajuda sob domínio público para os recursos disponibilizados por sua extensão. The convention is for extensions to have their user-focused help pages under a pseudo-namespace of Help:Extension:<ExtensionName>, with whatever subpages are required (the top level page will be automatically linked from the extension infobox if it exists). Ajuda:CirrusSearch é um exemplo de documentação bem feita. Forneça aos usuários uma ligação à documentação pela função addHelpLink() .

There are a number of common approaches to releasing updates to extensions. These are generally defined according to the compatibility policy of the extension (master, rel, or ltsrel):

• master – Releases may be tagged with version numbers on the master branch, and documentation provided on the extension's homepage describing which extension versions are compatible with which core versions. Release branches will still be created automatically, and you may wish to delete these if they are not intended to be used.
• rel e ltsrel – Release by backporting changes to the REL1_* branches (either all changes, or only critical ones). Version numbers are generally not needed unless the extension is a dependency of another (the version number can then be provided in the other extension's configuration to ensure that incompatible combinations aren't installed). Many extensions will stay at the same version number for years.

Compatibilidade com outras versões do núcleo

Existem duas convenções comuns para manter a compatibilidade com versões antigas do núcleo do MediaWiki:

• Master: a ramificação (branch) master da extensão deve ser compatível com tantas versões antigas do núcleo quanto possível. Isso resulta em um fardo de manutenção (hacks de compatibilidade com versões anteriores precisam ser mantidos por bastante tempo, e mudanças na extensão precisam ser testadas com várias versões do MediaWiki), mas os websites que usam versões antigas do MediaWiki se beneficiam das funcionalidades recentemente adicionadas à extensão.
• Ramificações por release: os chamados release branches da extensão devem ser compatíveis com as ramificações do núcleo correspondentes. P. ex., websites que utilizam o MediaWiki 1.43 precisam usar a ramificação REL1_43 da extensão. (Para extensões hospedadas no Gerrit, essas ramificações são criadas automaticamente quando as novas versões do MediaWiki são lançadas.) Isso resulta em um código mais limpo e um desenvolvimento mais rápido. Entretanto, usuários em versões antigas do núcleo não se beneficiam das correções de erros e dos novos recursos, a menos que haja um backporting manual.

Os mantenedores das extensões devem, com o parâmetro compatibility policy da predefinição {{Extensão }}, declarar qual convenção está sendo seguida.

Fornecendo suporte ou colaboração

Desenvolvedores de extensões devem abrir uma conta no Phabricator da Wikimedia e solicitar um novo projeto para a extensão. Isso fornece um canal público, onde os usuários podem relatar problemas e enviar extensões. Colabore também com os usuários e outros desenvolvedores para fazer triagem de bugs e para planejar mais recursos à sua extensão.