Best practices for extensions/es

Category:Development guidelines/es

Esta página contiene las buenas prácticas actuales para desarrollar extensiones para MediaWiki. Salvo que se especifique lo contrario, estos también se aplican a las apariencias.

Cada elemento recibe una calificación que refleje su importancia relativa. La calificación utiliza palabras claves tal como se definen en RFC 2119. Esto es lo que significan en el contexto:

  • MUST: Este elemento es obligatorio. Cumplir únicamente estos significa que tu extensión funcionará, pero puede ser insostenible.
  • SHOULD: Este elemento está recomendado. Cumplir también estos significa que tu extensión funcionará bien y probablemente seguirá funcionando bien en el futuro.
  • OPTIONAL: Este elemento es opcional. Te animamos a considerarlo. Las extensiones que cumplen estos se puede considerar que alcanzan el «estándar de excelencia» al que aspiramos todos, y se pueden presentar como ejemplo para otros desarrolladores.

Flujo de trabajo

  • MUST: Utilizar el rastreador de incidentes estándar. Crear o solicitar la creación de un proyecto en Phabricator para tu extensión.
  • MUST: Utilizar el sistema estándar de Revisión de código.
  • MUST: Antes del desplegue en los wikis de la Fundación Wikimedia – superar las revisiones de rendimiento y seguridad.
  • SHOULD: Ser adecuada para su uso en cualquier wiki, evitando cualquier código específico para la Fundación Wikimedia u otras organizaciones.
  • SHOULD: Antes del desplegue en los wikis de la Fundación Wikimedia – añadir la extensión y a tu equipo a la página Responsables del mantenimiento.
  • SHOULD: ¡Tener varios responsables del mantenimiento! Debería haber dos como mínimo. (No tienen por qué ser personal de la Fundación Wikimedia.)
  • OPTIONAL: Crear una guía de instalación MediaWiki-Docker para tu extensión.
  • OPTIONAL: Crear un rol MediaWiki-Vagrant para tu extensión.

Arquitectura de código

  • MUST: Utilizar el registro estructurado, con un nombre de canal propio para tu extensión y con niveles apropiados de gravedad de los mensajes. Esto ayuda a depurar. Para el despliegue en wikis de la Fundación Wikimedia, esto también ayuda a tu equipo a monitorizar la extensión. Véase también: Logstash en Wikitech.
  • SHOULD: Proporcionar la misma funcionalidad a través de la API (API de acciones o API REST) y la interfaz gráfica (index.php).
    • OPTIONAL: La funcionalidad debería implementarse evitando una duplicación significativa de código (por ejemplo, una clase de servicio compartida en el lado del servidor con vinculaciones ligeras a la API y a SpecialPage).
  • SHOULD: Utilizar Dependency Injection («DI») y clases de servicio registradas en la integración de servicios.
  • SHOULD: Evitar el estado global, especialmente los singletons y otros estados ocultos mediante variables de clase estáticas (salvo para registros de depuración y otros estados intrínsecos del proceso actual y que no se refieren a ningún wiki o invocador particular). Evitar llamadas estáticas para todo lo que no sean métodos de utilidad sin estado.
  • SHOULD: Evitar el uso de antiguas funciones globales o estáticas sin refactorizar de clases no relacionadas a la hora de crear nuevas clases de servicio basadas en DI.
  • SHOULD: Lanzar excepciones únicamente en situaciones que los invocadores no deberían manejar y por tanto están pensadas para burbujear hacia arriba.
  • SHOULD: No incluir código rígido ni hacer asunciones sobre plantillas, especialmente de una manera que no se pueda configurar para cada sitio web.
  • SHOULD: Mantener el código legible para cualquiera que esté familiarizado con esa área.
  • SHOULD: Mentener una clara separación de intereses entre lo que hace de verdad y la manera en que se presenta al usuario.
  • SHOULD: Pensar dos veces antes de añadir nuevas API públicas que deben permanecer para garantizar la compatibilidad del contenido, por ejemplo, una nueva funcionalidad de sintaxis de wikitexto.
  • SHOULD: No integrar estrechamente la funcionalidad de la apariencia con la funcionalidad de la extensión.
  • SHOULD: No añadir nuevas preferencias de usuario, salvo que tengas muy buenas razones para ello.
  • OPTIONAL: Exponer los métodos de JavaScript para su uso por parte de user scripts y accesorios y para permitir una depuración sencilla desde la consola.

Documentación

  • MUST: Disponer de una página Extension:… en mediawiki.org.
    • MUST: Añadirla a las categorías de extensión apropiadas.
    • MUST: Explicar brevemente lo que hace.
    • MUST: Documentar los enganches provistos (si los hay) bajo Extension:NombreExtensión/Hooks/NombreEnganche mediante {{Template:ExtensionHook}}.
    • MUST: Listar todas las extensiones de las que depende, y cómo instalarlas y configurarlas.
    • SHOULD: Establecer una política de compatibilidad para tu extensión en la ficha de información.
    • SHOULD: Describir todos los parámetros de configuración en un solo sitio, de mayor a menor uso.
    • OPTIONAL: Mencionar las extensiones similares y explicar cómo se compara y qué diferencia tiene con aquellas.
    • OPTIONAL: Escribir instrucciones sobre cómo desinstalar la extensión o documentar las limitaciones a la hora de desinstalarla.
  • MUST: Disponer de una página Help:Extension:… en mediawiki.org si la extensión tiene interfaces de usuario en web.
    • OPTIONAL: Añadir capturas de pantalla en varios idiomas; en el caso ideal, incluyendo alguno que se escriba de derecha a izquierda.
    • OPTIONAL: Mencionar algunos casos límite sometidos a pruebas – como muestra de la diligencia debida de no solo hacer pruebas en artículos simples o genéricos.
  • SHOULD: Utilizar de forma apropiada y consistente ‎<code>, ‎<syntaxhighlight>, ‎<kbd> y ‎<pre> en la documentación.
  • OPTIONAL: Añadir o actualizar la página de la extensión en WikiApiary.

Estructura de archivos

En su conjunto, la estructura de archivos de la extensión debería estar organizada: nombrado consistente, estructura de directorios lógica y ordenada.

  • MUST: Utilizar la siguiente estructura estándar de directorios:
    • src/ (en caso de utilizar la definición de espacios de nombres PSR4, recomendado) o includes/: contiene todas las clases PHP (y solo eso).
      • archivos i18n para los alias de las páginas especiales, palabras mágicas o espacios de nombres ubicados en la carpeta raíz.
      • SHOULD: Utilizar la estructura PSR-4 para clases y archivos, empleando Extension.json/Schema#AutoloadNamespaces en extension.json en lugar de listar todas las clases.
      • SHOULD: Ubicar las clases en el espacio de nombres MediaWiki\Extension\<NombreExtensión> (o MediaWiki\Skin\<NombreApariencia> si se trata de una apariencia). Se admite MediaWiki\<NombreExtensión> si el nombre de la extensión es una palabra suficientemente única y no algo genérico (p. ej., que no sea un verbo ni un sustantivo).
      • SHOULD: Una clase por archivo.
    • modules/ (o resources) - Contiene el JavaScript y el CSS para ResourceLoader.
    • maintenance/ - Scripts de mantenimiento de línea de comandos
    • i18n/ - Contiene mensajes localizados en archivos JSON.
    • sql/ - Archivos SQL para modificaciones de la base de datos (p. ej. llamadas por LoadExtensionSchemaUpdates)
    • tests/:
      • tests/parser/ - Contiene archivos de pruebas del analizador sintáctico.
      • tests/phpunit/ - Contiene casos de prueba de PHPUnit.
        • tests/phpunit/unit/ - Contiene casos de prueba que extienden MediaWikiUnitTestCase.
        • tests/phpunit/integration/ - Contiene casos de prueba que extienden MediaWikiIntegrationTestCase.
      • tests/qunit/ - Contiene casos de prueba de Qunit.
      • tests/selenium/ - Contiene archivos de pruebas del navegador Selenium.
    • COPYING o LICENSE - Contiene la copia completa de la licencia aplicable bajo la que se publica el código.
  • SHOULD: Evitar tener demasiados archivos en el directorio raíz.
  • SHOULD: Evitar tener demasiados directorios anidados que contienen una o dos cosas.
  • SHOULD: Evitar tener archivos demasiado grandes, o demasiados archivos minúsculos (pero mantén el patrón de una clase por archivo – la presencia de muchas clases minúsculas puede ser una señal de que algo más está mal).
  • SHOULD: Escribir un archivo README que resuma la documentación y proporcione instrucciones detalladas de instalación.
  • SHOULD: Declarar los recursos externos en un archivo foreign-resources.yaml.

Base de datos

  • MUST: En caso de añadir tablas a la base de datos, utilizar el enganche LoadExtensionSchemaUpdates para asegurar que update.php funcione.
  • MUST: Utilizar la biblioteca Wikimedia-Rdbms para todos los accesos a la base de datos. Esto evita la mayoría de los vectores de ataques de inyección SQL, procura que las transacciones se realicen correctamente y sigue las buenas prácticas de rendimiento.
  • SHOULD: Funcionar correctamente en un entorno distribuido (concurrencia, bases de datos múltiples, clustering).
  • SHOULD: Si necesita persistencia, crear un buen SQL (claves primarias, índices donde sean necesarios) y utilizar algún mecanismo de almacenamiento en caché en caso necesario.
  • SHOULD: No añadir nunca campos a las tablas del núcleo ni alterarlas de ninguna manera. Para persistir los datos asociados a las tablas del núcleo, crear una tabla dedicada para la extensión y referenciar la clave primaria de la tabla del núcleo. Esto facilita la eliminación de una extensión.
  • SHOULD: Utilizar el esquema abstracto.
  • OPTIONAL: Si la extensión persiste datos y permite la desinstalación, proporcionar un script de mantenimiento que lo automatice (p. ej., eliminar tablas y limpiar las entradas de registro y propiedades de página relevantes).

Convenciones de código

En general, sigue las convenciones de código de MediaWiki para PHP, JavaScript, CSS y cualquier otro lenguaje que esté en uso y tenga convenciones de código definidas.

Pruebas

Idioma

Los distintos aspectos del soporte de idiomas son conocidos como Localización (L10n), internacionalización (i18n), multilingualización y globalización. En general, tu extensión debería ser totalmente funcional y compatible con idiomas distintos del inglés y que no se escriban de izquierda a derecha.

  • MUST: Utilizar las funciones adecuadas de Localización (wfMessage) y no incluir cadenas rígidas y no traducibles en el código.
  • MUST: Utilizar los sistemas de internacionalización estándar de MediaWiki.
  • MUST: Utilizar un prefijo claro y único con un nombre basado en el de la extensión para todos los mensajes de interfaz.
  • MUST: Enviar mensajes de forma regular a Translatewiki.net y fusionar las traducciones actualizadas desde allí. Para extensiones alojadas en Wikimedia Gerrit, en general la plantilla de translatewiki.net te lo hará de forma proactiva. Translatewiki.net inicia un proceso automático que se suscribe a los mensajes nuevos de tu extensión y también exporta y fusiona las traducciones actualizadas de vuelta a tu repositorio una vez al día. Si esto no ha ocurrido a lo largo de una semana, contacta con la plantilla de TWN.
  • MUST: Añadir la documentación de los mensajes de qqq.json para todos los mensajes existentes en en.json.
  • SHOULD: Pasar lint a los archivos de mensajes en integración continua mediante banana-checker.
  • SHOULD: Escapar los parámetros en los mensajes de localización de la forma más fiel posible a la salida. Documentar si las funciones toman/aceptan wikitexto en contraposición con HTML.
  • OPTIONAL: Si la extensión emplea una terminología particular, escribir un glosario sobre estos términos y enlazar al mismo desde la documentación de los mensajes. Ejemplo: Wikipedia abstracta/Glosario.

Accesibilidad

Véase también Guía de accesibilidad para desarrolladores. Ten en cuenta que estas aún no están integradas en las directrices, y que para los propósitos de las buenas prácticas para las extensiones se pueden considerar OPTIONAL (opcionales), a la espera de discusiones futuras.

Seguridad

Véase también Seguridad para desarrolladores.

  • MUST: Escapar los argumentos al ejecutar comandos en la shell.
  • MUST: Proteger todas las acciones de escritura contra cross-site request forgery (CSRF).
  • MUST: Garantizar que cualquier asunto relacionado con la privacidad (verificación de usuario, supresión y eliminación de revisiones y registros) siga cubierto al refactorizar o escribir nuevo código.
  • SHOULD: Utilizar el sistema estándar de tokens CSRF de MediaWiki.
  • SHOULD: No modificar el HTML después de su depuración (el modelo común es utilizar regex, pero eso es malo).
  • SHOULD: No cargar ningún recurso de dominios externos. Esto también es necesario para la privacidad y mejora el rendimiento.
  • SHOULD: Discutir la creación de nuevos permisos de usuario y grupos de usuarios con la comunidad en primer lugar. Añadir permisos de usuario es sencillo de codificar, pero se debe considerar cuidadosamente con respecto de quién puede conceder dichos permisos y quién tiene esos permisos por defecto.
TODO: ¿Las extensiones deberían crear grupos de usuarios en su configuración predeterminada? ¿O deberíamos recomendar dejar los nuevos permisos sin asignar o asignados a grupos básicos por defecto?

No reinventar ni abusar MediaWiki

Como principio general, no reimplementes ni compitas con funcionalidades ya provistas por el núcleo de MediaWiki.

  • MUST: Utilizar los contenedores para elementos tales como WebRequest vs. $_GET, etc.
  • MUST: Utilizar enganches donde sea posible en lugar de alternativas o formas nuevas de modificar, inyectar o extender la funcionalidad.
  • MUST Utilizar los métodos de validación/depuración de MediaWiki, p. ej., aquellos de las clases Html y Sanitizer.
  • MUST: No desactivar la caché del analizador sintáctico sin tener un motivo de peso.
  • MUST: Utilizar Composer para la gestión de bibliotecas PHP de terceros.
  • SHOULD: No reinventar la rueda. Optar por bibliotecas estables y bien mantenidas cuando estas existan.
  • SHOULD: No desactivar OutputPage. (T140664)
  • SHOULD: Si existe una abstracción (p. ej., Manual:ContentHandler), utilizar la misma en lugar de enganches.
  • SHOULD: No complicarte las cosas – utilizar funcionalidades estándar como las pruebas de extension.json y el material de autodescubrimiento de PHPUnit.
  • SHOULD: Utilizar configuraciones globales de MediaWiki tales como el modo de solo lectura.


No categorizadas

  • Saber cuándo utilizar métodos de ParserOutput vs. métodos similares en OutputPage.

Meta

Esta página fue esbozada por primera vez durante el Hackatón de Wikimanía 2017.

Véase también

Category:Development guidelines/es#Best%20practices%20for%20extensions/es Category:Development guidelines/es
Category:Development guidelines/es