Информация о представлении группы модулей

• Представление группы модулей
• Перед началом кодирования
• Конвенция именования
• Свяжитесь с нами
• Где получить поддержку
• Ваш первый запрос на вытягивание
• Последующие запросы на вытягивание
• В заключение
• Новые в Git или GitHub

Представление группы модулей

В этом разделе обсуждается, как добавить несколько связанных модулей в Ansible.

Этот документ предназначен как для компаний, желающих добавить модули для собственной продукции, так и для пользователей сторонних продуктов, желающих добавить функциональность Ansible.

Он основан на лучших практиках разработки модулей, накопленных командой Ansible и сообществом.

Перед началом кодирования

Хотя соблазнительно сразу приступить к кодированию, есть несколько моментов, о которых следует знать. Этот список предварительных условий призван помочь гарантировать, что вы разработаете качественные модули, которые легко пройдут процесс проверки и быстрее интегрируются в Ansible.

• Прочитайте все страницы по ссылке Разработка модулей, уделяя особое внимание Вклад вашего модуля в Ansible.
• Для новых модулей, которые войдут в Ansible 2.4, мы повышаем планку, поэтому они должны соответствовать PEP 8. См. PEP 8 для получения дополнительной информации.
• Начиная с версии Ansible 2.4 все новые модули должны поддерживать Python 2.6 и Python 3.5+. Если это проблема, пожалуйста, свяжитесь с нами (см. раздел «Свяжитесь с нами» в этом документе, чтобы узнать как).
• Все модули, поставляемые с Ansible, должны распространяться под лицензией GPLv3. Файлы в каталоге lib/ansible/module_utils/ должны распространяться под лицензией BSD.
• Посмотрите на существующие модули и как они названы в Все модули, особенно в той же функциональной области (например, облачные, сетевые, базовые данные).
• Общий код можно разместить в lib/ansible/module_utils/
• Общую документацию (например, описание общих аргументов) можно разместить в lib/ansible/utils/module_docs_fragments/.
• С большой властью приходит большая ответственность: поддерживающие модули Ansible обязаны помогать в обновлении модулей. Как и в случае со всеми успешными проектами сообщества, поддерживающие модули должны внимательно следить за сообщениями об ошибках и вкладами.
• Хотя это не обязательно, тесты модулей и/или интеграционные тесты настоятельно рекомендуются. Тесты модулей особенно полезны при необходимости внешних ресурсов (например, облачных или сетевых устройств). Для получения дополнительной информации см. dev_guide/testing и группу по работе с тестами. * Начиная с Ansible 2.4 все сетевые модули ДОЛЖНЫ иметь тесты модулей.

Конвенция именования

Как вы могли заметить, просматривая lib/ansible/modules/, мы поддерживаем глубину вложения до двух каталогов (но не глубже), например databases/mysql. Это используется для группировки файлов на диске, а также для группировки связанных модулей в категории и темы в Индексе модулей, например: Базовые модули.

Имя каталога должно отражать имя продукта или ОС, а не имя компании.

Каждый модуль должен иметь вышеупомянутый (или аналогичный) префикс; см. существующие Все модули для существующих примеров.

Примечание:

• Имена файлов и каталогов всегда в нижнем регистре
• Слова разделяются символом подчеркивания (_)
• Имена модулей должны быть в единственном числе, а не во множественном, например, command , а не commands

Свяжитесь с нами

Обсуждение ваших идей до кодирования — хороший способ начать в нужном направлении.

После прочтения раздела «Перед началом кодирования» у вас, надеемся, появится общее представление о структуре ваших модулей.

Мы обнаружили, что составление списка предполагаемых имен модулей и описание того, что они будут делать, в одной-двух строках, а затем их проверка в Ansible — отличный способ убедиться, что модули соответствуют тому, как люди использовали модули Ansible раньше, и, следовательно, сделать их более удобными в использовании.

Где получить поддержку

Ansible обладает процветающим и знающим сообществом разработчиков модулей, являющимся отличным ресурсом для получения ответов на свои вопросы.

На Информация о сообществе и вклад вы можете узнать, как:

• Подписаться на списки рассылки — мы рекомендуем «Список рассылки разработчиков Ansible» (для получения информации о замораживании кода) и «Список рассылки объявлений Ansible»
• #ansible-devel — мы обнаружили, что IRC #ansible-devel на сети FreeNodes IRC лучше всего подходит для разработчиков модулей, чтобы мы могли вести интерактивный диалог.
• Встречи IRC — присоединяйтесь к различным еженедельным встречам IRC по расписанию встреч и повестке дня

Ваш первый запрос на вытягивание

Теперь, когда вы ознакомились с этим документом, вы должны быть готовы открыть свой первый запрос на вытягивание.

Первый запрос несколько отличается от остальных, потому что он:

• определяет пространство имен
• предоставляет основу для подробного обзора, который поможет сформировать ваши будущие запросы
• может включать общую документацию (docs_fragments) для нескольких модулей
• может включать общий код (module_utils) для нескольких модулей

Первый запрос должен содержать следующие файлы:

• lib/ansible/modules/$category/$topic/__init__.py — пустой файл для инициализации пространства имен и возможности импорта файлов в Python. Требуется новый файл
• lib/ansible/modules/$category/$topic/$yourfirstmodule.py — один модуль. Требуется новый файл
• lib/ansible/utils/module_docs_fragments/$topic.py — документация по коду, например, информация об общих аргументах. Необязательный новый файл
• lib/ansible/module_utils/$topic.py — код, общий для нескольких модулей, например, общие аргументы. Необязательный новый файл
• docs/docsite/rst/dev_guide/developing_module_utilities.rst — документируйте свой новый файл module_utils. Необязательное обновление существующего файла

И это все.

Перед отправкой запроса на вытягивание в GitHub рекомендуется еще раз просмотреть Вклад вашего модуля в Ansible.

После публикации вашего запроса на вытягивание в https://github.com/ansible/ansible тест Shippable CI должен выполниться в течение нескольких минут. Проверьте результаты (внизу страницы запроса) и убедитесь, что они пройдены (зеленый цвет). Если тесты не пройдены, проверьте каждый результат. Большинство ошибок должны быть понятны и часто связаны с неправильно отформатированной документацией (см. Синтаксис YAML) или кодом, не соответствующим Python 2.6 или Python 3.5 (см. Ansible и Python 3). Если вы не уверены, что означает сообщение теста Shippable, скопируйте его в запрос на вытягивание вместе с комментарием, и мы его проверим.

Если вам нужна дополнительная консультация, рассмотрите возможность присоединиться к каналу IRC #ansible-devel (см. как это сделать в разделе «Где получить поддержку»).

У нас есть помощник ansibullbot , который комментирует проблемы и запросы на вытягивание GitHub, что должно выделить важную информацию.

Последующие запросы на вытягивание

К этому моменту ваш первый запрос на вытягивание, который определил пространство имен модуля, должен быть объединен. Вы можете воспользоваться уроками, извлеченными из первого запроса, и применить их к остальным модулям.

Создавайте по одному запросу на вытягивание на модуль для оставшихся модулей.

На протяжении многих лет мы экспериментировали с запросами на вытягивание разного размера, от одного модуля до нескольких десятков, и в этот период мы обнаружили следующее:

• Запрос с одним файлом получает более качественный обзор
• Запросы с несколькими модулями сложнее для создателя, чтобы убедиться, что все отзывы были учтены
• Запросы с множеством модулей требуют гораздо больше усилий для проверки и, как правило, откладываются в сторону в пользу более простых для проверки запросов.

Вы можете подать до пяти запросов на вытягивание одновременно (5 запросов = 5 новых модулей) после объединения вашего первого запроса. Мы считаем, что этот размер группы является оптимальным для поддержания процесса проверки.

В заключение

Теперь, когда ваши модули интегрированы, нужно выполнить несколько задач по ведению учета.

Метаданные бота Обновите Ansibullbot, чтобы он знал, кого уведомлять, если/когда возникают ошибки или запросы на вытягивание по вашим модулям BOTMETA.yml.

Если нужно уведомить несколько человек, пожалуйста, перечислите их. Это поможет избежать ожидания от одного человека, который может быть недоступен по каким-либо причинам. Обратите внимание, что в BOTMETA.yml вы можете принять на себя ответственность за весь каталог.

Проверка веб-документации модуля Проверьте автоматически сгенерированную документацию модуля для каждого из ваших модулей, находящуюся в документации модулей, чтобы убедиться в правильности ее форматирования. Если есть какие-либо проблемы, исправьте их, создав отдельный запрос на вытягивание.

Если документация модуля еще не опубликована в сети, сообщите об этом участнику ядра Ansible в канале IRC #ansible-devel.

Новые в Git или GitHub

Мы понимаем, что это может быть ваше первое знакомство с Git или GitHub. Следующие руководства могут оказаться полезными:

• Как создать копию репозитория ansible/ansible
• Как синхронизировать (обновить) свою копию
• Как создать запрос на вытягивание (PR)

Обратите внимание, что в репозитории Ansible Git основная ветка называется devel вместо master, что используется в официальной документации GitHub.

После слияния вашего первого запроса на вытягивание убедитесь, что вы «синхронизировали свою вилку» с ansible/ansible, чтобы убедиться, что вы взяли структуру каталогов и совместно используемый код или документацию, созданные ранее.

Как указано в документации GitHub, всегда используйте ветки функций для своих запросов на вытягивание, никогда не вносите прямые изменения в devel.