Источник Руководящие принципы для библиотек

Этот документ описывает общие рекомендации для тех, кто пишет и публикует библиотеки Elixir, предназначенные для использования другими разработчиками.

Начало работы

Вы можете создать новую библиотеку Elixir, выполнив команду mix new:

$ mix new my_library

Имя проекта указывается в формате snake_case (все буквы строчные, слова разделены символом подчеркивания). Этот же формат используется для переменных, имён функций и атомов в Elixir. Дополнительную информацию можно найти в документе Правила именования.

Каждый проект имеет файл mix.exs, содержащий инструкции по сборке, компиляции, запуску тестов и т. д. Библиотеки обычно содержат каталог lib, который включает исходный код Elixir, и каталог test. Также может существовать каталог src для источников Erlang.

Команда mix new также поддерживает опцию --sup для создания нового проекта со встроенным деревом надзора. Дополнительную информацию о запуске проекта можно найти в официальном руководстве Mix & OTP или в документации Mix.

Публикация

Написание кода — лишь первый из многих шагов по публикации пакета. Мы настоятельно рекомендуем разработчикам:

• Выбрать схему версионирования. Elixir требует версий в формате MAJOR.MINOR.PATCH, но значение этих чисел определяется вами. Большинство проектов выбирают Семантическое версионирование.

• Выбрать лицензию. Наиболее распространёнными лицензиями в сообществе Elixir являются MIT License и Apache License 2.0. Последняя также используется в самом Elixir.

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

• Написать тесты. Elixir поставляется с тестовой средой под названием ExUnit. Сгенерированный проектом mix new проект включает примеры тестов и doctests.

• Написать документацию. Сообщество Elixir гордится тем, что документация является важным элементом и легко доступна. Библиотеки поддерживают этот подход, предоставляя полную документацию API с примерами для модулей, типов и функций. Дополнительную информацию см. в главе Написание документации руководства по началу работы. Такие проекты, как ExDoc, могут использоваться для генерации HTML- и EPUB-документов из документации. ExDoc также поддерживает «дополнительные страницы», например эту, которую вы читаете. Такие страницы дополняют документацию учебниками, руководствами, справочниками и даже шпаргалками.

• Следовать лучшим практикам. Проект Elixir документирует ряд антипаттернов, которых следует избегать в вашем коде. Особое внимание авторам библиотек следует уделить антипаттернам, связанным с процессами и антипаттернам, связанным с макросами.

Проекты часто становятся доступными другим разработчикам путём публикации пакета Hex. Hex также поддерживает частные пакеты для организаций. Если ExDoc настроен для проекта Mix, публикация пакета на Hex также автоматически опубликует сгенерированную документацию на HexDocs.

Управление зависимостями

Когда ваша библиотека публикуется и используется как зависимость, её файл блокировки (обычно с именем mix.lock) игнорируется проектом-хостом. Выполнение команды mix deps.get в проекте-хосте пытается получить последние возможные версии зависимостей вашей библиотеки, как указано в разделе deps вашего mix.exs. Эти версии могут быть больше, чем те, которые хранятся в вашем файле mix.lock (и, следовательно, используются в ваших тестах/CI).

С другой стороны, авторы вашей библиотеки нуждаются в детерминированной сборке, что подразумевает наличие mix.lock в вашей системе управления версиями (VCS).

Лучшей практикой управления файлом mix.lock является его хранение в VCS и выполнение двух различных рабочих процессов непрерывной интеграции (CI): обычный детерминированный и другой, который начинается с mix deps.unlock --all и всегда компилирует вашу библиотеку и запускает тесты с использованием последних версий зависимостей. Последний может выполняться даже ежедневно или периодически, чтобы оставаться в курсе возможных проблем с обновлениями зависимостей.