O que a tag estável faz e por que a errada não envia nada

O primeiro plugin que EU coloquei no WordPress.org não enviou nada por nove dias Eu tinha cometido o código, marcado o lançamento, assisti a atualização da listagem com minha nova descrição, e disse às pessoas que estava fora Os downloads permaneceram planos porque o botão de download estava servindo uma pasta de tag vazia: meu readme.txt disse Stable tag: 1.0.1 e a tag que eu realmente criei foi 1.0. Nada me avisou O diretório fez exatamente o que EU disse para.

Essa linha é o campo de apostas mais altas em um plugin WordPress's readme.txt, e é um dos vários que falham silenciosamente em vez de alto Este guia cobre o que o diretório faz com cada parte desse arquivo, na ordem em que o dano tende a acontecer O Gerador de leitura WordPress constrói o arquivo com essas regras anexadas aos campos aos quais elas se aplicam.

tl;dr: Stable tag nomeia a versão que o diretório realmente serve. É lido de trunk/readme.txt, e aponta para uma pasta abaixo /tags/ isso deve existir e deve conter o lançamento Se ele nomeia uma versão que não está lá, os usuários não recebem nada; se ele ainda nomeia um antigo, eles obtêm código antigo, não importa o que você cometeu. Tested up to controla o aviso de compatibilidade na sua listagem, Tags indexa apenas os cinco primeiros, e a breve descrição é cortada em 150 caracteres.

O que a tag Stable realmente controla?

Um plugin no diretório mora no Subversion, com trunk/ para o desenvolvimento atual e tags/<version>/ para lançamentos Quando alguém clica em Download, o diretório não os envia trunk. Ele lê trunk/readme.txt, encontra Stable tag, e serve tags/<that value>/.

Seguem-se três consequências e todas as três mordem lançamentos reais:

• O readme que decide isso é o do porta-malas. Editar o readme dentro de uma pasta de tags não altera nada sobre o que é enviado.
• A tag tem que existir. um Stable tag nomear uma pasta que nunca foi criada significa que o download está vazio ou falha.
• Trunk não é o que os usuários recebem. Você pode se comprometer com o trunk durante toda a semana; até que a tag estável se mova, o código liberado é o que quer que a tag antiga contenha.

o Manual do plug-in afirma a regra claramente, e vale a pena ler uma vez corretamente, em vez de copiar um readme de outro plugin e editar os campos A única exceção que vale a pena conhecer: Stable tag: trunk significa que o & quot; serve trunk", que é legal e é como um punhado de plugins é lançado Também significa que todo commit to trunk está imediatamente ativo para cada usuário, e é por isso que quase ninguém deve fazê-lo.

Há uma segunda metade para o lançamento que o readme não controla em tudo A versão em Stable tag tem que corresponder ao Version: cabeçalho no seu arquivo PHP plugin principal, porque é com isso que um site instalado se compara para decidir se uma atualização existe Envie uma tag cujo cabeçalho plugin ainda diz o número anterior e o diretório oferece uma atualização que instala algo que afirma ser a versão já presente.

O que cada linha de cabeçalho faz com sua listagem

O bloco de cabeçalho tem nove linhas simples Key: value e cada um deles muda algo visível.

Linha	O que faz	O que corre mal
Stable tag	Escolhe a versão servida	Valor errado não envia nada ou envia código antigo
Requires at least	Versão mínima WordPress	Blocos muito altos instalam que funcionariam
Tested up to	Declaração de compatibilidade	Ficar para trás mostra um & quot; não testado" aviso
Requires PHP	Versão mínima do PHP	Muito baixo permite que sites incompatíveis sejam instalados e falhem
Tags	Palavras-chave do diretório	Apenas os cinco primeiros são indexados
Contributors	Links Perfis WordPress.org	Um erro de digitação silenciosamente não credita ninguém
Donate link	Botão de doação da barra lateral	Ausente está bem, quebrado não
License / License URI	A licença	Deve ser compatível com GPL para ser listado

Tested up to é aquele que custa downloads silenciosamente Quando fica mais do que alguns lançamentos principais para trás, a listagem mostra um aviso dizendo aos visitantes que o plugin não foi testado com sua versão do WordPress, e um plugin que parece abandonado é instalado menos, independentemente de funcionar. Atualizar essa linha é um commit readme no trunk e leva um minuto, que é a manutenção mais barata do ecossistema.

Tags indexes five. Uma sexta tag não é um erro e não produz nenhum aviso; é simplesmente texto morto em seu arquivo Escolha as cinco pessoas realmente digitar.

Como a descrição é dividida e por que isso importa?

Existem duas descrições em um readme e elas realizam trabalhos diferentes.

o breve descrição é o único bloco de texto entre as linhas do cabeçalho e a primeira == Section ==. É limitado a 150 caracteres, e passado que o diretório trunca-lo nos resultados de pesquisa e no cartão de plugin, geralmente no meio da frase Esta é a linha que a maioria das pessoas lê antes de decidir se deve clicar, o que faz 150 caracteres o mais valioso imobiliário no arquivo.

o descrição longa é o == Description == seção e torna-se o corpo de sua página de listagem Ele leva um subconjunto de Markdown: cabeçalhos, negrito, itálico, listas, links Raw HTML é despojado Tabelas, blocos de código cercados com realce de sintaxe, e o Markdown mais exótico não renderizar, então um readme que parece certo em um visualizador Markdown ainda pode parecer errado no WordPress.org.

Cada uma das outras seções mapeia para uma guia na listagem:

== 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 mais atenção do que normalmente recebe É o único texto que a maioria dos usuários vê antes de clicar em atualização: uma ou duas linhas, no prompt de atualização, explicando por que este lançamento importa Uma correção de segurança, uma mudança de quebra, um novo requisito de PHP Deixado vazio, a atualização é apenas um número.

Onde o banner e o ícone vivem?

Não em readme.txt. Isso faz com que quase todo mundo tropece na primeira vez, porque o readme é de onde vêm todos os outros conteúdos de listagem.

Imagens ao vivo em um /assets/ diretório em SVN, ao lado trunk e tags, e eles são correspondidos pelo nome do arquivo:

Arquivo	propósito	Tamanho
banner-772x250.png	Cabeçalho listagem	772x250
banner-1544x500.png	Cabeçalho Retina	1544x500
icon-128x128.png	Ícone de resultados da pesquisa	128x128
icon-256x256.png	Ícone Retina	256x256
screenshot-1.png	Primeira captura de tela	qualquer

As capturas de tela são conectadas novamente ao readme por número. screenshot-1.png é descrito pela primeira linha abaixo == Screenshots ==, screenshot-2.png pela segunda, e assim por diante Uma legenda sem arquivo correspondente não mostra nada; um arquivo sem legenda mostra uma imagem sem rótulo.

Como é um bom changelog?

Um bloco por versão, mais novo na parte superior, cada linha dizendo o que mudou do ponto de vista do usuário & #39; 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

O & quot; Correcções de erros e melhorias" não diz nada a um utilizador e diz menos a um revisor O changelog é também onde qualquer pessoa que decida confiar no seu 'plugin' olha primeiro: uma lista constante de entradas específicas lê - se como manutenção, e um intervalo de dois anos lê - se como abandono se o código ainda funciona ou não.

Long changelogs são bons para aparar Mantenha os lançamentos recentes em readme.txt e mova o resto para a changelog.txt; o diretório lê o recortado e o histórico permanece no repositório.

Verificando o arquivo antes de enviá-lo

As verificações mecânicas são rápidas: sim Stable tag combine uma pasta de tag que existe, ela corresponde à Version: no cabeçalho do seu plugin, está Tested up to atual, é a breve descrição com menos de 150 caracteres, há cinco tags ou menos.

WordPress.org tem um validador oficial de readme que analisa um arquivo e relata o que ele não conseguiu ler, o que vale a pena executar uma vez por versão. O Gerador Readme toma a outra direção: ele constrói o arquivo a partir de campos, declara cada um desses limites ao lado do campo ao qual se aplica, visualiza a listagem que o arquivo produzirá e lê um existente readme.txt volte ao formulário para que um plugin antigo e o arquivo #39; possam ser atualizados sem redigitá-lo.

Se você estiver olhando para outras pessoas & #39; s plugins em vez de publicar o seu próprio, o Detector de plug-ins WordPress lista o que uma página carrega e o detector tema lê o tema por trás disso.