View source for Manual:Coding conventions/fr

<languages/>
{{Development guideline}}
{{Shortcut|CC}}
Cette page décrit les '''conventions de codage''' utilisées dans le [[Special:MyLanguage/Manual:Code|code de base de MediaWiki]] et les extensions utilisées pour les sites web Wikimedia, y compris les conventions de nommage correspondantes.
Les modifications qui ne suivent pas ces conventions peuvent être arbitrairement refusées (notées [[-1]] pour la validation par les [[Gerrit/Code review|relecteurs de code]]); ceci doit être considéré comme une invitation à corriger les problèmes de style et mettre à jour le patch.

{{TOCRight}}
Cette page liste les conventions '''générales''' qui s'appliquent à l'ensemble du code MediaWiki, quelque soit le langage dans lequel il est écrit.
Pour les instructions concernant des composants spécifiques ou des types de fichiers particuliers de MediaWiki, voir: 

* {{ll|Manual:Coding conventions/CSS|2=CSS (y compris LESS)}}
* {{ll|Manual:Coding conventions/SVG|SVG}}
* {{ll|Manual:Coding conventions/Documentation|2=Documentation}}
* {{ll|Manual:Coding conventions/Database|2=Base de données}}
* {{ll|Manual:Coding conventions/Java|Java}}
* {{ll|Manual:Coding conventions/JavaScript|JavaScript}}
* {{ll|Manual:Coding conventions/Lua|Lua}}
* {{ll|Manual:Coding conventions/PHP|PHP}}
* {{ll|Manual:Coding conventions/Python|Python}}
* {{ll|Manual:Coding conventions/Ruby|Ruby}}
* {{ll|Manual:Coding conventions/Selenium|2=Selenium (y compris Cucumber)}}

Sur Wikitech (s'applique au moins aux opérations/puppet):

* [[wikitech:Puppet_coding|Puppet]]

<span id="Code_structure"></span>
== Structure du code ==

<span id="File_formatting"></span>
=== Formatage du fichier ===

<span id="Tab_size"></span>
==== Largeur des tabulations ====

Les lignes doivent être indentées avec '''un seul caractère Tab par niveau d'indentation'''. Ne faites pas de supposition sur le nombre d'espaces par Tab. La plupart des développeurs MediaWiki estiment que 4 espaces par Tab conviennent bien pour la lisibilité, mais beaucoup de systèmes sont configurés pour utiliser 8 espaces par Tab et certains développeurs peuvent utiliser aussi 2 espaces par Tab.

Pour les utilisateurs de [[w:Vim (text editor)|vim]], une manière de faire ces initialisations est d'ajouter ce qui suit à $HOME/.vimrc :

<pre style="overflow:auto;">autocmd Filetype php setlocal ts=4 sw=4</pre>

avec des lignes semblables pour CSS, HTML et JavaScript.

Néanmoins, pour Python, suivez à la place le guide concernant les espaces de [http://www.python.org/dev/peps/pep-0008/ PEP 8], qui recommande les espaces pour les nouveaux projets.

<span id="Newlines"></span>
==== Nouvelles lignes ====

Tous les fichiers doivent utiliser le passage à la ligne du style Unix (caractère LF uniquement, et non une combinaison CR+LF).

* git sous Windows va (par défaut) convertir les passages à la ligne CR+LF en LF lors de la validation (commit).

Tous les fichiers doivent se terminer par un retour à la ligne.

* Cela a un sens parce que toutes les autres lignes ont un caractère de nouvelle ligne à la fin.
* Cela aide à faire circuler plus facilement les données en formats non binaires (comme les diffs).
* Les outils en ligne de commande comme [[w:cat (Unix)|cat]] et [[w:wc (Unix)|wc]] ne manipulent pas les fichiers si aucun n'est bon (ou au moins, pas de la manière que l'on voudrait ou que l'on souhaiterait).

<span id="Encoding"></span>
==== Encodage ====

Tous les fichiers texte '''doivent''' être encodés avec [[w:UTF-8|UTF-8]] sans [[w:byte order mark|Byte Order Mark (BOM)]].

N'utilisez pas Microsoft Notepad pour modifier vos fichiers, parce qu'il insère toujours un BOM.
Le BOM arrête l'exécution des fichiers PHP parce que c'est un caractère spécial tout au début du fichier et qu'il est passé par le navigateur web au client.

Bref, assurez-vous que votre éditeur prend en charge UTF-8 sans BOM.

<span id="Trailing_whitespace"></span>
==== Caractères espaces de fin de ligne ====

Quand vous utilisez un IDE, en pressant les touches Home et End (parmi d'autres raccourcis clavier) vous ignorez habituellement les espaces de fin et à la place vous sautez à la fin du code, ce qui est le but. Pour les éditeurs de texte non-IDE, au contraire, en pressant End vous allez à l'extémité complète de la ligne, ce qui signifie que le développeur doit revenir en arrière à travers les espaces de fin pour revenir finalement à l'endroit où il voulait entrer son texte.

Enlever les espaces de fin est une opération triviale pour la plupart des éditeurs de texte. Les développeurs doivent éviter d'ajouter des espaces après la fin, principalement sur les lignes qui contiennent d'autre code visible.

Certains outils rendent cela plus facile:

* nano: [https://www.nano-editor.org/ GNU nano 3.2];
* {{ll|Komodo Edit}}: dans Enregistrer les options du menu "Editer > Préférences", active "Supprimer les espaces et les marqueurs de fin de ligne" et "Nettoyer seulement les lignes modifiées";
* Kate: vous pouvez voir les espaces de fin en activant l'option "Metre en valeur les espaces de fin". Cette option  se trouve dans "Paramètres > Configurer Kate > Aspect". Vous pouvez aussi dire à Kate de nettoyer les espaces de fin lors de l'enregistrement dans "Paramètres > Configurer Kate > Ouvrir/Enregistrer".
* vim: divers plugin de nettoyage automatique;
* Sublimer le texte: [https://github.com/SublimeText/TrailingSpaces plugin TrailingSpaces].

<span id="Keywords"></span>
==== Mots-clé ====

N'utilisez pas de parenthèses avec des mots-clé (comme <code>require_once</code>, <code>require</code>) là où ce n'est pas nécessaire.

<span id="Indenting_and_alignment"></span>
=== Indentation et alignement ===

<span id="General_style"></span>
==== Style général ====

Le style d'indentation de MediaWiki est similaire à ce que l'on appelle le "[[w:Indent style#Variant: 1TBS|style à une accolade vraie]]" (One True Brace Style). Les accolades sont ainsi placées sur la même ligne que le début de la fonction, de la condition, de la boucle, etc. Le else/elseif est placé sur la même ligne que l'accolade fermante qui le précède.

<syntaxhighlight lang="php">
function wfTimestampOrNull( $outputtype = TS_UNIX, $ts = null ) {
	if ( $ts === null ) {
		return null;
	} else {
		return wfTimestamp( $outputtype, $ts );
	}
}
</syntaxhighlight>

Les instructions qui s'écrivent sur plusieurs lignes ont leur seconde ligne et les suivantes indentées d'un niveau supplémentaire:

Utilisez l'indentation et le passage à la ligne suivante pour clarifier la structure logique de votre code. Les expressions qui imbriquent des niveaux multiples de parenthèses ou des structures similaires peuvent commencer un nouveau niveau d'indentation avec chaque niveau d'imbrication:

<syntaxhighlight lang="php">
$wgAutopromote = [
	'autoconfirmed' => [ '&',
		[ APCOND_EDITCOUNT, &$wgAutoConfirmCount ],
		[ APCOND_AGE, &$wgAutoConfirmAge ],
	],
];
</syntaxhighlight>

<span id="Vertical_alignment"></span>
==== Alignement vertical ====

Evitez l'alignement vertical. Il a tendance à créer des diffs difficiles à interpréter, parce que la largeur autorisée pour la colonne de gauche doit sans cesse augmenter au fur et à mesure que des éléments sont ajoutés.

{{note|1=La plupart des outils de diff fournissent des options pour ignorer les modifications des espaces.<br/>Git: <code>git diff -w</code>}}

Quand c'est nécessaire, créez un alignement vertical sur la ligne du milieu avec des espaces plutôt que des tabulations. Par exemple, ceci :

<syntaxhighlight lang="php">
$namespaceNames = [
	NS_MEDIA            => 'Media',
	NS_SPECIAL          => 'Special',
	NS_MAIN             => '',
];
</syntaxhighlight>

Se réalise ainsi avec les espaces remplacés par des points:

<pre style="overflow:auto;">
$namespaceNames·=·[
 →  NS_MEDIA············=>·'Media',
 →  NS_SPECIAL··········=>·'Special',
 →  NS_MAIN·············=>·'',
];
</pre>

(Si vous utilisez le [https://github.com/godlygeek/tabular plugin vim de tabulation], en entrant <kbd>:Tabularize /=</kbd> vous alignerez les signes '='.)

<span id="Line_width"></span>
==== Largeur de ligne ====
Les lignes doivent s'arrêter avec un passage à la ligne entre les colonnes 80 et 100. Il existe quelques rares exceptions à cela. Les fonctions qui prennent beaucoup de paramètres ne font pas exception.
L'idée est que le code ne doit pas déborder de l'écran quand le repli des mots est désactivé.

L'opérateur qui sépare les deux lignes doit être placé de manière cohérente (toujours à la fin, ou toujours au début de la ligne). Certaines langages peuvent avoir individuellement des règles plus spécifiques.

<syntaxhighlight lang="php">
return strtolower( $val ) === 'on'
	|| strtolower( $val ) === 'true'
	|| strtolower( $val ) === 'yes'
	|| preg_match( '/^\s*[+-]?0*[1-9]/', $val );
</syntaxhighlight>

<syntaxhighlight lang="php">
$foo->dobar(
	Xml::fieldset( wfMessage( 'importinterwiki' )->text() ) .
		Xml::openElement( 'form', [ 'method' => 'post', 'action' => $action, 'id' => 'mw-import-interwiki-form' ] ) .
		wfMessage( 'import-interwiki-text' )->parse() .
		Xml::hidden( 'action', 'submit' ) .
		Xml::hidden( 'source', 'interwiki' ) .
		Xml::hidden( 'editToken', $wgUser->editToken() ),
	'secondArgument'
);
</syntaxhighlight>

L'opérateur de méthode doit toujours être mis au début de la ligne suivante.

<syntaxhighlight lang="php">
$this->getMockBuilder( Message::class )->setMethods( [ 'fetchMessage' ] )
	->disableOriginalConstructor()
	->getMock();
</syntaxhighlight>

Lorsque vous continuez des instructions "if", un  sélecteur d'accolades de   [[w:Indentation_style#Allman_style|style Allman]] rend plus claire la séparation entre la condition et le corps :

<syntaxhighlight lang="javascript">
if ( $.inArray( mw.config.get( 'wgNamespaceNumber' ), whitelistedNamespaces ) !== -1 &&
	mw.config.get( 'wgArticleId' ) > 0 &&
	( mw.config.get( 'wgAction' ) == 'view' || mw.config.get( 'wgAction' ) == 'purge' ) &&
	mw.util.getParamValue( 'redirect' ) !== 'no' &&
	mw.util.getParamValue( 'printable' ) !== 'yes'
) {
	…
}
</syntaxhighlight>

Les opinions diffèrent sur le nombre d'indentations qui doivent être utilisées pour la partie conditionnelle. En utilisant un nombre d'indentations différent que celui du corps, on voit de suite que la partie contitionnelle n'est pas le corps, mais ceci n'est pas observé universellement.

La continuation des conditions et les expressions très longues deviennent inextricables quelque soit la manière dont vous les formuliez. Il est donc parfois meilleur de les séparer à l'aide de variables temporaires.

<span id="Braceless_control_structures"></span>
==== Structures de contrôle sans accolades ====

N'écrivez pas les « blocs » sur une seule ligne. Cela réduit la lisibilité du code en déplaçant les instructions importantes de la marge gauche, là où le lecteur les attend. Rappelez-vous que faire un code plus court ne le simplifie pas. Le but du style de codage est de communiquer efficacement avec les humains, et non pas de placer du texte compréhensible par l'ordinateur dans un petit espace.

<syntaxhighlight lang="php">
// No:
if ( $done ) return;

// No:
if ( $done ) { return; }

// Yes:
if ( $done ) {
	return;
}
</syntaxhighlight>

Ceci évite une erreur de logique commune, qui est particulièrement importante quand le développeur utilise un éditeur de texte qui n'a pas la fonction d' « indentation intelligente ». L'erreur apparait alors quand un bloc mono-ligne est ensuite étendu sur deux lignes :

<syntaxhighlight lang="php">
if ( $done )
	return;
</syntaxhighlight>

Modifié ultérieurement en:

<syntaxhighlight lang="php">
if ( $done )
	$this->cleanup();
	return;
</syntaxhighlight>

Ceci a la capacité de créer des bogues subtiles.

<span id="emacs_style"></span>
==== Style emacs ====

Dans emacs, en utilisant <code>php-mode.el</code> du [https://web.archive.org/web/20121213222615/http://ourcomments.org/Emacs/nXhtml/doc/nxhtml.html mode nXHTML], vous pouvez définir un mode MediaWiki mineur dans votre fichier <code>.emacs</code> :

<syntaxhighlight lang="elisp">
(defconst mw-style
  '((indent-tabs-mode . t)
    (tab-width . 4)
    (c-basic-offset . 4)
    (c-offsets-alist . ((case-label . +)
                        (arglist-cont-nonempty . +)
                        (arglist-close . 0)
                        (cpp-macro . (lambda(x) (cdr x)))
                        (comment-intro . 0)))
    (c-hanging-braces-alist
        (defun-open after)
        (block-open after)
        (defun-close))))

(c-add-style "MediaWiki" mw-style)

(define-minor-mode mah/mw-mode
  "tweak style for mediawiki"
  nil " MW" nil
  (delete-trailing-whitespace)
  (tabify (point-min) (point-max))
  (subword-mode 1)) ;; If this gives an error, try (c-subword-mode 1)), which is the earlier name for it

;; Add other sniffers as needed
(defun mah/sniff-php-style (filename)
  "Given a filename, provide a cons cell of
   (style-name . function)
where style-name is the style to use and function
sets the minor-mode"
  (cond ((string-match "/\\(mw[^/]*\\|mediawiki\\)/"
                       filename)
         (cons "MediaWiki" 'mah/mw-mode))
        (t
         (cons "cc-mode" (lambda (n) t)))))

(add-hook 'php-mode-hook (lambda () (let ((ans (when (buffer-file-name)
                                                 (mah/sniff-php-style (buffer-file-name)))))
                                      (c-set-style (car ans))
                                      (funcall (cdr ans) 1))))
</syntaxhighlight>

La fonction <code>mah/sniff-php-style</code> ci-dessus, va vérifier votre chemin lorsque <code>php-mode</code> est appelé pour voir si s'il contient “mw” ou “mediawiki” et initialiser le tampon pour utiliser le mode mineur <code>mw-mode</code> pour la modification du source MediaWiki.
Vous saurez que le tampon utilise <code>mw-mode</code> parce que vous verrez quelquechose comme “PHP MW” ou “PHP/lw MW” dans le champ du mode ligne.

<span id="Data_manipulation"></span>
=== Manipulation des données ===

<span id="Constructing_URLs"></span>
==== Construction des URL ====

Ne construisez jamais les URL manuellement avec des concaténations de chaînes ou similaire. Utilisez toujours le format complet de l'URL pour les requêtes faites par votre code (particulièrement pour les requêtes POST et d'arrière-plan).

Vous pouvez utiliser la méthode appropriée de {{ll|Manual:Linker.php|Linker}} ou de {{ll|Manual:Title.php|Title}} en PHP, le mot magique {{ll|Help:Magic words#fullurl|fullurl}} dans le texte wiki, la méthode [[wmdoc:mediawiki-core/master/js/module-mediawiki.util.html#.getUrl|mw.util.getUrl()]] en JavaScript, et d'autres méthodes similaires dans d'autres langages.
Vous éviterez les problèmes avec la [[Special:MyLanguage/Manual:Short URL|configuration d'URL courte]] non-attendue et davantage.

<span id="File_naming"></span>
== Nommage des fichiers ==
Les fichiers qui contiennent du code côté serveur doivent être nommés en ''casse mixte commençant par une majuscule''.
C'est aussi notre convention de nommage pour les [[Special:MyLanguage/Manual:Developing extensions|extensions]].<ref>[[mailarchive:wikitech-l/2011-August/054839.html]]</ref>
Nommer le fichier d'après la plus importante classe qu'il contient; la plupart des fichiers ne contiennent qu'une seule classe, ou une classe de base et un nombre de descendants.
Par exemple, <code>{{git file |file=includes/Title.php |text=Title.php}}</code> ne contient que la classe <code>Title</code> ; <code>{{git file |file=includes/WebRequest.php |text=WebRequest.php}}</code> contient la classe <code>WebRequest</code> , avec ses descendants: <code>FauxRequest</code> et <code>DerivativeRequest</code>.

<span id="Access_point_files"></span>
=== Fichiers des points d'accès ===

Nommez les fichiers des « point d'accès », tels que les points d'entrée de SQL et de PHP, comme <code>index.php</code> et <code>''foobar''.sql</code>, en ''minuscules''. Les scripts de maintenance sont généralement en ''casse mixte'', bien que cela puisse varier. Les fichiers de l'administrateur de site, comme les README, les licences et les jounaux des modifications, sont habituellement en ''MAJUSCULES''.

N'utilisez jamais les espaces dans les noms de fichiers ou de répertoires, et n'utilisez jamais les caractères non-ASCII. Pour les titres en minuscules, les tirets sont préférables aux caractères soulignés.

<span id="JS,_CSS,_and_media_files"></span>
=== Fichiers JS, CSS, et de média ===
Pour JavaScript, les fichiers CSS et autres fichiers d'interface utilisateur (généralement enregistrés via [[Special:MyLanguage/ResourceLoader|ResourceLoader]]) doivent être placés dans un répertoire nommé d’après l'archive du module dans lequel ils sont enregistrés.
Par exemple le module <code>mediawiki.foo</code> peut contenir les fichiers <code>mediawiki.foo/Bar.js</code> et <code>mediawiki.foo/baz.css</code>

Les fichiers JavaScript qui définissent des classes doivent correspondre exactement au nom de la classe qu’ils définissent.
La classe <code>TitleWidget</code> doit être dans un fichier qui a le même nom, ou dont le noms est suffixé avec, comme <code>TitleWidget.js</code>.
Cela permet une navigation rapide dans les éditeurs de texte en naviguant vers des fichiers nommés d’après un nom de classe sélectionné (comme "Goto Anything [P]" dans Sublime, ou "Find File [P]" dans Atom).

Les grands projets peuvent avoir des classes hiérarchisées avec des noms qui se chevaucheraient ou seraient ambigus sans moyen supplémentaire d’organiser les fichiers.
Nous résolvons généralement cela en utilisant des sous-répertoires comme <code>ext.foo/bar/TitleWidget.js</code> (pour les [[Special:MyLanguage/ResourceLoader/Package files|Paquets de fichiers]]), ou en allongeant le nom des classes et des fichiers comme <code>mw.foo.bar.TitleWidget</code> dans <code>ext.foo/bar.TitleWidget.js</code>.

Les paquets de modules enregistrés par les extensions doivent suivre le même principe de nommage comme par exemple <code>ext.''myExtension''</code> dans <code>MyExtension/modules/ext.myExtension/index.js</code>.
Cela permet de commencer facilement à travailler sur un module dans un éditeur de texte, en trouvant directement les fichiers de code source à partir seulement du nom public du module ([[phab:T193826|T193826]]).

== Documentation ==
Les sous-pages spécifiques à un langage ont davantage d'informations sur la syntaxe exacte concernant les commentaires dans les fichiers de code, par exemple les [[Special:MyLanguage/Manual:Coding conventions/PHP#Comments and documentation|commentaires en PHP]] pour Doxygen.
En utilisant la syntaxe précise, vous pourrez générer la documentation à partir du code source, sur [https://doc.wikimedia.org doc.wikimedia.org].

Les concepts de haut niveau, les sous-systèmes, et les flux de données doivent être documentés dans le répertoire <code>{{git file|file=docs|text=/docs}}</code> .

<span id="Source_file_headers"></span>
=== Entêtes des fichiers source ===

Pour être conforme avec la plupart des licenses vous devez avoir quelque chose de similaire à ceci (spécifique aux applications PHP GPLv2) au début de chaque fichier source.

<syntaxhighlight lang="php">
<?php
/**
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 * http://www.gnu.org/copyleft/gpl.html
 * 
 * @file
 */
</syntaxhighlight>

<span id="Licenses"></span>
=== Licences ===

Les licenses sont généralement référencées par leur nom complet ou un acronyme comme pour le [https://spdx.org/licenses/ SPDX standard]. Voir aussi [[Special:MyLanguage/Manual:$wgExtensionCredits#license|Manual:$wgExtensionCredits#license]].

<span id="Dynamic_identifiers"></span>
=== Identifiants dynamiques ===

D'une manière générale, il est recommandé d'éviter de construire dynamiquement les identificateurs tels que les clés des messages d'interface, les noms des classes CSS, ou les noms de fichiers.
Lorsque c'est possible, écrivez-les en dehors et sélectionnez-les (par exemple en utilisant une condition, ou en utilisant l'opérateur ternaire ou un sélecteur).
Ceci améliore la stabilité du code et la productivité des développeurs : en facilitant la relecture du code, en augmentant la confidentialité lors du debogage, de la découverte des cas d'utilisation, de l'utilisation des outils du type ''git-grep'', ''Codesearch'', etc.

Si le code est considéré comme étant une meilleure image de la structure logique, ou bien s'il a besoin de changer tout le temps, alors vous pouvez à la place, concaténer l'identifiant avec une variable.
Dans ce cas, vous devez laisser un commentaire à proximité en indiquant les valeurs possibles (ou les plus fréquentes) pour prouver le comportement et pour aider à la recherche et la découverte.

Voir aussi :
* [[Help:System message#Using messages]]

{{code convention example|posneg=negative|
<syntaxhighlight lang="php">
// No: Avoid composing message keys
$context->msg( 'templatesused-' . ( $section ? 'section' : 'page' ) );
</syntaxhighlight>
}}

{{code convention example|posneg=positive|
<syntaxhighlight lang="php">
// Yes: Prefer full message keys
$context->msg( $section ? 'templatesused-section' : 'templatesused-page' );
</syntaxhighlight>
<syntaxhighlight lang="javascript">
// If needed, concatenate and write explicit references in a comment

// Messages:
// * myextension-connect-success
// * myextension-connect-warning
// * myextension-connect-error
var text = mw.msg( 'myextension-connect-' + status );
</syntaxhighlight>
<syntaxhighlight lang="javascript">
// The following classes are used here:
// * mw-editfont-monospace
// * mw-editfont-sans-serif
// * mw-editfont-serif
$texarea.addClass( 'mw-editfont-' + mw.user.options.get( 'editfont' ) );
</syntaxhighlight>
<syntaxhighlight lang="php">
// Load example/foo.json, or example/foo.php
$thing->load( "$path/foo.$ext" );
</syntaxhighlight>
}}

<span id="Release_notes"></span>
== Notes des versions ==
{{See also|Gerrit/Commit message guidelines}}
Vous devez documenter [[mailarchive:wikitech-l/2006-August/026207.html|toutes les modifications significatives]] (y compris [http://article.gmane.org/gmane.science.linguistics.wikipedia.technical/65130 tous les rapports de bogues corrigés]) faites sur le coeur du logiciel qui pourraient impacter les [[mailarchive:wikitech-l/2006-August/026207.html|utilisateurs du wiki]], les administrateurs des serveurs, [[mailarchive:wikitech-l/2006-December/028133.html|ou les auteurs des extensions]] dans le fichier <code>RELEASE-NOTES-''N.NN''</code>.
<code>{{git file |file=RELEASE-NOTES-{{MW Alpha branch number}}}}</code> est en développement; pour chaque version nous déplaçons les anciennes notes de diffusion dans le fichier <code>{{git file |file=HISTORY}}</code> et nous en ouvront un nouveau.
<code>RELEASE-NOTES-''N.NN''</code> est généralement divisé en trois sections :

* '''Configuration changes''' c'est l'endroit pour décrire les modifications relatives aux comportements par défaut acceptés, aux ruptures de compatibilité, et autres sujets qui demandent à ce qu'administrateur de serveurs  regarde et ''décide si la modification est acceptable pour son wiki''. Essayez d'inclure une explication ''brève'' sur la manière de revenir à l'ancienne fonctionalité si cela est désiré.
* '''Bug fixes''' c'est l'endroit pour décrire les modifications qui corrigent le comportement désigné comme problématique ou indésirable. Cela correspond souvent à des tâches référencées dans {{ll|Phabricator}}, mais pas nécessairement.
* '''New features''' sert, vous vous en doutez, à décrire l'ajout des nouvelles fonctionalités.

Il peut y avoir des sections supplémentaires pour les comportements spécifiques (par exemple l'[[Special:MyLanguage/API:Main page|API Action]]) ou pour diverses modifications qui ne rentrent pas dans les catégories ci-dessus.

Dans tous les cas, si vos modifications concernent la réponse à un ou plusieurs problèmes référencés dans Phabricator, mettez le ou les ID des tâches concernées au début de l'entrée. Ajoutez de nouvelles entrées [[mailarchive:wikitech-l/2007-March/030539.html|dans l'ordre chronologique à la fin de la section]].

{{Anchor|Messages}}
<span id="System_messages"></span>
== Messages système ==
Quand vous créez un nouveau [[Special:MyLanguage/Manual:system message|message système]], [[mailarchive:wikitech-l/2007-December/035583.html|utilisez des tirets (-) quand c'est possible]] au lieu d'une casse mixte ou d'utiliser le souligné(_).
Ainsi par exemple, <code>some-new-message</code> est bien pour un nom, tandis que <code>someNewMessage</code> et <code>some_new_message</code> sont à proscrire.

Si le message est une étiquette qui peut avoir un deux-points (:) à la fin, ne codez pas le deux-points; à la place, mettez le dans le texte du message. Certaines langues (telles que le français qui demande d'avoir un espace avant) doivent gérer le deux-points d'une manière différente, ce qui est impossible si les deux-points sont codés en dur. [[Special:MyLanguage/i18n#Symbols, colons, brackets, etc. are parts of messages|Ceci vaut pour plusieurs autres d'interpunctuation]].

Essayez d'utiliser les clés de messages "en entier" dans le code, plûtot que de les construire à la volée; car c'est plus facile de les rechercher dans la base de code. L'exemple suivant montre qu'une recherche de <code>templatesused-section</code> ne trouvera pas cette utilisation de clé de message si elle n'est pas entière.

<syntaxhighlight lang="php">
// No:
return wfMessage( 'templatesused-' . ( $section ? 'section' : 'page' ) );

// Yes:
$msgKey = $section ? 'templatesused-section' : 'templatesused-page';
return wfMessage( $msgKey );
</syntaxhighlight>

Si vous pensez que vous devez construire les messages à la volée, mettez à côté, un commentaire avec tous les messages possibles en entier:

<syntaxhighlight lang="php">
// Messages that can be used here:
// * myextension-connection-success
// * myextension-connection-warning
// * myextension-connection-error
$text = wfMessage( 'myextension-connection-' . $status )->parse();
</syntaxhighlight>

Voir la [[Special:MyLanguage/Localisation|Localisation]] pour davantage de conventions concernant la créatiion, l'usage, la documentation et la maintenance des clés de messages.

<span id="Preferred_spelling"></span>
=== Orthographe préférée ===

C'est aussi important d'avoir une orthographe cohérente de l'interface utilisateur avec la base de code que d'avoir une interface cohérente. Après un long historique, l'orthographe de l'anglais américain ('American English') est l'orthographe préférée pour les messages en langue anglaise, les commentaires, et la documentation.

<span id="Abbreviations_in_message_keys"></span>
=== Abbréviations des clés de messages ===
; ph
: emplacement à substituer (texte des champs d'entrée)
; tip
: texte de la bulle d'aide
; tog-''xx''
: gérer les options dans les préférences utilisateur

<span id="Punctuation"></span>
=== Ponctuation ===

Les messages d'erreur qui ne sont pas des titres sont considérés comme des phrases et doivent avoir une ponctuation.

<span id="Improve_the_core"></span>
== Améliorer le noyau ==
Si vous avez besoin de fonctionnalités supplémentaires concernant un composant du noyau MediaWiki (classe PHP, module JS, etc...), ou si vous voulez une fonction qui fait quelque chose de similaire mais un peu différent, il est préférable d'améliorer le composant du noyau.
Evitez de dupliquer le code dans une extension ou ailleurs dans le noyau et de le modifier à cet endroit.

<span id="Refactoring"></span>
== Remise en forme du code ==

Restructurez le code aussitôt que les modifications sont faites: n'attendez pas que le code s'enlaidisse au fur et à mesure des modifications.

Néanmoins, utilisez des commits séparés si votre restructuration est importante. Voir aussi les [[Special:MyLanguage/Architecture guidelines|Instructions pour l'architecture]] (ébauche).

== HTML ==
Les réponses HTTP de MediaWiki produisent du code HTML qui peut être généré par l'une des deux sources.
Le code PHP de MediaWiki est une source fiable pour l'interface utilisateur, il peut produire tout HTML arbitraire.
L'analyseur convertit le texte wiki généré de l'utilsateur en HTML, c'est une source non fiable.
Le code HTML complexe créé par les utilisateurs via le texte wiki est souvent issu de l'espace de noms « Template ».
Le HTML produit par l'analyseur est sujet à être nettoyé avant d'être envoyé.

La plupart des attributs de <code>data-*</code> peuvent être employés par les utilisateurs dans le wikicode et les modèles. Mais les préfixes suivants (non autorisés dans le wikicode) ont été restreints et seront supprimés dans la sortie HTML.
Ceci permet de savoir au code JavaScript du client si un élément du DOM provient d'une source fiable :

* <code>data-ooui</code> – Cet attribut est présent dans le HTML généré par les widgets OOUI.
* <code>data-parsoid</code> – attribut réservé à usage interne pour Parsoid.
* <code>data-mw</code> {{int|and}} <code>data-mw-...</code> – attribut réservé à usage interne du coeur de MediaWiki, des habillages et des extensions. L'attribut <code>data-mw</code> est utilisé par Parsoid; tout autre code du noyau doit utiliser <code>data-mw-*</code>.

En sélectionnant des éléments dans JavaScript, on peut préciser un attribut clé/valeur pour s'assurer que seulement les éléments DOM de la source présumée de confiance, sont pris en compte.
Exemple: [[gerrit:256665|Ne gèrer que l'accroche 'wikipage.diff' pour les diffs officiels]].

== Notes ==
<references />

<span id="External_links"></span>
== Liens externes ==

* [[:toollabs:stylize|outils de style pour le code]]

{{Conventions navigation}}

[[Category:MediaWiki code{{#translation:}}|Coding conventions]]