Expectations for dbt contributors
Будь то dbt-core, dbt-fusion, адаптеры, пакеты или даже этот сайт документации, вклад в open source или source-available код, поддерживающий экосистему dbt, — это отличный способ поделиться своими знаниями, прокачать себя как разработчика и внести вклад в сообщество. Цель этой страницы — помочь вам понять, чего ожидать при участии в проектах экосистемы dbt.
Видели ли вы в других проектах какие-то подходы или практики, которые вам нравятся и которые, по вашему мнению, мы могли бы перенять? Откройте обсуждение на форуме сообщества dbt или начните разговор в Slack‑сообществе dbt (например: #community-strategy, #dbt-core-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, чтобы подтвердить, что он решает конкретную проблему для вашей команды на практике, он с большей вероятностью будет объединен.
Иногда это может казаться криком в пустоту, особенно если вы не получаете немедленного ответа. Мы обещаем, что десятки (если не сотни) людей прочитают ваш комментарий, включая нас как хранителей. Все это складывается в реальную разницу.
Практические аспекты
Обсуждения
Обсуждение лучше всего подходит для выдвижения Big Idea, например, совершенно новой возможности в dbt Fusion Engine или в адаптере. Любой может открыть обсуждение, прокомментировать существующее или ответить в ветке.
Когда вы открываете новое обсуждение, вы можете искать подтверждение от других членов сообщества — людей, которые идентифицируют себя с вашим заявлением о проблеме, которым нравится ваша предложенная идея и у которых могут быть свои собственные идеи о том, как ее можно улучшить. Наиболее полезные комментарии предлагают нюансы или желаемые пользовательские впечатления, которые следует учитывать при проектировании и доработке. В отличие от проблемы, нет конкретного изменения кода, которое бы "решило" обсуждение.
Если в ходе обсуждения мы достигнем консенсуса по конкретным элементам предложенного дизайна, мы можем открыть новые проблемы реализации, которые ссылаются на обсуждение для контекста. Эти проблемы свяжут желаемые результаты пользователей с конкретными деталями реализации, приемочным тестированием и оставшимися вопросами, требующими ответа.
Проблемы
Проблема может быть ошибкой, которую вы выявили при использовании продукта или чтении документации. Это также может быть конкретная идея, которую вы предложили для узкого расширения существующей функциональности.
Лучшие практики для проблем
- Проблемы не предназначены для поддержки / устранения неполадок / помощи в отладке. Пожалуйста, ознакомьтесь с поддержкой dbt для получения более подробной информации и предложений о том, как получить помощь.
- Всегда сначала ищите существующие проблемы, чтобы увидеть, не возникла ли у кого-то еще такая же идея / не нашел ли кто-то ту же ошибку, что и вы.
- Многие репозитории dbt предлагают шаблоны для создания проблем, такие как отчет об ошибке или запрос новой функции. Если доступно, пожалуйста, выберите соответствующий шаблон и заполните его по мере возможности. Эта информация помогает нам (и другим) понять вашу проблему.
Вы нашли существующую проблему, которая вас интересует. Что вам следует сделать?
Прокомментируйте ее! Объясните, что вы столкнулись с той же ошибкой или у вас была похожая идея для новой функции. Если проблема включает подробное предложение об изменении, скажите, какие части предложения вам кажутся наиболее убедительными, а какие вызывают у вас сомнения.
Вы открыли новую проблему. Чего вы можете ожидать?
В наших наиболее критичных репозиториях (таких как dbt-core и dbt-fusion) наша цель — реагировать на новые issues как можно быстрее. Такой первоначальный ответ часто представляет собой короткое подтверждение того, что мейнтейнеры знают о проблеме, и служит сигналом того, как мы оцениваем её срочность. В зависимости от характера issue, она может хорошо подходить для внешнего вклада — от вас или другого участника сообщества.
Что, если вы открываете issue в другом репозитории? У нас есть инженерные команды, которые занимаются активной поддержкой dbt-core и его компонентных библиотек (dbt-common + dbt-adapters (сюда также входят адаптеры, поддерживаемые dbt Labs)), а также dbt-fusion (движок следующего поколения, лежащий в основе стандарта dbt). За годы мы опубликовали в open source ряд других программных проектов, и большинство из них не имеют такого же уровня активности или гарантий поддержки. Проверьте, есть ли ответы на другие недавние issues, или когда последний раз в ветку main добавлялся коммит.
Вы не уверены в статусе своей issue. Если ваша issue находится в активно поддерживаемом репозитории и к ней прикреплён лейбл triage, значит мы знаем, что на неё нужно ответить. Если issue прошла триаж, но не была приоритизирована, это может означать следующее:
- предполагаемый scope или пользовательский опыт предлагаемой фичи требуют дальнейшей проработки со стороны мейнтейнера;
- мы считаем, что необходимое изменение кода слишком сложное для внешнего контрибьютора.
Мы постараемся объяснить открытые вопросы или сложность, и когда / почему мы могли бы предвидеть ее приоритизацию.
Автоматизация, которая может нам помочь: Во многих репозиториях мы используем бота, который помечает проблемы как устаревшие, если они не имели никакой активности в течение 180 дней. Это помогает нам держать наш бэклог организованным и актуальным. Мы призываем вас комментировать старые открытые проблемы, которые вас интересуют, чтобы они не были помечены как устаревшие. Вы также всегда можете комментировать закрытые проблемы, чтобы сказать, что вы все еще заинтересованы в предложении.
Метки проблем
Скорее всего, хранитель, который ответит, также добавит несколько меток. Не все эти метки используются в каждом репозитории.
В некоторых случаях правильное решение открытой проблемы может быть косвенно связано с кодовой базой. Правильный путь вперед может быть в другой кодовой базе (мы перенесем ее), обновлении документации или изменении, которое вы можете сделать сами в пользовательском коде. В других случаях проблема может описывать функциональность, которую хранители не хотят или не могут включить в основную кодовую базу. В этих случаях хранитель закроет проблему (возможно, используя метку wontfix) и объяснит, почему.
Некоторые из наиболее распространенных меток объяснены ниже:
| Loading table... |
Pull-запросы
Каждый PR должен быть связан с проблемой. Почему? Прежде чем вы потратите много времени на работу над вкладом, мы хотим убедиться, что ваше предложение будет принято. Вы должны сначала открыть проблему, описав желаемый результат и наметив планируемое изменение. Если вы нашли старую проблему, которая уже открыта, прокомментируйте ее с планом вашей реализации до того, как начнете работу над открытием pull-запроса.
PR должны включать надежное тестирование. Комплексное тестирование в рамках pull-запросов имеет решающее значение для стабильности dbt. Приоритетное внимание к надежному тестированию обеспечивает надежность нашей кодовой базы, минимизирует непредвиденные проблемы и защищает от потенциальных регрессий. Мы не можем объединять изменения, которые могут привести к несовместимости с задокументированными поведениями. Мы понимаем, что создание тщательных тестов часто требует значительных усилий, и ваша приверженность этому процессу значительно способствует общей надежности проекта. Спасибо за вашу приверженность поддержанию целостности нашей кодовой базы и опыта всех, кто использует dbt!
PR проходят два этапа ревью. Сначала мы стараемся дать обратную связь о том, считаем ли мы реализацию подходящей с точки зрения продукта и удобства использования. На этом этапе мы закрываем PR, которые, по нашему мнению, выходят за рамки dbt Core или публичных компонентов dbt Fusion Engine, либо могут привести к непоследовательному пользовательскому опыту. Это важная часть нашей роли как мейнтейнеров; при этом мы всегда открыты к обсуждению и несогласию. Если PR проходит этот первый этап, мы ставим его в очередь на код-ревью, где уже стараемся протестировать изменения самостоятельно и дать подробные комментарии.
Мы получаем больше PR, чем можем тщательно отревьюить, протестировать и смержить. У наших команд ограниченные ресурсы, и наш главный приоритет — поддержание хорошо очерченного и качественного фреймворка для десятков тысяч людей, которые используют его каждую неделю. Поэтому нам приходится отдавать приоритет общей стабильности и запланированным улучшениям, а не длинному хвосту нишевых потенциальных функций. Чтобы повысить шансы на успех, сразу указывайте, по каким именно аспектам вам особенно важна обратная связь, и объясняйте, что будет значить принятие предложенного изменения для вас, вашей команды и других участников сообщества. Небольшие PR, решающие чётко ограниченные задачи, как правило, рассматриваются проще и быстрее. Два примера PR, внесённых участниками сообщества:
- (dbt-core#9347) Исправление конфигурации преобразования предупреждений тестов в ошибки
- (dbt-core#9863) Более информативное сообщение об ошибке при попытке выбрать отключённую модель
Автоматизация, которая может нам помочь: Во многих репозиториях есть шаблон для описаний pull-запросов, который будет включать контрольный список, который должен быть выполнен перед тем, как PR может быть объединен. Вам не нужно делать все это, чтобы получить начальный PR, но это задержит наш процесс проверки. Они включают:
- Тесты, тесты, тесты. Когда вы открываете PR, будут запущены тесты и проверки кода. (По соображениям безопасности некоторые из них могут потребовать одобрения мейнтейнера.) Мы не будем мержить PR с падающими тестами. Если вы не уверены, почему тест не проходит, пожалуйста, сообщите об этом — мы постараемся вместе разобраться в причинах.
- Contributor License Agreement (CLA): Это соглашение гарантирует, что мы можем принять ваш код, не беспокоясь о неожиданных последствиях для авторских прав или лицензирования open source или source-available ПО dbt. Подробнее см.: "Contributor License Agreements"
- Changelog: В проектах, где в каждом релизе содержится большое количество изменений, нам нужен надежный способ показать, что именно было включено. Конкретный механизм может отличаться в зависимости от репозитория, поэтому обращайте внимание на инструкции о том, как обновлять changelog.
Включение в релизные версии
dbt Core
Как исправления ошибок, так и обратно совместимые новые возможности включаются в следующий минорный релиз dbt Core. Исправления регрессий и новых багов, которые присутствовали в первоначальном релизе минорной версии, будут портированы обратно в версии с активной поддержкой. Другие исправления ошибок могут быть перенесены обратно, если у нас есть высокая уверенность, что они имеют узкую область воздействия и не вызовут непреднамеренных побочных эффектов.
dbt Fusion engine
В процессе публичной беты dbt Fusion Engine новые релизы будут выпускаться регулярно. После того как новый движок достигнет стадии General Availability, мы обновим этот документ, добавив долгосрочную стратегию релизов, хотя вы можете ожидать, что она будет похожа на стратегию dbt Core.
