Точный шаблон запроса на слияние GitHub, который мы используем в dbt Labs

Наличие шаблона запроса на слияние (PR) GitHub — один из самых важных и часто упускаемых из виду аспектов создания эффективного и масштабируемого аналитического рабочего процесса, ориентированного на dbt. Открытие запроса на слияние — это финальный шаг в вашем процессе моделирования, который обычно включает в себя много сложной работы!

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

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

В команде профессиональных услуг dbt Labs наши аналитические инженеры часто работают в парах над проектами клиентов, что означает, что два аналитических инженера пишут и проверяют PR в одном и том же репозитории.

Теперь представьте, что вы работаете с 2-3 разными людьми над 2-3 проектами. Без какой-либо структуры шансы на то, что все будут следовать тщательным и повторяемым процессам написания/проверки PR, крайне малы.

Давайте перейдем к точному шаблону PR, который мы используем внутри dbt Labs.

Шаблон PR GitHub, который мы используем

Наш шаблон PR (посмотреть файл markdown на GitHub) состоит из 6 разделов:

• Описание и мотивация
• Задачи перед слиянием (опционально)
• Скриншоты
• Валидация моделей
• Изменения в существующих моделях
• Контрольный список

Как и почему работает этот шаблон PR GitHub

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

Описание и мотивация:

Это введение в ваш PR, которое должно позволить рецензенту быстро понять причину открытия этого PR. Если ваш фактический код — это «как», то описание — это «что» и «почему». Пример из недавнего проекта:

Пример: Этот PR обновляет сопоставление каналов для данных Google Adwords на основе этой таблицы Google. Это имитирует сопоставление, используемое для сессий, и будет использоваться в нашей финальной модели атрибуции для анализа ROAS.

Этот PR также добавляет stg таблицу для final_url_report из Adwords. В настоящее время она используется только для сопоставления utm_medium и utm_source с campaign_id и ad_group_id, чтобы затем определить канал. Это пока не используется в качестве входных данных для пакета Adwords из-за ограничений в данных, которые настроены и доступны через Adwords. Мы можем решить включить это позже.

Основная цель этого PR заключалась в обновлении сопоставления каналов для модели атрибуции. Я мог бы быстро написать «обновлено сопоставление каналов» и на этом закончить. Но, зная, что мне, вероятно, потребуется снова обратиться к этому сопоставлению в будущем, я добавил эту ссылку на таблицу Google, где мы изначально создали сопоставление.

Помните, вы знаете об этом PR сейчас больше, чем будете знать через пару месяцев. Если вы или ваша команда отправите более 30 PR и вам нужно будет вернуться к одному из них, чтобы что-то уточнить, вы будете разочарованы, если ваше описание будет просто «добавлена модель».

Скриншоты:

Здесь мы добавляем соответствующие разделы из нашего DAG! Это одна из моих любимых функций dbt, так как я очень визуальный ученик. Поэтому, когда я открываю PR, я быстро просматриваю соответствующие разделы DAG (также известного как граф зависимостей), чтобы помочь мне концептуализировать моделирование.

Проверка таких вещей, как модульность и 1:1 отношения между источниками и моделями на стадии, гораздо проще выполняется визуально через DAG, чем попытка взглянуть на код и визуализировать отношения.

Примечание: мои коллеги Кристин Бергер и Рэнди Питчер опубликовали отличный обзор техники модульного моделирования данных, если вам интересно узнать больше.

Валидация моделей:

Этот раздел должен показать что-то, что подтверждает, что ваша модель делает то, что вы намеревались. Это может быть тест dbt, такой как уникальность или отсутствие null, или это может быть ad-hoc запрос, который вы написали для проверки ваших данных. Вот скриншот из тестового запуска на локальной ветке разработки:

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

Включив скриншот вашего тестового запуска dbt здесь, вы подтверждаете, что выполнили работу.

Изменения в существующих моделях:

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

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

Контрольный список:

Контрольный список запуска, вероятно, является самой важной частью шаблона PR — он гарантирует, что вы следовали шагам контроля качества, необходимым для отправки вашего PR в производство.

Мой запрос на слияние представляет собой одну логическую часть работы:

Каждый PR должен представлять собой связное тело работы — конкретную модель fct или постановку определенного источника данных. Если у вас возникают трудности с сужением и описанием того, что делает ваш PR, возможно, он слишком широк.

Это также значительно облегчает работу вашему рецензенту. Проверка PR с несколькими, несвязанными концепциями чрезвычайно сложна и требует много времени.

Мои коммиты связаны с запросом на слияние и выглядят чисто.

Подумайте о себе! Что, если вам нужно будет откатить изменение, но в момент пост-кодовой затуманенности вы сделали массивный коммит несвязанных концепций, который «обновил все». Уф.

Мой SQL следует стилевому руководству dbt Labs.

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

Я добавил соответствующие тесты и документацию к любым новым моделям.

По умолчанию все новые модели должны иметь как минимум тесты на уникальность и отсутствие null на .

Документация следует той же логике, что и описание PR. Вы будете знать больше сейчас о тонкостях этих моделей, чем после того, как разработаете еще 50 моделей в ближайшие месяцы.

Я материализовал свои модели соответствующим образом.

Это все о производительности. Наша конечная цель — моделировать данные так, чтобы конечные пользователи могли легко и эффективно запрашивать полученные объекты базы данных.

Я обновил файл README.
Последнее, но не менее важное — README. Это не нужно обновлять с каждым PR.

В общем, ваш README содержит информацию о таких вещах, как как начать вносить вклад в ваш проект dbt, к кому обратиться за доступом к базе данных, дополнительные ресурсы для разработки и т.д. Если что-то из этого изменится в результате вашего PR, обязательно обновите README!

Добавление полного шаблона PR GitHub в ваш репозиторий

Если вы еще не взяли его с GitHub, полный код markdown шаблона PR dbt Labs приведен ниже. После копирования шаблона PR в буфер обмена, давайте пройдемся по тому, как добавить его в ваш репозиторий.

<!---

Предоставьте краткое резюме в заголовке выше. Примеры хороших заголовков PR:

* "Функция: добавить такие-то модели"

* "Исправление: удалить дубликаты таких-то"

* "Обновление: версия dbt 0.13.0"

-->

## Описание и мотивация

<!---

Опишите ваши изменения и почему вы их делаете. Это связано с открытым

вопросом, карточкой Trello или другим запросом на слияние? Ссылка здесь.

-->

## Задачи перед слиянием

<!---

(Опционально — удалите этот раздел, если он не нужен)

Включите любые заметки о вещах, которые должны произойти до слияния этого PR, например:

- [ ] Изменить базовую ветку

- [ ] Обновить задания dbt Cloud

- [ ] Убедиться, что PR #56 объединен

-->

## Скриншоты:

<!---

Включите скриншот соответствующего раздела обновленного DAG. Вы можете получить доступ

к вашей версии DAG, запустив `dbt docs generate && dbt docs serve`.

-->

## Валидация моделей:

<!---

Включите любой вывод, который подтверждает, что модели делают то, что ожидается. Это может

быть ссылка на разрабатываемую панель в вашем BI инструменте или запрос, который

сравнивает существующую модель с новой.

-->

## Изменения в существующих моделях:

<!---

Включите этот раздел, если вы изменяете какие-либо существующие модели. Ссылка на любые связанные

запросы на слияние в вашем BI инструменте или инструкции для слияния (например, следует ли

удалить старые модели после слияния или требуется ли полное обновление)

-->

## Контрольный список:

<!---

Этот контрольный список в основном полезен как напоминание о мелочах, которые легко

забыть — он предназначен как полезный инструмент, а не как препятствия для преодоления.

Поставьте `x` во всех пунктах, которые применимы, сделайте заметки рядом с любыми, которые не были

учтены, и удалите любые пункты, которые не относятся к этому PR.

-->

- [ ] Мой запрос на слияние представляет собой одну логическую часть работы.

- [ ] Мои коммиты связаны с запросом на слияние и выглядят чисто.

- [ ] Мой SQL следует стилевому руководству.

- [ ] Я материализовал свои модели соответствующим образом.

- [ ] Я добавил соответствующие тесты и документацию к любым новым моделям.

- [ ] Я обновил файл README.

{%- if project.warehouse == 'redshift' %}

- [ ] Я добавил ключи сортировки и распределения к моделям, материализованным как таблицы.

- [ ] Я проверил SQL в любых представлениях с поздним связыванием.

{% endif %}

Создание markdown файла

Скопируйте полный текст шаблона PR выше и вставьте его в ваш любимый текстовый редактор. После этого экспортируйте документ как файл .md.

Добавление файла .md в ваш репозиторий GitHub

Теперь, когда у вас есть файл markdown шаблона запроса на слияние, перейдите на главную страницу вашего репозитория на GitHub. Над списком файлов, используя выпадающее меню Add file, нажмите Create new file.

После добавления файла назовите его так, чтобы было понятно, что это ваш шаблон запроса на слияние. Хорошее имя для файла может быть pull_request_template.md.

И это все!

Теперь у вас есть шаблон запроса на слияние в вашем репозитории GitHub, который может помочь вашей команде следовать лучшим практикам аналитического инжиниринга.

Чтобы глубже погрузиться в то, как мы используем его как часть рабочего процесса аналитического инжиниринга, ознакомьтесь с бесплатным курсом dbt Fundamentals по запросу.