Рекомендации для участников проектов dbt

Будь то dbt-labs/dbt, адаптеры, пакеты или сам этот сайт документации, участие в разработке кода с открытым исходным кодом или доступным для просмотра исходным кодом, на котором строится экосистема dbt, — отличный способ поделиться знаниями, вырасти как разработчик и внести свой вклад в сообщество. Цель этой страницы — помочь вам понять, чего ожидать при участии в проектах экосистемы dbt.

Вы видели в других проектах что-то, что вам понравилось, и считаете, что мы могли бы перенять этот опыт? Создайте обсуждение на форуме сообщества dbt или начните разговор в Slack сообщества dbt (например, в каналах #community-strategy, #dbt-development, #package-ecosystem, #adapter-ecosystem). Мы всегда рады вашим отзывам и предложениям!

Принципы

dbt — командный вид спорта

Мы все вместе создаем dbt — будь то написание кода или внесение идей. Используя dbt, вы вкладываетесь в будущее инструмента и играете активную роль в продвижении стандарта аналитической инженерии. Вы уже получаете выгоду от использования кода и документации, внесенных членами сообщества. Участие в сообществе dbt — это ваш способ быть активным участником того, что мы все создаем вместе.

Есть и вполне практическая причина: разработка «в публичном поле» ставит коллективные знания и опыт выше опыта любого отдельного человека. У нас нет практики работы с каждой базой данных, каждой операционной системой, каждой средой безопасности и т. д. Мы полагаемся на сообщество пользователей, которое помогает оттачивать функциональность продукта и документацию для самого широкого спектра контекстов, в которых он используется. Благодаря этому dbt становится результатом работы тысяч людей, а не нескольких десятков.

Мы серьезно относимся к нашей роли хранителей стандарта

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

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

Так когда же мы говорим «да» новым возможностям в dbt? Среди сигналов, на которые мы обращаем внимание:

• Голоса (upvotes) за issues в наших GitHub‑репозиториях
• Пакеты dbt с открытым исходным кодом, пытающиеся закрыть существующий пробел
• Технические достижения в экосистеме

А пока — мы будем стараться отвечать на новые issues следующим образом:

• Чётко объяснять, попадает ли предложенная функциональность в предполагаемые границы source‑available компонентов dbt
• Давать контекст (включая ссылки на связанные issues)
• Предлагать альтернативы и обходные пути
• По возможности указывать на код, который может помочь контрибьюторам из сообщества

Инициатива — это все

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

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

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

Практические аспекты

Обсуждения

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

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

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

Проблемы

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

Лучшие практики для проблем

• Проблемы не предназначены для поддержки / устранения неполадок / помощи в отладке. Пожалуйста, ознакомьтесь с поддержкой dbt для получения более подробной информации и предложений о том, как получить помощь.
• Всегда сначала ищите существующие проблемы, чтобы увидеть, не возникла ли у кого-то еще такая же идея / не нашел ли кто-то ту же ошибку, что и вы.
• Многие репозитории dbt предлагают шаблоны для создания проблем, такие как отчет об ошибке или запрос новой функции. Если доступно, пожалуйста, выберите соответствующий шаблон и заполните его по мере возможности. Эта информация помогает нам (и другим) понять вашу проблему.

Вы нашли существующую проблему, которая вас интересует. Что вам следует сделать?

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

Вы открыли новую проблему. Чего вы можете ожидать?

В наших наиболее важных репозиториях (таких как dbt-labs/dbt) мы стремимся как можно быстрее отвечать на новые issues. Первым ответом часто бывает краткое подтверждение того, что сопровождающие проекта знают о проблеме, с обозначением того, насколько срочной мы её считаем. В зависимости от характера вашей проблемы её решение может хорошо подойти для вклада со стороны — от вас или другого участника сообщества.

Что делать, если вы создаёте issue в другом репозитории? У нас есть инженерные команды, которые активно поддерживают dbt-labs/dbt, где размещены как v1, так и v2. Если вы вносите вклад в репозиторий dbt-labs/dbt, учитывайте следующее:

• v2 находится в ветке main
• v1 находится в ветке latest.1, а также в библиотеках компонентов v1 (dbt-common + dbt-adapters (который также включает адаптеры, поддерживаемые dbt Labs). dbt-adapters относится только к v1.

За прошедшие годы мы открыли исходный код ряда других программных проектов, и для большинства из них мы не гарантируем такой же уровень активности и поддержки. Проверьте, есть ли ответы на другие недавние issues и когда был добавлен последний коммит в ветку main.

Вы не уверены в статусе своего issue. Если ваш issue находится в активно поддерживаемом репозитории и имеет метку status:triage, мы знаем, что на него нужно ответить. Если issue уже прошёл первичный разбор, но ещё не получил приоритет, это может означать следующее:

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

Мы постараемся объяснить открытые вопросы или сложность, и когда / почему мы могли бы предвидеть ее приоритизацию.

Автоматизация, которая может нам помочь: Во многих репозиториях мы используем бота, который помечает проблемы как устаревшие, если они не имели никакой активности в течение 180 дней. Это помогает нам держать наш бэклог организованным и актуальным. Мы призываем вас комментировать старые открытые проблемы, которые вас интересуют, чтобы они не были помечены как устаревшие. Вы также всегда можете комментировать закрытые проблемы, чтобы сказать, что вы все еще заинтересованы в предложении.

Метки проблем

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

В некоторых случаях правильное решение открытой проблемы может быть косвенно связано с кодовой базой. Правильный путь вперед может быть в другой кодовой базе (мы перенесем ее), обновлении документации или изменении, которое вы можете сделать сами в пользовательском коде. В других случаях проблема может описывать функциональность, которую хранители не хотят или не могут включить в основную кодовую базу. В этих случаях хранитель закроет проблему (возможно, используя метку wontfix) и объяснит, почему.

Многие метки следуют модели facet:value с пространством имён, где каждый фасет отвечает на один вопрос о задаче — к какому виду работ она относится, какую подсистему затрагивает, на какой движок dbt нацелена и так далее. Некоторые фасеты принимают ровно одно значение, другие — несколько. Вам не нужно назначать эти метки самостоятельно, но понимание их значений поможет отслеживать состояние задачи.

Фасет	Примеры значений	Значение
type:	type:bug, type:feature, type:docs, type:tech-debt, type:epic, type:good-first-issue	Вид работ. Ровно одно значение на задачу.
area:	area:static-analysis, area:engine, area:compute, area:adapters, area:vscode, area:wizard, area:autofix, area:cicd	Подсистема, которую затрагивает задача.
adapter:	adapter:bigquery, adapter:snowflake, adapter:databricks, adapter:postgres, …	Адаптер или диалект SQL, к которому относится задача.
engine:	engine:v1, engine:v2	Движок dbt, которого касается задача: engine:v1 — движок на Python (dbt v1); engine:v2 — версия v2, переписанная на Rust.
priority:	priority:p0, priority:p1, priority:p2	Срочность, определённая сопровождающими при первичном разборе задачи.
status:	status:triage, status:needs-repro, status:has-repro, status:ready-for-review	Текущий этап обработки задачи.
resolution:	resolution:wontfix	Причина закрытия задачи без изменений в коде.

Автоматизация назначает новым задачам метку status:triage, обозначающую, что они ожидают первого ответа сопровождающего. У старых задач также могут сохраняться прежние метки без пространства имён, такие как bug, enhancement, good_first_issue, help_wanted, duplicate, stale и wontfix. Они соответствуют приведённым выше фасетным меткам (bug → type:bug, enhancement → type:feature, good_first_issue → type:good-first-issue, wontfix → resolution:wontfix и так далее) и сохраняются для преемственности. Пока переход не завершён, вы можете встретить любой из этих наборов меток.

Pull-запросы

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

PR должны включать надежное тестирование. Комплексное тестирование в рамках pull-запросов имеет решающее значение для стабильности dbt. Приоритетное внимание к надежному тестированию обеспечивает надежность нашей кодовой базы, минимизирует непредвиденные проблемы и защищает от потенциальных регрессий. Мы не можем объединять изменения, которые могут привести к несовместимости с задокументированными поведениями. Мы понимаем, что создание тщательных тестов часто требует значительных усилий, и ваша приверженность этому процессу значительно способствует общей надежности проекта. Спасибо за вашу приверженность поддержанию целостности нашей кодовой базы и опыта всех, кто использует dbt!

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

Мы получаем больше PR, чем можем тщательно отревьюить, протестировать и смержить. У наших команд ограниченные ресурсы, и наш главный приоритет — поддержание хорошо очерченного и качественного фреймворка для десятков тысяч людей, которые используют его каждую неделю. Поэтому нам приходится отдавать приоритет общей стабильности и запланированным улучшениям, а не длинному хвосту нишевых потенциальных функций. Чтобы повысить шансы на успех, сразу указывайте, по каким именно аспектам вам особенно важна обратная связь, и объясняйте, что будет значить принятие предложенного изменения для вас, вашей команды и других участников сообщества. Небольшие PR, решающие чётко ограниченные задачи, как правило, рассматриваются проще и быстрее. Два примера PR, внесённых участниками сообщества:

• (dbt-core#9347) Исправление конфигурации преобразования предупреждений тестов в ошибки

• (dbt-core#9863) Более информативное сообщение об ошибке при попытке выбрать отключённую модель

• (dbt-labs/dbt#9347) Исправлена настройка преобразования предупреждений тестов в ошибки

• (dbt-labs/dbt#9863) Улучшено сообщение об ошибке при попытке выбрать отключённую модель

• Тесты, тесты, тесты. Когда вы открываете PR, будут запущены тесты и проверки кода. (По соображениям безопасности некоторые из них могут потребовать одобрения мейнтейнера.) Мы не будем мержить PR с падающими тестами. Если вы не уверены, почему тест не проходит, пожалуйста, сообщите об этом — мы постараемся вместе разобраться в причинах.

• Contributor License Agreement (CLA): Это соглашение гарантирует, что мы можем принять ваш код, не беспокоясь о неожиданных последствиях для авторских прав или лицензирования open source или source-available ПО dbt. Подробнее см.: "Contributor License Agreements"

• Changelog: В проектах, где в каждом релизе содержится большое количество изменений, нам нужен надежный способ показать, что именно было включено. Конкретный механизм может отличаться в зависимости от репозитория, поэтому обращайте внимание на инструкции о том, как обновлять changelog.

• Тесты, тесты, тесты. Когда вы открываете PR, запускаются тесты и проверки кода. (Из соображений безопасности для запуска некоторых из них может потребоваться одобрение сопровождающего проекта.) Мы не принимаем PR с непрошедшими тестами. Если вы не уверены, почему тест завершается с ошибкой, сообщите нам, и мы постараемся разобраться вместе.

• Лицензионное соглашение с участником (CLA): Оно позволяет нам принимать ваш код, не опасаясь непредвиденных последствий для авторских прав или лицензий на программное обеспечение dbt с открытым или доступным для просмотра исходным кодом. Подробнее читайте в разделе: «Лицензионные соглашения с участниками»

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

• Метка Semver: В некоторых репозиториях каждый пул-реквест должен иметь ровно одну метку: semver:patch (исправления ошибок и другие безопасные изменения) или semver:minor (новые возможности, не нарушающие обратную совместимость); метка semver:major не допускается. В таких репозиториях CI проверяет соблюдение этого требования.

Включение изменений в релизы

dbt v1

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

dbt v2

dbt v2 выпускается непрерывно и включает весь код и все функциональные возможности, доступные в слое с открытым исходным кодом, а также дополнительные возможности. Номера версий dbt OSS и dbt v2 сходятся на v2.0.0.

Мажорная версия нашего продукта с открытым исходным кодом построена на среде выполнения v2. Изменения в dbt-core, предназначенные для серии v2.x, подчиняются тем же принципам, что и для v1.x: исправления ошибок и возможности с обратной совместимостью включаются в ближайший выпуск.

Нашли ошибку?

Создать GitHub Issue