Хостинг на GitLab

• Добавьте и зафиксируйте всё:

  $ git add -A && git commit -am "shard complete"
  

• Создайте проект GitLab с тем же name и description, что указаны в вашем файле shard.yml.

• Добавьте удалённый репозиторий: (не забудьте заменить <YOUR-GITLAB-USERNAME> и <YOUR-REPOSITORY-NAME> соответствующими значениями)

  $ git remote add origin https://gitlab.com/<YOUR-GITLAB-USERNAME>/<YOUR-REPOSITORY-NAME>.git
  

  или, если вы используете SSH

  $ git remote add origin git@gitlab.com:<YOUR-GITLAB-USERNAME>/<YOUR-REPOSITORY-NAME>.git
  

• Отправьте изменения:

  $ git push origin master
  

Пайплайны

Теперь настроим пайплайн GitLab, который будет запускать тесты и собирать/публиковать документацию при отправке кода в репозиторий.

Для этого просто добавьте следующий файл в корень репозитория и назовите его .gitlab-ci.yml

image: "crystallang/crystal:latest"

before_script:
  - shards install

cache:
  paths:
  - lib/

spec & format:
  script:
  - crystal spec
  - crystal tool format --check

pages:
  stage: deploy
  script:
  - crystal docs -o public src/palindrome-example.cr
  artifacts:
    paths:
    - public
  only:
  - master

Будут созданы две задачи. Первая называется "spec & format" (можно выбрать любое имя) и по умолчанию выполняется на этапе "test" пайплайна. Она просто запускает массив команд из script в новом экземпляре контейнера Docker, указанного в image. Скорее всего, вам понадобится зафиксировать версию Crystal для этого контейнера (ту, что указана в вашем shard.yml), но в этом примере мы просто используем тег latest.

Этап тестирования пайплайна либо завершится успешно (каждый элемент массива вернул код завершения, указывающий на успешное выполнение), либо завершится с ошибкой (один из элементов вернул ошибку).

Если он завершится успешно, пайплайн перейдёт ко второй задаче, определённой здесь, которую необходимо назвать "pages". Это специальная задача для публикации содержимого на вашем сайте GitLab Pages! Она выполняется после успешного завершения тестов, поскольку мы указали, что она должна запускаться на этапе "deploy". Она снова выполняет команды из script (на этот раз собирая документацию), но теперь мы указываем сохранить путь public (куда мы поместили документацию) как артефакт задачи.

Поскольку эта задача называется pages, документация помещена в каталог public и указана как artifact, GitLab опубликует сайт из этого каталога по URL-адресу по умолчанию https://<YOUR-GITLAB-USERNAME>.gitlab.io/<YOUR-REPOSITORY-NAME>.

Ключи before_script и cache в файле нужны для запуска одного и того же скрипта в каждой задаче (shards install) и сохранения созданных файлов (cache). Они не нужны, если у вашего shard нет зависимостей.

Если вы добавите приведённый выше файл в проект и отправите изменения, запустится первый запуск нового пайплайна.

$ git add -A && git commit -am 'Add .gitlab-ci.yml' && git push origin master

Несколько значков

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

Значок — это просто ссылка с изображением. Создадим ссылку на наш пайплайн и получим изображение значка из API значков пайплайна GitLab.

В разделе Badges общих настроек General сначала добавим значок выпуска. Ссылка: https://gitlab.com/<YOUR-GITLAB-USERNAME>/<YOUR-REPOSITORY-NAME>/pipelines, а URL изображения значка: https://gitlab.com/<YOUR-GITLAB-USERNAME>/<YOUR-REPOSITORY-NAME>/badges/master/pipeline.svg.

Теперь, когда пайплайн завершится, у нас будет документация, на которую можно добавить ссылку с помощью универсального значка из shields.io.

• Ссылка: https://<YOUR-GITLAB-USERNAME>.gitlab.io/<YOUR-REPOSITORY-NAME>
• Изображение: https://img.shields.io/badge/docs-available-brightgreen.svg

Выпуски

Выпуск — это специальный коммит в истории с именем (см. создание тегов).

Согласно файлу README Crystal Shards,

При установке библиотек из репозиториев Git ожидается, что в репозитории будут теги версий в формате, похожем на semver, с префиксом v. Примеры: v1.2.3, v2.0.0-rc1 или v2017.04.1

В GitLab также есть функция выпусков, позволяющая связать с этим тегом файлы и описание. Так вы можете, например, распространять двоичные файлы.

Как видно из документации по выпускам, можно создать аннотированный тег вместе с примечаниями к выпуску и файлами в интерфейсе:

или создать тег из командной строки следующим образом:

$ git tag -a v0.1.0 -m "Release v0.1.0"

отправьте его в репозиторий

$ git push origin master --follow-tags

а затем используйте интерфейс, чтобы добавить или отредактировать примечание к выпуску и прикрепить файлы.

Рекомендации

• Используйте параметр -a для создания аннотированного тега выпуска.
• Следуйте принципам семантического версионирования.

Значок выпуска

При желании можно также добавить значок shields.io для выпуска. GitLab не поддерживает такую функциональность в полной мере, и пока кто-нибудь не добавит в shields.io значок версии для GitLab, нам придётся указывать номер версии непосредственно в URL-адресах.

• Ссылка: https://img.shields.io/badge/release-<VERSION>-brightgreen.svg
• Изображение: https://img.shields.io/badge/release-<VERSION>-brightgreen.svg

где <VERSION> — это номер версии с префиксом v, например: v0.1.0.

Зеркало на GitHub

В настоящее время crystalshards.xyz использует только API GitHub, поэтому, если вы хотите, чтобы ваша библиотека индексировалась этим сервисом, можно настроить «зеркало отправки» из GitLab в GitHub.

1. Создайте репозиторий GitHub с тем же именем, что и ваш проект.
2. Следуйте инструкциям здесь: https://docs.gitlab.com/ee/workflow/repository_mirroring.html#setting-up-a-push-mirror-from-gitlab-to-github-core
3. Отредактируйте описание на GitHub. В результатах поиска crystalshards.xyz будут отображаться только первые несколько слов описания, а не вся строка, поэтому, например, можно использовать следующее
   • Описание: Слова, которые одинаково читаются в прямом и обратном порядке. Это зеркало:
   • Ссылка: https://gitlab.com///

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