Skip to content

Руководство по вкладу в проект

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

Ограничения

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

  • Некоторые компании до сих пор используют Python 3.7. Поэтому требуется сохранять совместимость, если это возможно, по крайней мере для клиентской части пакета.
  • Разные пользователи используют Horizon по-разному - кто-то хранит данные в Postgres, кто-то в MySQL, некоторым пользователям нужен LDAP. Такие зависимости должны быть опциональными.

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

Установка Git

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

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

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

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

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

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

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

cd horizon

Настройка окружения

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

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

make venv-init

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

make venv-install

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

Существуют дополнительные зависимости (включенные в пакет как опциональные):

  • backend
  • client-sync
  • postgres
  • ldap

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

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

Включение pre-commit хуков

pre-commit хуки позволяют проверять и исправлять содержимое репозитория перед созданием нового коммита. Это позволяет запускать линтеры, форматтеры, исправлять разрешения файлов и так далее. Если что-то не так, изменения не могут быть зафиксированы.

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

pre-commit install --install-hooks

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

pre-commit run

Как сделать

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

Запустите контейнер с базой данных:

make db

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

make dev

И откройте http://localhost:8000/docs

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

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

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

make db-start

Сгенерируйте ревизию:

make db-revision

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

make db-upgrade

Откатите базу данных до миграции head-1:

make db-downgrade

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

Запустите все контейнеры с зависимостями:

make db  # для тестов бэкенда и клиента
make ldap-start  # для тестов бэкенда
make dev  # для тестов клиента, запустите в отдельной вкладке терминала

Запустите тесты:

make test

Вы можете передать дополнительные аргументы, которые будут переданы pytest:

make test PYTEST_ARGS="-m client-sync -lsx -vvvv --log-cli-level=INFO"

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

make cleanup ARGS="-v"

Получите фикстуры, не используемые ни одним тестом:

make check-fixtures

Сборка CI образа локально

Этот образ собирается в CI для целей тестирования, но вы также можете сделать это локально:

make test-build

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

Во-первых, соберите производственный образ:

make prod-build

А затем запустите его:

make prod

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

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

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

Соберите документацию с помощью Sphinx и откройте ее:

make docs

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

make docs-fresh

Процесс рецензирования

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

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

Небольшие изменения могут быть непосредственно созданы и отправлены в репозиторий GitHub в виде Pull Request.

Создание pull request

Зафиксируйте ваши изменения:

git commit -m "Commit message"
git push

Затем откройте интерфейс Github и создайте pull request. Пожалуйста, следуйте руководству из шаблона тела PR.

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

Написание release notes

horizon использует towncrier для управления changelog.

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

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

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

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

В общем, имя будет следовать шаблону <pr_number>.<category>.rst, где категории:

  • feature: Любая новая функция
  • bugfix: Исправление ошибки
  • improvement: Улучшение
  • doc: Изменение в документации
  • dependency: Изменения, связанные с зависимостями
  • misc: Изменения, внутренние для репозитория, такие как CI, тесты и изменения сборки

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

Примеры добавления записей в changelog к вашим Pull Requests

Добавлена роль ``:github:user:`` в конфигурацию Sphinx -- от :github:user:`someuser`

Исправлено поведение ``backend`` -- от :github:user:`someuser`

Добавлена поддержка ``timeout`` в ``LDAP``
-- от :github:user:`someuser`, :github:user:`anotheruser` и :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. Переименуйте файл с changelog в номер версии выпуска
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. Обновите индекс Changelog
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. Слейте ветку 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