Создание Shard-пакетов

Как создавать и выпускать Shard-пакеты Crystal.

Что такое Shard-пакет?

Проще говоря, Shard-пакет — это пакет кода на Crystal, предназначенный для совместного использования и применения в других проектах.

Подробности см. в разделе команда Shards.

Введение

В этом руководстве мы создадим библиотеку Crystal под названием palindrome-example.

Для тех, кто не знает: палиндром — это слово, которое одинаково читается слева направо и справа налево. Например: топот, дед, комок, шалаш, казак.

Требования

Чтобы выпустить Shard-пакет Crystal и следовать этому руководству, вам потребуется:

• Рабочая установка компилятора Crystal
• Рабочая установка Git
• Учётная запись GitHub или GitLab

Создание проекта

Для начала используйте команду init lib компилятора Crystal, чтобы создать библиотеку Crystal со стандартной структурой каталогов.

В терминале: crystal init lib <YOUR-SHARD-NAME>

Например:

$ crystal init lib palindrome-example
    create  palindrome-example/.gitignore
    create  palindrome-example/.editorconfig
    create  palindrome-example/LICENSE
    create  palindrome-example/README.md
    create  palindrome-example/shard.yml
    create  palindrome-example/src/palindrome-example.cr
    create  palindrome-example/spec/spec_helper.cr
    create  palindrome-example/spec/palindrome-example_spec.cr
Initialized empty Git repository in /<YOUR-DIRECTORY>/.../palindrome-example/.git/

...затем cd в этот каталог:

Например:

cd palindrome-example

Затем выполните add и commit, чтобы начать отслеживать файлы с помощью Git:

$ git add -A
$ git commit -am "First Commit"
[master (root-commit) 77bad84] First Commit
 8 files changed, 104 insertions(+)
 create mode 100644 .editorconfig
 create mode 100644 .gitignore
 create mode 100644 LICENSE
 create mode 100644 README.md
 create mode 100644 shard.yml
 create mode 100644 spec/palindrome-example_spec.cr
 create mode 100644 spec/spec_helper.cr
 create mode 100644 src/palindrome-example.cr

Написание кода

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

Тестирование кода

• Тестируйте свой код. Весь код. Это единственный способ узнать, работает ли он, и касается это всех, включая вас.
• В Crystal есть встроенная библиотека для тестирования. Используйте её!

Документация

• Документируйте код с помощью комментариев. Весь код. Даже приватные методы.
• В Crystal есть встроенный генератор документации. Используйте его!

Выполните crystal docs, чтобы преобразовать код и комментарии в связанную перекрёстными ссылками документацию API. Открывайте файлы из каталога /docs/ в браузере, чтобы следить за тем, как выглядит ваша документация.

Инструкции по размещению документации, сгенерированной компилятором, на GitHub/GitLab Pages приведены ниже.

Когда документация будет готова и доступна, можно добавить значок документации в репозиторий, чтобы пользователи знали о её наличии. В GitLab этот значок относится к проекту, поэтому мы рассмотрим его в инструкциях для GitLab ниже. На GitHub обычно размещают такой значок под описанием в README.md: (Не забудьте заменить <LINK-TO-YOUR-DOCUMENTATION> соответствующим значением.)

[![Docs](https://img.shields.io/badge/docs-available-brightgreen.svg)](<LINK-TO-YOUR-DOCUMENTATION>)

Создание файла README

Хороший файл README может как обеспечить успех проекта, так и погубить его. Awesome README — отличная подборка примеров и материалов по этой теме.

Самое важное — README должен объяснять:

1. Что представляет собой ваша библиотека
2. Что она делает
3. Как ей пользоваться

Это описание должно содержать несколько примеров и подзаголовки.

Стиль кода

• Можно придерживаться собственного стиля, но соблюдение основных рекомендаций, определённых командой Crystal, поможет сделать код последовательным, читаемым и удобным для других разработчиков.
• Используйте встроенный форматтер кода Crystal, чтобы автоматически форматировать все файлы .cr в каталоге.

Например:

crystal tool format

Чтобы проверить, правильно ли отформатирован ваш код, или убедиться, что форматтер не внесёт никаких изменений, просто добавьте --check в конец этой команды.

Например:

crystal tool format --check

Эту проверку полезно добавить в качестве шага в непрерывную интеграцию.

Создание shard.yml

Спецификация — ваше руководство. Следуйте ей.

Название

Свойство name в shard.yml должно быть кратким и информативным.

• Поищите на сайте crystalshards.xyz, чтобы проверить, не занято ли уже выбранное название.

Например:

name: palindrome-example

Описание

Добавьте description в shard.yml.

description — это краткое описание в одну строку, по которому можно найти ваш Shard-пакет.

Описание должно быть:

1. Информативным
2. Помогающим найти проект

Оптимизация

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

Одни люди ищут точно такую функциональность, как у нашей библиотеки, другие — общую функциональность. Например, Бобу нужна библиотека для палиндромов, Фелипе ищет библиотеки, связанные с текстом, а Сьюзен — библиотеки, связанные с правописанием.

Наше name уже достаточно информативно для поиска Боба по слову «палиндром». Повторять ключевое слово палиндром не нужно. Вместо этого мы охватим поиск Сьюзен по слову «правописание» и поиск Фелипе по слову «текст».

description: |
  A textual algorithm to tell if a word is spelled the same way forwards as it is backwards.

Размещение

Дальнейшие инструкции различаются в зависимости от того, размещаете ли вы репозиторий на GitHub или GitLab. Если вы используете другой сервис, можете написать руководство и добавить его в эту книгу!

• Размещение на GitHub
• Размещение на GitLab