Внесение вклада в Quickwit

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

Отправка PR

Проверьте, нет ли вашего вопроса в списке на GitHub. Если нет, создайте свой собственный вопрос.

Добавьте следующее выражение в конце вашего коммита Закрывает #<Номер вопроса>. Это автоматически создаст ссылку на ваш PR в странице вопроса. Также, после того как ваш PR будет включен, вопрос будет закрыт. Если ваш PR частично решает вопрос и вы хотите оставить его открытым, просто напишите См. #<Номер вопроса>.

Не стесняйтесь отправлять свой вклад в незавершенном состоянии для получения ранней обратной связи. В этом случае просто пометьте PR тегом [WIP] (что означает работу в процессе).

Проверки PR

Когда вы отправляете pull request в проект, система CI выполняет несколько проверок. После того как ваш PR будет включен, будет выполнена более полная проверка.Вы будете уведомлены по электронной почте от системы CI, если будут обнаружены какие-либо проблемы, но если вы хотите выполнить эти проверки локально перед отправкой PR или для проверки изменений, вы можете использовать следующие команды в корневом каталоге:

1. Чтобы проверить, проходят ли все тесты, выполните make test-all.
2. Чтобы исправить стиль кода и форматирование, а также выявить общие ошибки, выполните make fix. В качестве альтернативы выполните make -k test-all docker-compose-down, чтобы завершить Docker-сервисы после выполнения всех тестов.
3. Чтобы построить документацию, выполните make build-rustdoc.# Разработка

Настройка и запуск тестов

Локальное развитие

1. Установите Rust, CMake, Docker (https://docs.docker.com/engine/install/) и Docker Compose (https://docs.docker.com/compose/install/)
2. Установите node@20 и выполните команду npm install -g yarn
3. Установите awslocal (https://github.com/localstack/awscli-local)
4. Установите protoc (https://grpc.io/docs/protoc-installation/) (может потребоваться установить последние бинарные файлы, а не версию вашего дистрибутива)
5. Установите nextest (https://nexte.st/docs/installation/pre-built-binaries/)

GitHub Codespaces

GitHub Codespaces предоставляет полностью настроенную среду разработки в облаке, что делает начало работы с разработкой Quickwit простым. Нажав на значок выше, вы можете создать codespace с установленными и настроенными всеми необходимыми инструментами.

Запуск тестов

Запустите make test-all, чтобы запустить все тесты.## Полезные команды

• make test-all - запускает необходимые Docker службы и выполняет все тесты.
• make -k test-all docker-compose-down - то же самое, но завершает Docker службы после выполнения всех тестов.
• make fmt - запускает форматтер, эта команда требует установки nightly toolchain с помощью команды rustup toolchain install nightly.
• make fix - запускает форматтер и проверки clippy.
• make typos - запускает инструмент проверки орфографии по всему коду. (Установите с помощью команды cargo install typos-cli)
• make doc - создаёт документацию.
• make docker-compose-up - запускает Docker службы.
• make docker-compose-down - останавливает Docker службы.
• make docker-compose-logs - показывает логи Docker.## Запуск UI

1. Переключитесь в подкаталог quickwit проекта и создайте каталог данных qwdata там, если он ещё не существует.
2. Запустите сервер cargo r run --config ../config/quickwit.yaml.
3. yarn --cwd quickwit-ui install и yarn --cwd quickwit-ui start.
4. Откройте ваш браузер по адресу http://localhost:3000/ui, если он не откроется автоматически.

Запуск тестов UI

1. Запустите yarn --cwd quickwit-ui install и yarn --cwd quickwit-ui test в каталоге quickwit.

Запуск UI e2e тестов

1. Убедитесь, что запущен поисковый сервер cargo r run --service searcher --config ../config/quickwit.yaml.
2. Запустите yarn --cwd quickwit-ui e2e-test.

Запуск служб, таких как Amazon Kinesis или S3, Kafka или PostgreSQL локально.

1. Убедитесь, что Docker и Docker Compose правильно установлены на вашем компьютере (см. выше).
2. Запустите make docker-compose-up для запуска всех служб или make docker-compose-up DOCKER_SERVICES=kafka,postgres для запуска подмножества служб.

Трассировка с помощью Jaeger

1. Убедитесь, что Docker и Docker Compose правильно установлены на вашем компьютере (см. выше).
2. Запустите службы Jaeger (UI, collector, agent, ...) с помощью команды make docker-compose-up DOCKER_SERVICES=jaeger.
3. Запустите Quickwit с помощью следующих переменных окружения:

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
QW_ENABLE_OPENTELEMETRY_OTLP_EXPORTER=true

4. Откройте ваш браузер и перейдите на localhost:16686## Использование консоли tokio
5. Установите tokio-console, запустив cargo install tokio-console.
6. Установите бинарный файл quickwit в папку quickwit-cli командой RUSTFLAGS="--cfg tokio_unstable" cargo install --path . --features tokio-console.
7. Запустите долгоживущую команду, такую как индексирование, и активируйте tokio с помощью переменной окружения: QW_ENABLE_TOKIO_CONSOLE=1 quickwit index ....
8. Запустите tokio-console.## Сборка бинарников

В настоящее время мы используем cross для сборки бинарников Quickwit для различных архитектур. Для этого нам пришлось настроить docker-образы, используемые cross. Эти настройки можно найти в файлах Docker, расположенных в папке ./cross-images. Чтобы заставить cross учитывать любые изменения в этих файлах Docker, вам нужно будет собрать и отправить образы на Docker Hub, запустив make cross-images.

У нас также есть ночное сборочное окно, которое отправляет образы на Docker Hub. Это помогает постоянно проверять, что наши бинарники все еще собираются даже при обновлениях внешних зависимостей. Успешные сборки позволяют получить доступ к артефактам в течение следующих трёх дней. Бинарники релизов всегда имеют прикрепленные к ним артефакты.

Docker-образы

Каждое слияние в ветке main запускает сборку нового Docker-образа, доступного на DockerHub по адресу quickwit/quickwit:edge. Тегирование коммита также создает новый образ quickwit/quickwit:<tag name>, если имя тега начинается с v* или qw*. Docker-образы основаны на Debian.

Примечания по встроенному UI

Так как react-UI встроен в бинарник Rust, нам нужно собрать react-приложение перед сборкой бинарника. Поэтому make cross-image зависит от команды build-ui.

Тестирование релизов (альфа, бета, rc)Следующая команда установки Quickwit curl -L https://install.quickwit.io | sh всегда устанавливает последнюю стабильную версию Quickwit. Чтобы облегчить установку и тестирование новых (альфа, бета, rc) релизов, вы можете вручную вытянуть и выполнить скрипт как ./install.sh --allow-any-latest-version. Это заставит скрипт установить любую последнюю доступную версию пакета.## Отслеживание лицензий

Мы отслеживаем лицензии, используемые открытыми исходными crate'ами, используемыми этим проектом, с помощью rust-license-tool. Список проверяется каждый раз, когда запускается CI. Чтобы обновить список, установите инструмент с помощью cargo install --git https://github.com/DataDog/rust-license-tool и затем выполните dd-rust-license-tool write. Если возникли ошибки, возможно, вам потребуется обновить список исключений в license-tool.toml.

Документация

Документация Quickwit находится в директории docs.

Генерация документации для CLI.

Страница документации CLI частично генерируется с помощью скрипта. Чтобы обновить её, сначала запустите скрипт:

cargo run --bin generate_markdown > ../docs/reference/cli_insert.md

Затем вручную отредактируйте страницу документации, чтобы обновить её и удалите сгенерированный файл. Существуют два комментария, чтобы указать, где вы хотите вставить новые документы и где они заканчиваются:

[comment]: <> (Insert auto generated CLI docs from here.)

...docs to insert...

[comment]: <> (End of auto generated CLI docs.)