Skip to content

Процесс деплоя

Jump to bottom
Anton Angelgardt edited this page Oct 18, 2024 · 6 revisions

Структура директории deploy

  • run.sh — корневой скрипт деплоя
  • modules — скрипты, отвечающие за рендеринг (_render.sh), деплой (_deploy.sh) или релиз (_release.sh), а также цветовое оформление консольных аутпутов (_set-colors.sh)
  • backup — бэкап предыдущего деплоя
  • logs — файлы логов рендеринга, деплоя и релиза
  • README.md — файл с краткой инструкцией

Структура директории docs

GitHub Pages строит сайт из директории docs, однако чтобы до релиза можно было просматривать самую последнюю версия, а также совместно вычитывать материалы, в директории предусмотрена следующая структура:

  • index.html — страница, которая открывается при запросе angelgardt.github.io/wlm-sdarp и содержит перенаправление на angelgardt.github.io/wlm-sdarp/cr, то есть на текущий релиз книги
  • cr — директория, содержащая текущий релиз книги (current release) — отдебаженную и вычитанную версию
  • dpl — директория, содержащая текущий деплой книги — версию, которая подлежит дебагингу и вычитке
  • prev — директория, содержащая предыдущие релизы книги на случай, если в текущий релиз всё же просочится какой-то суровый баг или же читатели после каких-либо больших обновлений захотят читать старую версию

Все указанные команды предполагают, что консоль смотрит в корень проекта — директорию wlm-sdarp, несмотря на то, что папка проекта книги — это book. Решено не загромождать папку book файлами, не относящимися непосредственно к книге.

Рендер, деплой и релиз делаются на ветке dev и вливаются в master через pull request на GitHub!

Рендер

В ходе разработки, безусловно, будет запущен локальный сервер для просмотра изменений, а значит многократно будет осуществлен рендер обновлений. Однако при желании есть возможность полностью снести папку book/_book и отрендерить всю книгу заново. Кроме того, рендер по умолчанию обновляет JSON-файлы квизов и листков, что может облегчить жизнь при их дебаге.

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

deploy/run.sh render

Что произойдет:

  • будет полностью удалена папка book/_book
  • книга будет полностью отрендерена с нуля
  • в папке logs будет создан лог рендеринга с названием render_<render-date>_<render-time>.log
    • дата и время вставляются автоматически

Рендер не коммитит изменения! Это необходимо сделать вручную! Рекомендуется выделить для этого отдельный коммит: сначала закоммитить все текущие изменения, затем запустит рендер, а после его завершения закоммитить с указанием в сообщении коммита, что это рендер.

Деплой

После того, как было внесено некоторое, логически замкнутое на себе, количество обновлений, можно деплойнуть версию, чтобы её можно было вычитывать и дебажить на стороне GitHub Pages. Для этого есть следующая команда:

deploy/run.sh deploy

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

Что произойдет:

  • результат деплоя будет помещен в папку docs/dpl
  • предыдущая версия деплоя будет перенесена в папку deploy/backup на случай, если что-то пойдет не так
  • в папке logs будет создан лог рендеринга с названием deploy_<deploy-date>_<deploy-time>.log
    • дата и время вставляются автоматически
  • по завершении деплоя будет открыт автоматически открыт файл README.md, в котором стоит задокументировать изменения этого деплоя

Деплой может быт выполнен несколько раз. Номер деплоя стоит обозначать в версии, отделив его двоеточием: Версия 0.0.1:8.

Деплой не коммитит изменения! Это необходимо сделать вручную! Необходимо выделить для этого отдельный коммит: сначала закоммитить все текущие изменения, затем запустит деплой, а после его завершения закоммитить с указанием в сообщении коммита, что это деплой.

Релиз

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

deploy/run.sh release

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

  • Версии не вставляются автоматически, чтобы был лишний повод проверить, что всё соответствует планам, а также служит имплицитным напоминанием, что в других места — index.qmd и _quarto.yml версию тоже надо поменять.
  • Предыдущая версия нужна для создания соответствующей подпапки в папке prev, где сохраняются предыдущие релизы.
  • Если на вопросы программы дан ответ N/No, релиз остановится.

Релиз не коммитит изменения! Это необходимо сделать вручную! Необходимо выделить для этого отдельный коммит: сначала закоммитить все текущие изменения, затем запустит рендер, а после его завершения закоммитить с указанием в сообщении коммита, что это релиз.

После релиза

После релиза на ветке dev выполняется pull request на GitHub, сливаются ветки и проставляется тег с указанием версии релиза.

Связаться с автором:
TG: @angelgardt
Email: [email protected]

Clone this wiki locally