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

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

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

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

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

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

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

Чит-лист по Git можно найти здесь. Подробная инструкция по Git доступна здесь.

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

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

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

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

• выполнить git clone с опцией --recurse-submodules,

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

• если git clone выполнен без --recurse-submodules, и вы хотите использовать разреженный и поверхностный checkout подмодулей, чтобы исключить ненужные файлы и историю в подмодулях для экономии места (примерно 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" (работа в процессе) в начале заголовка, его можно будет изменить позже. Это полезно для совместного рецензирования и обсуждения изменений, а также для запуска всех доступных тестов. Важно, чтобы вы предоставили краткое описание ваших изменений, оно позже будет использоваться для генерации changelog релиза.

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

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

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

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

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

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

В clickhouse-client:

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