Crystal Programming. Введение на основе проекта в создание эффективных, безопасных и читаемых веб-приложений и приложений CLI

Отсюда вы можете рассмотреть возможность добавления некоторых правил защиты ветвей, например, http://docs.github.com/en/rePositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches#require-status-checks-before-merging, чтобы потребовать прохождения определенных проверок перед объединением запроса на включение.

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

Развертывание документации

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

В примере, который мы собираемся рассмотреть, я размещу документацию на веб-сайте https://pages.github.com, только с последней версией, без каких-либо внешних зависимостей. Таким образом, вам нужно будет обязательно настроить GitHub Pages для вашего репозитория.

Совет

см. https://docs.github.com/en/pages/quickstart для получения дополнительной информации о том, как это настроить.

Теперь, когда с этим покончено, мы можем перейти к настройке рабочего процесса! Поскольку развертывание документации — это то, что должно произойти только после публикации новой версии, мы собираемся создать для этого специальный рабочий процесс. Начните с создания файла deployment.yml в папке workflows. В этот файл можно добавить следующее содержимое:

name: Deployment

on:

  release:

    types:

      - created

jobs:

  deploy_docs:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v2

      - name: Install Crystal

      uses: crystal-lang/install-crystal@v1

      - name: Build

      run: crystal docs

      - name: Deploy

      uses: JamesIves/github-pages-deploy-action@4.1.5

      with:

        branch: gh-pages

        folder: docs

        single-commit: true

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

Поэтапно мы проверяем код, устанавливаем Crystal, создаем документацию, запуская crystal docs, и, наконец, загружаем документацию на GitHub Pages.

Мы используем внешнее действие для развертывания документации. Есть немало других действий, которые поддерживают это, или вы также можете сделать это вручную, но я обнаружил, что это работает довольно хорошо и его легко настроить. Вы можете проверить https://github.com/JamesIves/github-pages-deploy-action для получения дополнительной информации об этом действии.

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

Кроме того, поскольку Crystal Docs выводит результаты в папку docs/, я указал ее в качестве исходной папки. Я также устанавливаю для опции single-commit значение true. По сути, это сбрасывает историю нашей ветки, так что в этой ветке всегда остается только один коммит. В нашем случае это нормально, поскольку при необходимости документацию можно легко восстановить, поэтому нет необходимости хранить эту историю.