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

Настройка среды разработки

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

ZincSearch использует Go (для сервера) и VueJS (для веб-интерфейса).

Вы должны иметь установленными следующие компоненты:

1. Git
2. Go 1.16+ (Мы рекомендуем версию 1.19+)
3. nodejs v14+ и npm v6+

Сборка из исходного кода

Давайте клонируем репозиторий и начнем работу

git clone https://github.com/zincsearch/zincsearch
cd zincsearch

Теперь соберем веб-интерфейс

cd web
npm install
npm run build
cd ..

Результат будет сохранен в папке web/dist. Папка web/dist будет встроена в бинарник ZincSearch при сборке go-приложения.

Важно, чтобы вы собирали веб-приложение каждый раз, когда вносите изменения в код на языке JavaScript, так как собранный код затем встраивается в go-приложение.

Теперь соберем go-приложение

Загрузим зависимости

go mod tidy # это загрузит go-библиотеки, используемые в zincsearch

Простая команда:

go build -o zincsearch cmd/zincsearch/main.go # соберет бинарник ZincSearch

Расширенная команда:

CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -ldflags="-s -w -X github.com/zincsearch/zincsearch/pkg/meta.Version=${VERSION} -X github.com/zincsearch/zincsearch/pkg/meta.CommitHash=${COMMIT_HASH} -X github.com/zincsearch/zincsearch/pkg/meta.BuildDate=${BUILD_DATE}" -o zincsearch cmd/zincsearch/main.go

Установка GOOS и GOARCH позволяет выполнять кросс-платформенную компиляцию. Проверьте официальную документацию для всех возможных значений и комбинаций. Этот gist также полезен.Установка CGO_ENABLED=0 позволяет выполнять статическую компиляцию, что приводит к созданию одного бинарного файла без зависимостей.

Настройка ldflags позволяет передавать значения, такие как номер версии, в бинарник во время сборки, вместо жесткого кодирования значения в исходном коде. Обычно номер версии устанавливается CI-транспортной лентой во время сборки с использованием git-тега.

Разработка

После клонирования исходного кода вы можете начать разработку.

Существует два направления разработки.

1. UI
2. Сервер

Сервер

go mod tidy
ZINC_FIRST_ADMIN_USER=admin ZINC_FIRST_ADMIN_PASSWORD=Complexpass#123 go run cmd/zincsearch/main.go

Это запустит сервер API ZincSearch на порту 4080. Переменные окружения ZINC_FIRST_ADMIN_USER и ZINC_FIRST_ADMIN_PASSWORD требуются только в первый раз при запуске ZincSearch.

Интерфейс

cd web
npm install
npm run dev

Это запустит сервер интерфейса на порту 8080.

Чтобы эффективно использовать интерфейс, вам потребуется запустить сервер API ZincSearch в отдельном окне, который будет принимать запросы от интерфейса.

Swagger

Сервер также предоставляет конечную точку API Swagger, которую можно увидеть, посетив путь /swagger/index.html. Он использует gin-swagger для пометки конечных точек API с аннотациями комментариев и swag для генерации спецификации API из аннотаций в документацию Swagger 2.0.Если вы обновите аннотации, вам также потребуется перегенерировать документацию Swagger, запустив скрипт swagger.sh, расположенный в корневой папке проекта:

./swagger.sh
2022/05/31 10:18:13 Генерация документации Swagger....
2022/05/31 10:18:13 Генерация общего API Info, папка поиска:./
2022/05/31 10:18:13 Генерация auth.LoginRequest
2022/05/31 10:18:13 Генерация auth.LoginSuccess
2022/05/31 10:18:13 Генерация auth.SimpleUser
2022/05/31 10:18:13 Генерация auth.LoginError
2022/05/31 10:18:13 Создание docs.go в docs/docs.go
2022/05/31 10:18:13 Создание swagger.json в docs/swagger.json
2022/05/31 10:18:13 Создание swagger.yaml в docs/swagger.yaml

Создание образа Docker

Убедитесь, что у вас установлен docker.

Простое создание:

docker build --tag zincsearch:latest . -f Dockerfile

Создание образа для нескольких архитектур

Для создания образов для нескольких архитектур вам потребуется установленный buildx. Вам потребуется передать флаг платформы для платформы, которую вы хотите построить.

docker buildx build --platform linux/amd64 --tag zinc:latest-linux-amd64 . -f Dockerfile.hub

Проверки в CI-трубопроводеМы проверяем следующее в CI-трубопроводе для любых запросов на слияние.

1. Охват юнит-тестов для кода на Go.

   • Если охват юнит-тестов меньше 81% (по данным go test), CI-тесты завершатся неудачей.
   • Вы можете проверить охват самостоятельно, запустив ./coverage.sh.
   • Мы используем codecov для визуализации охвата юнит-тестов для кода на Go. Codecov обновляет охват для каждого PR через комментарий. Это позволяет видеть недостающий охват для любых строк.

2. Линтер для JavaScript в GUI

   • Мы запускаем eslint для JavaScript, и любые ошибки линтера приведут к неудаче сборки.
   • Вы можете проверить ошибки линтера, запустив ./lint.sh в папке web.
   • Вы также можете автоматически исправить исправляемые ошибки линтера, запустив npm run lint-autofix.

Как вносить изменения в код1. Создайте форк репозитория на GitHub (например, awesomedev/zincsearch).

1. Клонируйте репозиторий из форкнутого репозитория (например, awesomedev/zincsearch) на вашу машину.
2. Создайте новый локальный ветвь.
3. Внесите изменения в код.
4. Загрузите код в ваш репозиторий.
5. Создайте запрос на слияние (Pull Request).
6. Убедитесь, что автоматические проверки CI проходят для вашего запроса на слияние.