Skip to content

Руководство по внесению вклада в разработку

Добро пожаловать! Существует множество способов внести свой вклад, включая отправку сообщений об ошибках, улучшение документации, отправку запросов на новые функции, рассмотрение новых заявок или предоставление кода, который можно включить в проект.

Первоначальная настройка для локальной разработки

Установка git

Пожалуйста, следуйте инструкциям.

Создание форка

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

Пожалуйста, следуйте инструкциям.

Клонирование репозитория

Откройте терминал и выполните эти команды:

git clone https://github.com/MobileTeleSystems/syncmaster -b develop

cd syncmaster

Установка окружения

Во-первых, установите make. Он используется для выполнения сложных команд в локальной среде.

Во-вторых, создайте virtualenv и установите зависимости:

make venv

Если у вас уже есть venv, но необходимо установить зависимости, необходимые для разработки:

make venv-install

Мы используем poetry для управления зависимостями и сборкой пакета. Это позволяет сохранить единую среду разработки для всех разработчиков благодаря использованию файла блокировки с фиксированными версиями зависимостей.

Есть дополнительные зависимости (включены в пакет как необязательные):

  • server — для запуска сервера
  • worker — для запуска рабочих процессов Celery

И группы (не включены в пакет, используются локально и в непрерывной интеграции):

  • test — для запуска тестов
  • dev — для разработки, например, линтеры, форматировщики, mypy, pre-commit и т. д.
  • docs — для сборки документации

Включить хуки пре-коммита

пре-коммит Хуки позволяют проверять и исправлять содержимое репозитория перед созданием нового коммита. Они позволяют запускать линтеры, форматировщики, исправлять права доступа к файлам и т. д. Если что-то не так, изменения не могут быть зафиксированы.

Вр-первых, установите пре-коммит хуки:

pre-commit install --install-hooks

И затем протестируйте запуск хуков:

pre-commit run

Как

Запустить инстанс разработки локально

Запустить DB контейнер:

make db broker

Затем запустить сервер разработки:

make dev-server

И открыть http://localhost:8000/docs

Настройки хранятся в файле .env.local.

Чтобы запустить процесс разработки, откройте новое окно/вкладку терминала и выполните:

make dev-worker

Работать с миграциями

Запустить базу данных:

make db-start

Сгенерировать ревизию:

make db-revision ARGS="-m 'Message'"

Обновить версию базы данных до head миграции:

make db-upgrade

Понизить версию базы данных до head-1:

make db-downgrade

Запустить тестирование локально

Модульное тестирование

Это очень просто:

make test-unit

Эта команда запускает все необходимые контейнеры (Postgres, RabbitMQ), выполняет все необходимые миграции, а затем запускает Pytest.

Вы можете передать дополнительные аргументы pytest следующим образом:

make test-unit PYTEST_ARGS="-k some-test -lsx -vvvv --log-cli-level=INFO"

Получить механизмы, не используемые ни в одном тесте:

make test-check-fixtures

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

ВНИМАНИЕ

Для локального запуска тестов HDFS и Hive необходимо добавить следующую строку в файл /etc/hosts (путь к файлу зависит от ОС):

# HDFS/Hive server returns container hostname as connection address, causing error in DNS resolution
127.0.0.1 test-hive

Для запуска специфических интеграционных тестов:

make test-integration-hdfs

Это запускает контейнеры базы данных, брокера и рабочего процесса, а также контейнер HDFS. Затем выполняются только интеграционные тесты, связанные с HDFS.

Чтобы запустить полный набор тестов:

make test-integration

Это запускает все контейнеры и все интеграционные тесты.

Как и в случае с модульными тестами, вы можете передавать Pytest дополнительные аргументы:

make test-integration-hdfs PYTEST_ARGS="-k some-test -lsx -vvvv --log-cli-level=INFO"

Остановите все контейнеры и удалите созданные тома:

make test-cleanup ARGS="-v"

Запустить продуктивный экземпляр локально

Сначала соберите пподуктивные образы:

make prod-build

И затем запустите все необходимые сервисы:

make prod

Затем откройте http://localhost:8000/docs

Настройки хранятся в файле .env.docker.

Сборка документации

Соберите документацию, используя Sphinx и откройте её:

make docs

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

make docs-fresh

Процесс проверки

Создайте новую задачу на GitHub для любых существенных изменений и улучшений, которые вы хотели бы внести. Укажите, какую функцию вы хотели бы внести, почему она вам нужна и как она будет работать. Обсудите свои идеи открыто и получите обратную связь от сообщества, прежде чем продолжить.

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

Небольшие изменения можно создать и отправить непосредственно в репозиторий GitHub в виде запроса на включение изменений.

Создание pull request

Сделайте коммит ваших изменений:

git commit -m "Commit message"
git push

Затем откройте интерфейс Github и создайте pull request.

Следуйте инструкциям из шаблона тела запроса на включение изменений.

После создания запроса на включение изменений ему присваивается соответствующий номер, например, 123 (pr_number).

Создайте описание релиза

Data.SyncMaster использует towncrier для управления журналом изменений.

Чтобы отправить заметку об изменении вашего запроса на изменение (PR), добавьте текстовый файл в папку docs/changelog/next_release. Он должен содержать объяснение того, как применение этого запроса на изменение (PR) изменит взаимодействие конечных пользователей с проектом. Обычно достаточно одного предложения, но вы можете добавить столько подробностей, сколько считаете нужным, чтобы пользователи поняли, что это значит.

Используйте прошедшее время для текста в вашем фрагменте, поскольку в сочетании с другими он станет частью «новостного дайджеста», рассказывающего читателям что изменилось в конкретной версии библиотеки по сравнению с предыдущей версией.

Синтаксис reStructuredText используется для выделения кода (встроенного или блочного), ссылки на части документации или внешние сайты. Если вы хотите подписать свои изменения, смело добавляйте -- by :user:github-username` (в конце заменитеgithub-username` своим!).

Наконец, назовите свой файл в соответствии с соглашением, которое понимает Towncrier: оно должно начинаться с номера выпуска или PR, за которым следует точка, затем добавьте тип патча, например feature, doc, misc и т. д., и добавьте .rst в качестве суффикса. Если вам нужно добавить более одного фрагмента, вы можете добавить необязательный порядковый номер (разделённый ещё одной точкой) между типом и суффиксом.

Обычно имя следует шаблону <pr_number>.<category>.rst, где категории:

  • feature: Любая новая функция. Добавление новой функциональности, которой ещё не было.
  • removal: Обозначает прекращение поддержки или удаление публичного API.
  • bugfix: Исправление ошибки.
  • improvement: Улучшение. Улучшение уже существующей функциональности.
  • doc: Изменение в документации.
  • dependency: Изменения, связанные с зависимостями.
  • misc: Изменения внутри репозитория, такие как изменения непрерывной интеграции, тестирования и сборки.
  • breaking: Вносит критически важное изменение API.
  • significant: Указывает на значительные изменения в коде.
  • dependency: Указывает на изменения в зависимостях.

Запрос на включение изменений может содержать более одного из этих компонентов, например, изменение кода может ввести новую функцию, которая делает устаревшей старую, в этом случае следует добавить два фрагмента. Нет необходимости создавать отдельный фрагмент документации для изменений, сопровождающих соответствующие изменения кода.

Примеры добавления записей журнала изменений в ваши запросы на извлечение

Added a ``:github:user:`` role to Sphinx config -- by :github:user:`someuser`

Fixed behavior of ``server`` -- by :github:user:`someuser`

Added support of ``timeout`` in ``LDAP``
-- by :github:user:`someuser`, :github:user:`anotheruser` and :github:user:`otheruser`

Как пропустить проверку заметок об изменениях?

Просто добавьте метку ci:skip-changelog в pull request.

Процесс выпуска

Перед выпуском из ветки develop выполните следующие действия:

  1. Перейдите в ветку develop и обновите её до актуального состояния.
git checkout develop
git pull -p
  1. Произведите резервное копирование NEXT_RELEASE.rst
cp "docs/changelog/NEXT_RELEASE.rst" "docs/changelog/temp_NEXT_RELEASE.rst"
  1. Создайте заметки о релизе с помощью Towncrier
VERSION=$(poetry version -s)
towncrier build "--version=${VERSION}" --yes
  1. Измените номер версии релиза в файле со списком изменений
mv docs/changelog/NEXT_RELEASE.rst "docs/changelog/${VERSION}.rst"
  1. Удалите содержимое над заголовком номера версии релиза в файле ${VERSION}.rst
awk '!/^.*towncrier release notes start/' "docs/changelog/${VERSION}.rst" > temp && mv temp "docs/changelog/${VERSION}.rst"
  1. Обновить индекс изменений
awk -v version=${VERSION} '/DRAFT/{print;print "    " version;next}1' docs/changelog/index.rst > temp && mv temp docs/changelog/index.rst
  1. Восстановите NEXT_RELEASE.rst файл из резервной копии
mv "docs/changelog/temp_NEXT_RELEASE.rst" "docs/changelog/NEXT_RELEASE.rst"
  1. Сделайте коммит и добавьте изменения в ветку develop 
git add .
git commit -m "Prepare for release ${VERSION}"
git push
  1. Сделайте merge ветки develop в master, БЕЗ сжатия
git checkout master
git pull
git merge develop
git push
  1. Добавьте тег git к последнему коммиту в ветке master
git tag "$VERSION"
git push origin "$VERSION"
  1. Обновление версии в ветке develop после релиза:
git checkout develop

NEXT_VERSION=$(echo "$VERSION" | awk -F. '/[0-9]+\./{$NF++;print}' OFS=.)
poetry version "$NEXT_VERSION"

git add .
git commit -m "Bump version"
git push