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

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

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

Установка Git

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

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

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

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

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

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

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

cd data_rentgen

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

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

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

make venv

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

make venv-install

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

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

backend
client-sync
postgres
seed

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

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

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

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

Сначала установите pre-commit хуки:

pre-commit install --install-hooks

Затем проверьте работу хуков:

pre-commit run

Как выполнять различные задачи

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

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

make db db-seed

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

make dev-server

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

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

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

make broker dev-consumer

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

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

make db-start

Создайте ревизию:

make db-revision ARGS="-m 'Сообщение'"

Обновите БД до миграции head:

make db-upgrade

Откатите БД до миграции head-1:

make db-downgrade

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

Это так же просто, как:

make test

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

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

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

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

make test-cleanup ARGS="-v"

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

make test-check-fixtures

Запуск production экземпляра локально

Сначала соберите production образ:

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 "Сообщение коммита"
git push

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

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

Написание примечаний к выпуску

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

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

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

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

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

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

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

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

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

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

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

Добавлена поддержка ``timeout`` в ``LDAP``
-- by :github:user:`someuser`, :github:user:`anotheruser` и :github:user:`otheruser`

Tip

Посмотреть pyproject.toml <pyproject.toml>_ для всех доступных категорий (tool.towncrier.type). Towncrier philosophy: https://towncrier.readthedocs.io/en/stable/#philosophy

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

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

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

Note

Это предназначено только для сопровождения репозитория.

Перед созданием релиза из ветки develop, выполните следующие шаги:

Перейдите в ветку develop и обновите её до актуального состояния
```
git checkout develop
git pull -p
```

Создайте резервную копию NEXT_RELEASE.rst

cp "docs/changelog/NEXT_RELEASE.rst" "docs/changelog/temp_NEXT_RELEASE.rst"

Соберите Примечания к выпуску с помощью Towncrier
```
VERSION=$(poetry version -s)
towncrier build "--version=${VERSION}" --yes
```
Измените файл с списком изменений на номер версии релиза
```
mv docs/changelog/NEXT_RELEASE.rst "docs/changelog/${VERSION}.rst"
```

Удалите содержимое выше заголовка с номером версии в файле ${VERSION}.rst

awk '!/^.*towncrier release notes start/' "docs/changelog/${VERSION}.rst" > temp && mv temp "docs/changelog/$  {VERSION}.rst"

Обновите Индекс списка изменений

awk -v version=${VERSION} '/DRAFT/{print;print "    " version;next}1' docs/changelog/index.rst > temp && mv temp   docs/changelog/index.rst

Восстановите файл NEXT_RELEASE.rst из резервной копии
```
mv "docs/changelog/temp_NEXT_RELEASE.rst" "docs/changelog/NEXT_RELEASE.rst"
```
Зафиксируйте и отправьте изменения в ветку develop
```
git add .
git commit -m "Prepare for release ${VERSION}"
git push
```
Объедините ветку develop с веткой master, БЕЗ сжатия
```
git checkout master
git pull
git merge develop
git push
```
Добавьте git-тег к последнему коммиту в ветке master
```
git tag "$VERSION"
git push origin "$VERSION"
```

Обновите версию в ветке 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