El primer complemento que puse en WordPress.org no envió nada durante nueve días. Confirmé el código, etiqueté el lanzamiento, vi la actualización del listado con mi nueva descripción y le dije a la gente que ya estaba disponible. Las descargas se mantuvieron estables porque el botón de descarga estaba sirviendo a una carpeta de etiquetas vacía: mi readme.txt dicho Stable tag: 1.0.1 y la etiqueta que realmente había creado era 1.0. Nada me advirtió. El directorio hizo exactamente lo que le dije.
Esa línea es el campo de mayor riesgo en un complemento de WordPress 's readme.txt, y es uno de varios que fallan silenciosamente en lugar de en voz alta. Esta guía cubre lo que hace el directorio con cada parte de ese archivo, en el orden en que tiende a ocurrir el daño. El Generador de lectura de WordPress construye el archivo con estas reglas adjuntas a los campos a los que se aplican.
TL;Dr:
Stable tagnombra la versión que realmente sirve el directorio. Se lee desdetrunk/readme.txt, y apunta a una carpeta debajo/tags/eso debe existir y debe contener la versión. Si nombra una versión que no está allí, los usuarios no obtienen nada; Si todavía nombra uno antiguo, obtienen código antiguo sin importar lo que hayas cometido.Tested up tocontrola la advertencia de compatibilidad en tu listado,Tagsindexa sólo los primeros cinco y la breve descripción se corta en 150 caracteres.
¿qué controla realmente la etiqueta estable?
Un complemento en el directorio vive en Subversion, con trunk/ para el desarrollo actual y tags/<version>/ para lanzamientos. Cuando alguien hace clic en Descargar, el directorio no lo envía trunk. Se lee trunk/readme.txt, encuentra Stable tag, și servi tags/<that value>/.
Siguen tres consecuencias y las tres muerden lanzamientos reales:
- El lector que decide que este es el que está en el baúl. Editar el readme dentro de una carpeta de etiquetas no cambia nada sobre lo que se envía.
- La etiqueta tiene que existir. un
Stable tagnombrar una carpeta que nunca se creó significa que la descarga está vacía o falla. - Trunk no es lo que reciben los usuarios. Puedes comprometerte con el troncal toda la semana; Hasta que la etiqueta estable se mueva, el código publicado es lo que sea que contenga la etiqueta anterior.
los Manual de complementos establece la regla claramente y vale la pena leerla una vez correctamente en lugar de copiar un readme de otro complemento y editar los campos. La única excepción que vale la pena conocer: Stable tag: trunk significa "servir troncal", que es legal y es como se lanzan algunos complementos. También significa que cada confirmación con el troncal está disponible inmediatamente para cada usuario, razón por la cual casi nadie debería hacerlo.
Hay una segunda mitad del lanzamiento que el lector no controla en absoluto. La versión en Stable tag tiene que coincidir con el Version: encabezado en su archivo PHP del complemento principal, porque eso es con lo que se compara un sitio instalado para decidir si existe una actualización. Envíe una etiqueta cuyo encabezado del complemento aún diga el número anterior y el directorio ofrezca una actualización que instale algo que diga ser la versión ya presente.
Lo que cada línea de encabezado hace con su listado
El bloque de encabezado consta de nueve líneas simples Key: value y cada uno de ellos cambia algo visible.
| Línea | Lo que hace | Lo que sale mal |
|---|---|---|
Stable tag |
Selecciona la versión servida | El valor incorrecto no envía nada o envía código antiguo |
Requires at least |
Versión mínima de WordPress | Instalaciones de bloques demasiado altos que funcionarían |
Tested up to |
Declaración de compatibilidad | Caer detrás muestra un "untested" advertencia |
Requires PHP |
Versión PHP mínima | Demasiado bajo permite que los sitios incompatibles se instalen y fallen |
Tags |
Palabras clave del directorio | Sólo los cinco primeros están indexados |
Contributors |
Enlaces de perfiles de WordPress.org | Un error tipográfico no le da crédito a nadie en silencio |
Donate link |
Botón de donación de barra lateral | Ausente está bien, roto no |
License / License URI |
La licencia | Debe ser compatible con GPL para figurar en la lista |
Tested up to es el que cuesta descargas silenciosamente. Cuando se quedan más de unas pocas versiones principales, la lista muestra un aviso que indica a los visitantes que el complemento no se ha probado con su versión de WordPress y que un complemento que parece abandonado se instala menos independientemente de si funciona. Actualizar esa línea es un compromiso de lectura con el troncal y lleva un minuto, que es el mantenimiento más barato del ecosistema.
Tags índices cinco. Una sexta etiqueta no es un error y no produce ninguna advertencia; simplemente es texto muerto en su archivo. Elija las cinco personas que realmente escriben.
¿Cómo se divide la descripción y por qué es importante?
Hay dos descripciones en un readme y hacen trabajos diferentes.
los breve descripción es el único bloque de texto entre las líneas del encabezado y la primera == Section ==. Tiene un límite de 150 caracteres y, más allá de eso, el directorio lo trunca en los resultados de búsqueda y en la tarjeta del complemento, generalmente a mitad de la oración. Esta es la línea que la mayoría de la gente lee antes de decidir si hacer clic, lo que convierte a 150 caracteres en el bien inmobiliario más valioso del archivo.
los descripción larga es el == Description == sección y se convierte en el cuerpo de su página de listado. Se necesita un subconjunto de Markdown: encabezados, negrita, cursiva, listas, enlaces. Se elimina HTML sin formato. Las tablas, los bloques de código vallados con resaltado de sintaxis y el Markdown más exótico no se representan, por lo que un readme que se ve bien en una vista previa de Markdown aún puede verse mal en WordPress.org.
Cada una de las otras secciones se asigna a una pestaña del listado:
== Description == the main body
== Installation == the Installation tab
== Frequently Asked Questions == the FAQ tab, one "= question =" per entry
== Screenshots == numbered captions, matched to files in /assets/
== Changelog == one "= version =" block per release, newest first
== Upgrade Notice == the short line shown inside wp-admin on update
Upgrade Notice merece más atención de la que suele recibir. Es el único texto que la mayoría de los usuarios ven antes de hacer clic en la actualización: una o dos líneas, en el mensaje de actualización, que explica por qué es importante esta versión. Una solución de seguridad, un cambio de ruptura, un nuevo requisito de PHP. Si se deja vacía, la actualización es solo un número.
¿Dónde viven el banner y el icono?
No en readme.txt. Esto hace tropezar a casi todos la primera vez, porque de donde proviene el contenido de cada dos listas.
Las imágenes viven en un /assets/ directorio en SVN, al lado trunk y tags, y coinciden por nombre de archivo:
| Archivo | proponerse | Tamaño |
|---|---|---|
banner-772x250.png |
Encabezado de listado | 772 x 250 |
banner-1544x500.png |
Encabezado de retina | 1544 x 500 |
icon-128x128.png |
Icono de resultados de búsqueda | 128 x 128 |
icon-256x256.png |
Icono de retina | 256 x 256 |
screenshot-1.png |
Primera captura de pantalla | ninguno |
Las capturas de pantalla se conectan nuevamente al readme por número. screenshot-1.png se describe en la primera línea a continuación == Screenshots ==, screenshot-2.png por el segundo, y así sucesivamente. Un título sin ningún archivo coincidente no muestra nada; un archivo sin título muestra una imagen sin etiquetar.
¿cómo es un buen registro de cambios?
Un bloque por versión, el más nuevo en la parte superior, cada línea dice lo que cambió desde el punto de vista del usuario 's:
= 3.2.5 =
* Fixed: admin menu order lost after a role change
* Improved: login customizer previews without saving
= 3.2.4 =
* Added: per-role dashboard widget visibility
" Correcciones y mejoras de errores" no le dice nada al usuario y le dice menos a un revisor. El registro de cambios también es donde cualquiera que decida si confiar en su complemento se ve primero: una lista constante de entradas específicas se lee como mantenimiento, y un intervalo de dos años se lee como abandono, independientemente de que el código siga funcionando o no.
Los registros de cambios largos están bien para recortar. Mantenga los lanzamientos recientes en readme.txt y mueve el resto a a changelog.txt; el directorio lee el recortado y el historial permanece en el repositorio.
Comprobando el archivo antes de enviarlo
Las comprobaciones mecánicas son rápidas: lo hace Stable tag coincide con una carpeta de etiquetas que existe, ¿coincide con Version: en el encabezado de su complemento, es Tested up to actual, es la breve descripción de menos de 150 caracteres, hay cinco etiquetas o menos.
WordPress.org tiene un validador oficial de readme eso analiza un archivo e informa lo que no pudo leer, que vale la pena ejecutar una vez por versión. El Generador Léame toma la otra dirección: construye el archivo a partir de campos, establece cada uno de estos límites junto al campo al que se aplica, obtiene una vista previa de la lista que producirá el archivo y lee uno existente readme.txt vuelva al formulario para que un archivo plugin's antiguo se pueda actualizar sin volver a escribirlo.
Si está mirando a otras personas y complementos #39;s en lugar de publicar los suyos propios, el Detector de complementos de WordPress enumera lo que carga una página y el detector temático lee el tema detrás.
