Предварительные требования

ClickHouse можно собирать на Linux, FreeBSD и macOS. Если вы используете Windows, вы все равно можете собрать ClickHouse в виртуальной машине с Linux, например, VirtualBox с Ubuntu.

Создание репозитория на GitHub

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

Далее, создайте форк репозитория ClickHouse в вашем личном аккаунте, нажав кнопку "fork" в правом верхнем углу.

Чтобы внести изменения, например, исправление проблемы или новую функциональность, сначала закоммитьте ваши изменения в ветку в вашем форке, затем создайте "Pull Request" с изменениями в основной репозиторий.

Для работы с Git-репозиториями установите Git. Например, в Ubuntu выполните:

Читать справочник по Git можно здесь. Подробное руководство по Git доступно здесь.

Клонирование репозитория на вашу рабочую машину

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

Эта команда создаст директорию ClickHouse/, содержащую исходный код, тесты и другие файлы. Вы можете указать пользовательский каталог для проверки после URL, но важно, чтобы этот путь не содержал пробелов, так как это может сломать сборку позже.

Git-репозиторий ClickHouse использует подмодули для подключения сторонних библиотек. Подмодули по умолчанию не проверяются. Вы можете либо

• запустить git clone с опцией --recurse-submodules,

• если git clone был запущен без --recurse-submodules, выполните git submodule update --init --jobs <N>, чтобы явно проверить все подмодули. (<N> можно установить, например, на 12, чтобы параллелизовать загрузку.)

• если git clone был запущен без --recurse-submodules, и вы хотите использовать разреженный и мелкий вывод подмодули, чтобы исключить ненужные файлы и историю в подмодулях для экономии места (около 5 ГБ вместо около 15 ГБ), выполните ./contrib/update-submodules.sh. Этот альтернативный вариант используется CI, но не рекомендуется для локальной разработки, так как делает работу с подмодулями менее удобной и медленной.

Чтобы проверить статус Git-подмодулей, выполните git submodule status.

Если вы получите следующее сообщение об ошибке:

то SSH-ключи для подключения к GitHub отсутствуют. Эти ключи обычно располагаются в ~/.ssh. Чтобы SSH-ключи были приняты, вам нужно загрузить их в настройках GitHub.

Вы также можете клонировать репозиторий через HTTPS:

Однако это не позволит вам отправлять ваши изменения на сервер. Вы все еще можете использовать его временно и добавить SSH-ключи позже, заменив адрес удаленного репозитория с помощью команды git remote.

Вы также можете добавить оригинальный адрес репозитория ClickHouse в ваш локальный репозиторий, чтобы получать обновления оттуда:

После успешного выполнения этой команды вы сможете получать обновления из основного репозитория ClickHouse, выполнив git pull upstream master.

подсказка

Пожалуйста, не используйте дословно git push, вы можете выполнить пуш в неправильный удаленный репозиторий и/или неправильную ветку. Лучше указывать интересно и ветку отдельно, например, git push origin my_branch_name.

Написание кода

Ниже приведены некоторые быстрые ссылки, которые могут быть полезными при написании кода для ClickHouse:

• Архитектура ClickHouse.
• Руководство по стилю кода.
• Сторонние библиотеки
• Написание тестов
• Открытые проблемы

IDE

Visual Studio Code и Neovim – два варианта, которые хорошо зарекомендовали себя в прошлом для разработки ClickHouse. Если вы используете VS Code, мы рекомендуем использовать расширение clangd для замены IntelliSense, так как оно гораздо более производительное.

CLion – еще одна отличная альтернатива. Однако он может работать медленнее на крупных проектах, таких как ClickHouse. Несколько моментов, которые следует учитывать при использовании CLion:

• CLion создает путь build самостоятельно и автоматически выбирает debug для типа сборки
• Он использует версию CMake, которая определена в CLion, а не ту, которая установлена вами
• CLion будет использовать make для выполнения сборочных задач вместо ninja (это нормальное поведение)

Другие IDE, которые вы можете использовать, включают Sublime Text, Qt Creator или Kate.

Создание Pull Request

Перейдите к вашему форку репозитория в интерфейсе GitHub. Если вы разрабатывали в ветке, вам нужно выбрать эту ветку. На экране будет кнопка "Pull request". По сути, это значит "создать запрос на принятие моих изменений в основной репозиторий".

Pull request может быть создан даже если работа еще не завершена. В этом случае, пожалуйста, добавьте слово "WIP" (работа в процессе) в начале заголовка, его можно будет изменить позже. Это полезно для совместного просмотра и обсуждения изменений, а также для запуска всех доступных тестов. Важно предоставить краткое описание ваших изменений, оно будет позже использовано для генерации изменений в релизах.

Тестирование начнется, как только сотрудники ClickHouse пометят ваш PR тегом "можно протестировать". Результаты некоторых первых проверок (например, стиль кода) поступят в течение нескольких минут. Результаты проверки сборки придут в течение получаса. Основной набор тестов сообщит о себе в течение часа.

Система подготовит бинарные сборки ClickHouse для вашего pull request индивидуально. Чтобы получить эти сборки, нажмите ссылку "Details" рядом с записью "Builds" в списке проверок. Там вы найдете прямые ссылки на собранные .deb пакеты ClickHouse, которые вы можете развернуть даже на ваших производственных серверах (если вы не боитесь).

Написание документации

Каждый pull request, который добавляет новую функциональность, должен сопровождаться соответствующей документацией. Если вы хотите просмотреть изменения в вашей документации, инструкции по построению страницы документации локально доступны в файле README.md здесь. При добавлении новой функции в ClickHouse вы можете использовать приведенный ниже шаблон в качестве руководства:

Использование тестовых данных

Разработка ClickHouse часто требует загрузки реалистичных наборов данных. Это особенно важно для тестирования производительности. У нас есть специально подготовленный набор анонимизированных данных веб-аналитики. Он требует дополнительно около 3 ГБ свободного дискового пространства.

В clickhouse-client:

Импортируйте данные: