Статья размещена автором Бетке Сергей Сергеевич

Пишем плагин для WordPress: часть 6, пишем readme.txt

Наш плагин уже умеет кое-что: он пишет свои параметры в базу данных, предоставляет инструмент для просмотра и редактирования параметров, и пишет комментарий в head страницы :-). Закончим своеобразный “шаблон” плагина – напишем readme.txt.

Итак, пишем readme.txt: Писать будем по частям, в конце статьи приведу файл целиком. Приступим.

Заголовок файла readme.txt

Приведу сначала шаблон заголовка:

=== Plugin Name ===
Contributors: markjaquith, mdawaffe (this should be a list of wordpress.org userid's)
Donate link: http://example.com/
Tags: comments, spam
Requires at least: 2.0.2
Tested up to: 2.1
Stable tag: 4.3

Here is a short description of the plugin.  This should be no more than 150 characters.  No markup here.

== Description ==
This is the long description.

Первый раздел – идентификация и описание плагина. Цитирую readme нашего плагина-примера, после чего поясню.

=== COS Search provider ===
Contributors: sergey.s.betke@novgaro.ru
Donate link: http://sergey-s-betke.blogs.novgaro.ru/ie-search-provider-wordpress-plugin/
Tags: search, IE
Requires at least: 2.7
Tested up to: 3.0.3
Stable tag: 1.0

This plugin provides support for Search Provider Extensibility in Internet Explorer.

== Description ==

* Author: [Sergey S. Betke](http://sergey-s-betke.blogs.novgaro.ru/about)
* Project URI: <http://sergey-s-betke.blogs.novgaro.ru/ie-search-provider-wordpress-plugin/>

This plugin provides support for Search Provider Extensibility
in Internet Explorer.
This version only adds a tag
&lt;link
    title="Title"
    rel="search"
    type="application/opensearchdescription+xml"
    href="http://www.example.com/provider.xml"
/&gt;.

Теперь поясняю по шагам:

  1. Пишем идентификатор нашего плагина. Следует повторить то, что мы указали в первой строке “шапки” php файла нашего плагина. Причём знаки === важны и не могут быть опущены. Поддерживается только латиница.
  2. Пишем плагин для WordPress: часть 6, пишем readme.txtContributors. В этом поле следует указать Вашу учётную запись на ресурсе wp.org или wp-plugins.org. Для начала – регистрируемся. Полезную информацию и живые ссылки смог получить только здесь.  Итак – идём на сайт http://wordpress.org/extend/plugins/ и регистрируемся. Саму процедуру регистрации описывать не буду, скажу лишь следующее: рекомендую в качестве username использовать Ваш же e-mail (гарантированно ни с кем не будете пересекаться). Также должен предупредить: письмо с паролем после регистрации приходит с существенной задержкой, так что приготовьтесь ждать. Я зарегистрировался под username sergey.s.betke@novgaro.ru.
  3. Donate link. Укажите здесь ссылку на страницу, на которой Вы принимаете благодарности в денежном выражении. У нашего плагина подобного сервиса нет, поэтому я указал url страницы, на которой будет статья о самом плагине и его обсуждение.
  4. Tags. Введите здесь через запятую ключевые слова, что позволит потенциальным пользователям Вашего плагина его найти в репозитории wordpress.
  5. Requires at least. Здесь мы должны указать минимальную версию wordpress, на которой наш плагин будет работать. Учитывая тот факт, что мы использовали API WordPress 2.7 и указываем – 2.7.
  6. Tested up to. Речь также о версии WordPress, до которой включительно Вы тестировали Ваш плагин.
  7. Stable tag. Рекомендую оставлять trunk. Или же можно указать что-либо иное (например — версию 1.2). В этом случае в репозитории wordpress Ваши потенциальные пользователи будут видеть содержимое readme.txt не последнего, а из ветки tags/1.2 (если Вы её не забудете создать). И качать они будут версию плагина именно оттуда, а не из trunk. Это полезно только в том случае, когда Вы сохраняете в репозиторий непротестированные версии. Если же Вы их тестируете до публикации в репозиторий, рекомендую оставить trunk. Также Вы можете временно «перекинуть» пользователей на предыдущую версию, если вдруг обнаружили ошибку в последней, а исправить быстро возможности нет.
  8. Далее следует краткое описание плагина (до 150 символов). Именно данное “краткое” описание и будет видно пользователям при поиске плагина в консоли управления wordpress. При заполнении данного и последующих текстовых полей есть возможность использовать разметку markdown. Благодаря использованию предлагаемой разметки, Вы сможете добавить в описание и ссылки, и выделения. Должен Вам сказать – достаточно богатый разметки. В моём случае таким образом добавлена ссылка на страницу about моего блога.

Раздел Description

В данном разделе Вы опять таки можете использовать синтаксис markdown для разметки. Здесь Вы уже вправе размещать достаточно длинное описание функционала плагина. Следует помнить: если Вы включаете html теги в описание, перед ними не должно быть пустых строк. Иначе они и будут распознаны как html теги, а не как текст (таков уж markdown).

Installation

== Installation ==

1. Upload `cos-search-provider.php` to the `/wp-content/plugins/` directory
1. Activate the plugin through the 'Plugins' menu in WordPress
1. Go to COS Search provider options

В этом разделе Вам следует описать процедуру установки и активации Вашего плагина. И дополнительные действия, если они требуются (внесение изменений в файлы темы и так далее).

P.S. таким образом (1.) в синтаксисе markdown мы создали нумерованный список.

FAQ

== Frequently Asked Questions ==

= What is it Search Provider =

Please read about search provider for Internet Explorer
and Mozilla at [MSDN](http://msdn.microsoft.com/library/cc848862(VS.85).aspx).

= Second Question =

Thank You!

Таким образом Вы можете создать краткий FAQ по Вашему плагину. Пользуйтесь данной возможностью – этот FAQ будет доступен пользователям непосредственно в репозитории wordpress. Можно и ссылочки на Ваш сайт добавить – лишними они, как известно, не бывают :-).

Screenshots

== Screenshots ==

1. This screen shot description corresponds to screenshot-1.png. Note that the screenshot is taken from
the directory of the stable readme.txt, so in this case, `/tags/4.3/screenshot-1.png`

В этом разделе мы имеем возможность разместить ссылки и краткие описания скриншотов нашего плагина или результатов его работы. Опять-таки, когда размещу уже рабочий плагин – приведу и текст полностью и результат в репозитории wordpress.

Журнал регистрации изменений и рекомендации по обновлению

== Changelog ==

= 1.0 =
* First version.

== Upgrade Notice ==

= 1.0 =
This version fixes a security related bug.  Upgrade immediately.

Как уже понятно, в двух последних разделах мы приводим журнал изменений, внесённых нами при выпуске новых версий плагина, а также рекомендации по обновлению для пользователей.

Необязательные разделы

== License ==

The COS Search provider plugin is copyright © 2010 with
[GNU General Public License][] by Sergey S. Betke. 

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.

  [GNU General Public License]: http://www.gnu.org/copyleft/gpl.html
  
== ToDo ==
The next version or later:

1. Ability to create and edit provider.xml file.
1. Ability to specify the location provider.xml file, and automatically determination the location for file.

Разделы необязательные, но полезные.

Проверяем полученный readme.txt

Пишем плагин для WordPress: часть 6, пишем readme.txt Прежде, чем двигаться дальше, мы должны проверить наш readme.txt. Для этих целей нам предоставлен специальный сервис http://wordpress.org/extend/plugins/about/validator/. Загоняем наш readme в валидатор. Результат видим на рисунке справа. Проверку прошли успешно :-). Теперь мы уже имеем возможность публиковать свой плагин. Но об этом – в следующих статьях.

Дополнительные материалы

Рекомендую ознакомиться со следующими статьями на тему создания и публикации собственного плагина:

Отзывы » (2)

  1. Безспорно исчерпывающая статья, но для быстрого входа в курс плагинописания, нужно что то по легче, возможно на подобии вот этого.Спасибо за статью, очень познавательная.

    • Марк, я понимаю, что хочется иметь ссылку на свой блог, я не против :-) Описанный Вами плагин также достаточно сложен для первого. Кстати — не используйте <?= ?>, далеко не на любом хостинге будет работать. Рекомендую отключить короткие теги в php.ini для целей отладки новых плагинов.

Опубликовать комментарий

XHTML: Вы можете использовать следующие HTML теги: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Tags Связь с комментариями статьи:
RSS комментарии
Обратная ссылка