Слияние кода завершено, страница обновится автоматически
Этот документ предназначен для сопровождающих DevDocs.
PR должны быть одобрены хотя бы одним сопровождающим перед слиянием.
Запросы на включение, которые добавляют или обновляют документацию, всегда должны быть собраны и протестированы локально, а файлы документов загружены командой thor docs:upload, прежде чем PR будет объединён на GitHub.
Этот рабочий процесс необходим, поскольку существует зависимость между локальной и производственной средами. Команда thor docs:download загружает документацию из производственных файлов, загруженных командой thor docs:upload. Если PR, добавляющий новую документацию, будет объединён и отправлен на GitHub до того, как файлы будут загружены в рабочую среду, команда thor docs:download завершится ошибкой для новой документации, и контейнер Docker не будет правильно собран, пока новая документация не будет развёрнута в рабочей среде.
Процесс обновления документации выглядит следующим образом:
thor docs:commit, описанную ниже).thor docs:upload (описана ниже).thor docs:clean (описана ниже).Примечание: изменения в файле public/docs/docs.json никогда не должны фиксироваться. Этот файл отражает, какая документация была загружена или сгенерирована локально, чего всегда нет при свежем клонировании репозитория.
Чтобы развернуть DevDocs, необходимо:
иметь доступ к Heroku, настроить интерфейс командной строки Heroku на своём компьютере и ознакомиться с пользовательским интерфейсом и интерфейсом командной строки Heroku, а также с интерфейсом New Relic (доступным через панель управления Heroku).
Иметь доступ к экземпляру Sentry DevDocs (для отслеживания ошибок JS) и ознакомиться с его пользовательским интерфейсом.
Получить учётные данные DevDocs S3 и установить (brew install awscli на macOS) и настроить AWS CLI на своём компьютере. В конфигурации должен быть добавлен именованный профиль под названием «devdocs»:
aws configure --profile devdocs
В дополнение к общедоступным командам, следующие команды предназначены для сопровождающих DevDocs:
thor docs:packageГенерирует пакеты для одной или нескольких документаций. Эти пакеты предназначены для загрузки в зону пакета S3 DevDocs сопровождающими с помощью команды thor docs:upload и загружаются пользователями с помощью команды thor docs:download.
Версии можно указать следующим образом: thor docs:package rails@5.2 node@10\ LTS.
Пакеты также могут быть автоматически сгенерированы во время процесса очистки, передав параметр --package команде thor docs:generate.
thor docs:uploadЭта команда выполняет две операции:
thor docs:download).Для работы команды у вас должен быть настроен AWS CLI, как указано выше.
Важно: приложение всегда должно быть развёрнуто сразу после завершения выполнения этой команды. Не запускайте эту команду, если вы не готовы к развёртыванию DevDocs.
Чтобы загрузить все документации, упакованные на вашем компьютере, выполните команду thor docs:upload --packaged. Чтобы протестировать конфигурацию и эффект от этой команды без загрузки чего-либо, используйте опцию --dryrun.
thor docs:commitКоманда быстрого доступа для создания коммита Git для данной документации после её обновления. Будут зафиксированы изменения скребка и файлов в папке assets/. Сообщение коммита будет включать самую последнюю версию, до которой была обновлена документация. Если некоторые файлы... Были пропущены коммитом, используйте git commit --amend, чтобы добавить их к коммиту. Команду можно запустить перед thor docs:upload, но коммит не должен быть отправлен в GitHub до того, как файлы были загружены и приложение развёрнуто.
thor docs:clean
Короткая команда для удаления всех файлов пакета (после загрузки через thor docs:upload они больше не нужны).После того как документы были загружены через thor docs:upload (если применимо), вы можете отправить изменения в основную ветку DevDocs (или объединить PR, содержащий обновления). Это запускает действие GitHub, которое начинается с запуска тестов. Если они пройдут успешно, приложение Heroku будет автоматически развёрнуто.
Если вы развёртываете обновления документации, убедитесь, что документация работает правильно после завершения развёртывания. Имейте в виду, что вам нужно подождать несколько секунд, пока сервисный работник завершит кэширование новых ресурсов. Вы должны увидеть уведомление «DevDocs был обновлён», когда кэширование будет завершено, после чего вам необходимо обновить страницу, чтобы увидеть изменения.
Если вы развёртываете изменения на фронтенде, отслеживайте Sentry на предмет новых ошибок JS после завершения развёртывания.
Если вы развёртываете серверные изменения, отслеживайте New Relic (доступный через панель управления Heroku) на предмет исключений Ruby и изменений пропускной способности или времени отклика после завершения развёртывания.
Если возникнет какая-либо проблема, запустите heroku rollback, чтобы откатить предыдущую версию приложения (это также можно сделать через пользовательский интерфейс Heroku). Обратите внимание, что это не вернёт изменения, внесённые в файлы документации, которые были загружены через thor docs:upload. Попробуйте исправить проблему как можно быстрее, а затем повторно разверните приложение. Обратитесь за помощью к другим сопровождающим, если вам нужна помощь.
Если это ваше первое развёртывание, убедитесь, что рядом есть другой сопровождающий, который может помочь.
Скомплектованные документы доступны по адресу downloads.devdocs.io, а сами документы — по адресу documents.devdocs.io. Запросы на загрузку и документы проксируются на S3-ведра devdocs-downloads.s3.amazonaws.com и devdocs-documents.s3.amazonaws.com соответственно.
Новые прокси-ВМ должны быть созданы из снимка devdocs-proxy. Прежде чем добавлять их в балансировщик нагрузки, необходимо добавить их IP-адреса в списки aws:SourceIp для обоих сегментов, иначе их запросы будут отклонены.
При создании новой прокси-VM и отсутствии снимка devdocs-proxy новая VM должна быть подготовлена следующим образом:
# нам нужен хотя бы nginx 1.19.x
wget https://nginx.org/keys/nginx_signing.key
apt-key add nginx_signing.key
echo 'deb https://nginx.org/packages/mainline/ubuntu/ focal nginx' >> /etc/apt/sources.list
echo 'deb-src https://nginx.org/packages/mainline/ubuntu/ focal nginx' >> /etc/apt/sources.list
apt-get -y remove nginx-common
apt-get -y update
apt-get -y install nginx
# конфиг на github
rm -rf /etc/nginx/*
rm -rf /etc/nginx/.* 2> /dev/null
git clone https://github.com/freeCodeCamp/devdocs-nginx-config.git /etc/nginx
# на этом этапе нам нужно добавить сертификаты от Cloudflare и протестировать конфиг
nginx -t
# если nginx уже запущен, просто
# ps aux | grep nginx
# найдите номер и убейте его
nginx
Следующие люди (раньше) поддерживали DevDocs:
Чтобы связаться, пожалуйста, напишите @freeCodeCamp/devdocs.
Хотите помочь поддерживать DevDocs? Приходите поговорить с нами на Discord :)
Кроме того, мы ценим большой вклад, сделанный этими замечательными людьми.
Вы можете оставить комментарий после Вход в систему
Неприемлемый контент может быть отображен здесь и не будет показан на странице. Вы можете проверить и изменить его с помощью соответствующей функции редактирования.
Если вы подтверждаете, что содержание не содержит непристойной лексики/перенаправления на рекламу/насилия/вульгарной порнографии/нарушений/пиратства/ложного/незначительного или незаконного контента, связанного с национальными законами и предписаниями, вы можете нажать «Отправить» для подачи апелляции, и мы обработаем ее как можно скорее.
Опубликовать ( 0 )