Непрерывная интеграция (CI)

Когда вы отправляете pull request, система непрерывной интеграции (CI) ClickHouse запускает для вашего кода ряд автоматических проверок. Это происходит после того, как мейнтейнер репозитория (кто-то из команды ClickHouse) просмотрит ваш код и добавит к вашему pull request метку can be tested. Результаты проверок отображаются на странице pull request в GitHub, как описано в документации GitHub о проверках. Если какая-либо проверка завершается ошибкой, вам может потребоваться её исправить. На этой странице приведён обзор проверок, с которыми вы можете столкнуться, и того, что можно сделать для их исправления. Если похоже, что сбой проверки не связан с вашими изменениями, это может быть временный сбой или проблема с инфраструктурой. Отправьте пустой коммит в pull request, чтобы перезапустить проверки CI:

git commit --allow-empty
git push

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

Слияние с master

Проверяет, можно ли слить PR с веткой master. Если нет, проверка завершится с сообщением Cannot fetch mergecommit. Чтобы эта проверка прошла, разрешите конфликт слияния, как описано в документации GitHub, или слейте ветку master в ветку вашего pull request с помощью git.

Проверка документации

Пытается собрать сайт документации ClickHouse. Проверка может завершиться ошибкой, если вы внесли изменения в документацию. Наиболее вероятная причина — некорректная перекрёстная ссылка в документации. Перейдите к отчёту о проверке и найдите сообщения ERROR и WARNING.

Проверка описания

Проверьте, что описание вашего pull request соответствует шаблону PULL_REQUEST_TEMPLATE.md. Вы должны указать категорию в changelog для вашего изменения (например, Bug Fix) и написать понятное пользователю сообщение с описанием этого изменения для CHANGELOG.md

Docker-образ

Собирает Docker-образы сервера ClickHouse и Keeper, чтобы убедиться, что их сборка проходит корректно.

Тесты официальной библиотеки Docker

Запускаются тесты из официальной библиотеки Docker, чтобы убедиться, что Docker-образ clickhouse/clickhouse-server работает корректно. Чтобы добавить новые тесты, создайте каталог ci/jobs/scripts/docker_server/tests/$test_name и поместите в него скрипт run.sh. Дополнительные сведения о тестах можно найти в документации по скриптам CI-задач.

Проверка маркера

Эта проверка означает, что система CI начала обрабатывать pull request. Статус ‘pending’ означает, что запущены ещё не все проверки. После запуска всех проверок статус изменится на ‘success’.

Проверка стиля

Выполняет различные проверки стиля кодовой базы. Базовые проверки в задаче Style Check:

cpp

Выполняет простые проверки стиля кода на основе регулярных выражений с помощью скрипта ci/jobs/scripts/check_style/check_cpp.sh (его также можно запускать локально). Если проверка завершилась ошибкой, исправьте проблемы со стилем в соответствии с руководством по стилю кода.

codespell, aspell

Проверьте текст на грамматические ошибки и опечатки.

mypy

Выполняет статическую проверку типов кода Python.

Запуск задачи проверки стиля локально

Всю задачу проверки стиля можно запустить локально в контейнере Docker с помощью:

python -m ci.praktika run "Style check"

Чтобы запустить конкретную проверку (например, cpp):

python -m ci.praktika run "Style check" --test cpp

Эти команды загружают Docker-образ clickhouse/style-test и запускают задачу в контейнерной среде. Никаких дополнительных зависимостей, кроме Python 3 и Docker, не требуется.

Запуск тестов без сохранения состояния

Локально установленный ClickHouse с настройками по умолчанию может подойти для отдельных тестовых сценариев, но не позволяет корректно выполнять все тестовые запросы. В CI для каждой задачи применяется определённая конфигурация ClickHouse (например, хранилище S3, параллельные реплики), и вручную воспроизвести её бывает затруднительно. Чтобы этого избежать, вы можете локально воспроизвести любую задачу CI, используя ту же оркестрацию, что и в CI, — ручная настройка не требуется.

Необходимые условия

Python 3 (только стандартная библиотека)
Docker

При необходимости установите Docker в Ubuntu и войдите в систему заново:

sudo apt-get update
sudo apt-get install docker.io
sudo usermod -aG docker "$USER"
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "ipv6": true,
  "ip6tables": true
}
EOF
sudo systemctl restart docker

Запустите задачу CI локально

Выберите любое название задачи из отчёта CI и запустите её локально:

python -m ci.praktika run "<JOB_NAME>"

Всегда указывайте имя задачи в кавычках и в точности так, как оно приведено в отчёте CI (оно может содержать пробелы и запятые), например: "Stateless tests (amd_debug, parallel)". Это задаёт ту же конфигурацию ClickHouse и запускает те же тесты, что и в CI.
Архитектура и тип сборки в имени задачи (например, amd_debug) — это метки, специфичные для CI. При локальном запуске они ни на что не влияют: задача будет использовать тот бинарный файл, который вы указали, и ту архитектуру, на которой вы её запускаете. Имя задачи определяет только конфигурацию ClickHouse и набор тестов (если это не переопределено через --test).
В CI функциональные тесты разделены на батчи для более эффективного использования ресурсов. Например, "Stateless tests (amd_debug, parallel)" и "Stateless tests (amd_debug, sequential)" вместе охватывают весь объём: тесты, безопасные для параллельного запуска, выполняются одновременно, а остальные — последовательно. Такое разделение сокращает общее время CI, максимально используя параллелизм там, где это возможно. Чтобы локально воспроизвести полный набор тестов, запустите оба батча.
Также есть задача CI "Fast test", которая запускает ограниченный набор функциональных тестов для проверки базовой работоспособности ClickHouse. Она использует сборку не со всеми необязательными модулями и позволяет быстрее всего обнаружить регрессии. Её можно запустить локально тем же способом. Поместите бинарный файл ClickHouse в один из стандартных путей поиска (./ci/tmp/clickhouse, ./build/programs/clickhouse или ./clickhouse) — иначе задача сначала попытается собрать ClickHouse:
```
python -m ci.praktika run "Fast test"
```

Запуск отдельных тестов в рамках задачи CI

С --test задача подготавливает ту же конфигурацию ClickHouse, что используется в CI, но запускает только выбранные тесты:

python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
  --test 00001_select1

Можно указать несколько имен тестов:

python -m ci.praktika run "Stateless tests (amd_debug, parallel)" \
  --test 00001_select1 00002_log_and_exception_messages_formatting

Совет: если подходит любая конфигурация ClickHouse и вам нужно запустить только определенные тесты, используйте псевдоним functional вместо полного имени задачи:
```
python -m ci.praktika run functional --test 00001_select1
```

Дополнительные параметры настройки

--path PATH — пользовательский путь к бинарному файлу ClickHouse. По умолчанию runner ищет в следующем порядке: ./ci/tmp/clickhouse, ./build/programs/clickhouse, ./clickhouse.
--count N — повторить каждый тест N раз.
--workers N — переопределить автоматический расчёт числа параллельных воркеров на основе ресурсов машины.

Проверка сборки

Сборка ClickHouse в различных конфигурациях для использования на следующих этапах.

Локальный запуск сборок

Сборки можно запускать локально в среде, близкой к CI, с помощью:

python -m ci.praktika run "<BUILD_JOB_NAME>"

Никаких зависимостей, кроме Python 3 и Docker, не требуется.

Доступные задачи сборки

Названия задач сборки в точности совпадают с тем, как они указаны в отчёте CI: Сборки AMD64:

Build (amd_debug) - Отладочная сборка с символами
Build (amd_release) - Оптимизированная релизная сборка
Build (amd_asan) - Сборка с Address Sanitizer
Build (amd_tsan) - Сборка с Thread Sanitizer
Build (amd_msan) - Сборка с Memory Sanitizer
Build (amd_ubsan) - Сборка с Undefined Behavior Sanitizer
Build (amd_binary) - Быстрая релизная сборка без Thin LTO
Build (amd_compat) - Сборка для старых систем
Build (amd_musl) - Сборка с musl libc
Build (amd_darwin) - Сборка для macOS
Build (amd_freebsd) - Сборка для FreeBSD

Сборки ARM64:

Build (arm_release) - Оптимизированная релизная сборка ARM64
Build (arm_asan) - Сборка ARM64 с Address Sanitizer
Build (arm_coverage) - Сборка ARM64 с инструментированием для анализа покрытия
Build (arm_binary) - Быстрая релизная сборка ARM64 без Thin LTO
Build (arm_darwin) - Сборка ARM64 для macOS
Build (arm_v80compat) - Сборка для совместимости с ARMv8.0

Другие архитектуры:

Build (ppc64le) - PowerPC 64-bit Little Endian
Build (riscv64) - 64-разрядная RISC-V
Build (s390x) - 64-разрядная IBM System/390
Build (loongarch64) - 64-разрядная LoongArch

Если задача завершается успешно, результаты сборки будут доступны в каталоге <repo_root>/ci/tmp/build. Примечание: Для сборок, не относящихся к категории “Другие архитектуры” (в которой используется кросс-компиляция), архитектура локальной машины должна соответствовать типу сборки, чтобы получить сборку, указанную в BUILD_JOB_NAME.

Пример

Чтобы запустить локальную отладочную сборку:

python -m ci.praktika run "Build (amd_debug)"

Если описанный выше подход вам не подходит, используйте параметры cmake из журнала сборки и следуйте общей процедуре сборки.

Функциональные тесты без сохранения состояния

Запускает функциональные тесты без сохранения состояния для бинарных файлов ClickHouse, собранных в различных конфигурациях — release, debug, с санитайзерами и т. д. Посмотрите отчет, чтобы понять, какие тесты завершаются ошибкой, а затем воспроизведите сбой локально, как описано здесь. Обратите внимание: для воспроизведения нужно использовать правильную конфигурацию сборки — тест может завершаться ошибкой с AddressSanitizer, но проходить в Debug. Скачайте бинарный файл со страницы CI build checks или соберите его локально.

Интеграционные тесты

Запускает интеграционные тесты.

Проверка валидации исправления ошибки

Проверяет, что либо добавлен новый тест (функциональный или интеграционный), либо есть изменённые тесты, которые завершаются ошибкой при запуске с бинарным файлом, собранным из ветки master. Эта проверка запускается, когда у pull request есть метка “pr-bugfix”.

Стресс-тест

Запускает функциональные тесты без сохранения состояния одновременно с нескольких клиентов, чтобы выявить ошибки, связанные с параллелизмом. Если тест завершается сбоем:

Сначала устраните все остальные сбои тестов;
- Просмотрите отчет, чтобы найти журналы сервера, и проверьте их на наличие возможных причин ошибки.

Проверка совместимости

Проверяет, запускается ли бинарный файл clickhouse в дистрибутивах со старыми версиями libc. Если нет, обратитесь за помощью к мейнтейнеру.

AST-фаззер

Запускает случайно сгенерированные запросы, чтобы выявлять ошибки в программе. Если он завершается сбоем, обратитесь за помощью к мейнтейнеру.

Тесты производительности

Оценивайте изменения в производительности запросов. Это самая длительная проверка, её выполнение занимает чуть менее 6 часов. Отчёт о тестах производительности подробно описан здесь.

​Слияние с master

​Проверка документации

​Проверка описания

​Docker-образ

​Тесты официальной библиотеки Docker

​Проверка маркера

​Проверка стиля

cpp

codespell, aspell

mypy

​Запуск задачи проверки стиля локально

​Запуск тестов без сохранения состояния

​Необходимые условия

​Запустите задачу CI локально

​Запуск отдельных тестов в рамках задачи CI

​Дополнительные параметры настройки

​Проверка сборки

​Локальный запуск сборок

​Доступные задачи сборки

​Пример

​Функциональные тесты без сохранения состояния

​Интеграционные тесты

​Проверка валидации исправления ошибки

​Стресс-тест

​Проверка совместимости

​AST-фаззер

​Тесты производительности