Гайдлайны

Гайдлайны для Pull Request

Философия, которую мы настоятельно рекомендуем:

Перед созданием PR создайте issue.

Цель — отделить проблему от возможных решений.

Bug-фиксы: для маленького бага PR можно открыть сразу, но настоятельно рекомендуется создать issue с описанием. Это полезно, если конкретный фикс не примут, но проблему нужно отслеживать. Помните, что мейнтейнеры оставляют за собой право принимать или отклонять PR'ы — поэтому лучше отделять issue от кода. В отдельных случаях мейнтейнеры могут попросить создать отдельный issue от PR перед продолжением.

Refactor: небольшой рефакторинг может быть отдельным PR с описанием, что и зачем. При вопросах мейнтейнер может попросить сначала открыть #LIP (Liteset Improvement Proposal).

Feature/большие изменения: если вы планируете изменить публичный API или сделать нетривиальные изменения в реализации — сначала откройте #LIP (Liteset Improvement Proposal), чтобы договориться о направлении до значительных усилий. PR можно прислать вместе с ним (иногда нужно для демонстрации), но согласуем подход до review/merge.

В целом маленькие PR ревьюить проще, чем большие. Лучшая практика — разбивать работу на меньшие независимые PR'ы со ссылкой на один issue. Это сильно сократит время turn-around'а.

Если работа ещё не готова к merge'у — создайте Draft PR. Это позволит мейнтейнерам и CI приоритезировать зрелые PR'ы.

И последнее: никогда не отправляйте PR, который оставит main-ветку в сломанном состоянии. Если PR — часть многошаговой большой фичи и не работает сам — создайте feature-ветку и мерджите все связанные PR'ы в неё, прежде чем мерджить feature-ветку в main.

Протокол

Авторство

Заполните все секции PR-template.
В заголовке используйте семантический префикс (по Karma):
- feat (новая фича)
- fix (баг-фикс)
- docs (изменения документации)
- style (форматирование, точки с запятой; без логических изменений)
- refactor (рефакторинг кода)
- test (добавление/рефакторинг тестов; без логики)
- chore (обновление задач и т. п.; без логики)
- perf (производительность)
- build (build-инструменты, Docker)
- ci (test runner, GitHub Actions)
- other (что-то иное — должно быть редко!)
- Примеры:
  - feat: export charts as ZIP files
  - perf(api): improve API info performance
  - fix(chart-api): cached-indicator always shows value is cached
Префикс [WIP] в заголовке — если PR не готов к ревью. Рекомендуется создать PR с [WIP] и убрать его, пройдя CI и просмотрев свои изменения хотя бы раз.
Если в PR есть потенциально breaking change — поставьте ! после семантического префикса перед двоеточием: feat!: Added foo functionality to bar.
Скриншоты/GIF'ы: для UI-изменений приложите before/after скриншоты или GIF.
- Рекомендуемые инструменты: Kap, LICEcap, Skitch.
- Без скриншота committers пометят PR лейблом need:screenshot и не будут ревьюить, пока скриншот не появится.
Зависимости: аккуратно с новыми зависимостями, избегайте лишних.
- Для Python — добавьте в pyproject.toml с указанием ограничений и в requirements.txt с пинной версией для воспроизводимости сборки.
- Для TypeScript/JavaScript — в package.json.
Тесты: PR должен включать тесты — doctests, unit-тесты или оба. Все ошибки и упавшие тесты — починить. Как запускать — см. Testing.
Документация: если PR добавляет функциональность — документация обновляется в этом же PR.
CI: ревьюверы не ревьюят, пока CI не зелёный. Иногда тесты flaky — закройте/откройте PR, чтобы перезапустить CI. Если проблема устойчивая — сообщите. После фикса CI в main — rebase'ните свой PR.
Code coverage: не уменьшайте.
Уберите [WIP], когда готовы к ревью. PR может быть смержен сразу после approve — убедитесь, что готовы.
Если PR не готов к ревью и неактивен > 30 дней — закроем его за неактивность. Автор может реоткрыть.

Ревью

Конструктивный тон.
Если нужны изменения — чётко напишите, что именно сделать перед approve.
Если просят обновить PR — не создавайте новый, push'те в ту же ветку.
Committers оставляют за собой право отклонить PR; в отдельных случаях — попросить открыть issue.

Тестовые окружения

Члены org могут поднять эфемерное тестовое окружение прямо из PR — оставьте комментарий с (только) командой /testenv up.
- Членство в org должно быть публичным, иначе валидация не сработает.
Feature-флаги задаются префиксом FEATURE_:
- Формат: /testenv up FEATURE_<имя>=true|false
- Пример: /testenv up FEATURE_DASHBOARD_NATIVE_FILTERS=true
- Несколько флагов — через пробел.
Скрипт workflow создаст комментарий с адресом и логином окружения.
Тестовые окружения создаются после успешного завершения Docker build CI.
Тестовые окружения не обновляются автоматически при новых коммитах.
Тестовые окружения пока не поддерживают async-воркеров (планируется).
При закрытии PR окружение выключается.

Merge

Минимум один approve.
Обычно PR висит открытым минимум 24 часа перед merge'ом.
После merge'а — закройте соответствующий issue.

Ответственность после merge

Мейнтейнеры могут связаться с автором PR, если PR создал новые проблемы.
Мейнтейнеры могут откатить ваши изменения, если найдена критическая проблема (например, сломан CI main'а).

Управление issues и PR

Чтобы обрабатывать поток issues/PR, committers читают их и помечают лейблами для категоризации и помощи контрибьюторам в выборе областей для участия.

Цели triage:

Для issues: категоризировать, отсеивать, помечать необходимые действия от автора.
Для PR: категоризировать, помечать действия от автора. Если готов к ревью — действия от ревьюверов.

Сначала добавьте Category labels (a.k.a. hash labels). У каждого issue/PR должна быть одна hash-метка (кроме спама). Лейблы с # определяют тип:

Лейбл	для Issue	для PR
`#bug`	Баг-репорт	Баг-фикс
`#code-quality`	Описание проблемы кода, архитектуры, продуктивности	Рефакторинг, тесты, инструменты
`#feature`	Запрос новой фичи	Реализация новой фичи
`#refine`	Предложение улучшения вроде корректировки отступов или UI-стиля (исключая фичи, баг-фиксы и рефакторинг).	Реализация подобных улучшений (исключая фичи, баг-фиксы и рефакторинг).
`#doc`	Документация	Документация
`#question`	Troubleshooting: установка, локальный запуск, как сделать. Может стать `#bug`.	N/A
`#LIP`	Liteset Improvement Proposal (дизайн / изменение публичного API)	N/A

Затем — другие лейблы:

Descriptive labels (.ui, .js, .install, .backend...) — описывают детали. Можно несколько или ноль.
Need labels (need:rebase, need:update, need:screenshot) — описывают необходимые действия для прогресса.
Risk labels (risk:db-migration) — описывают риск принятия PR. Цель — лучше понимать impact и привлекать внимание для PR'ов с более тщательным тестированием.
Status labels — abandoned, wontfix, cant-reproduce и т. д. Issue/PR'ы, которые отклонены или закрыты без завершения, должны иметь один или несколько status-лейблов.
Version labels — паттерн vx.x (v0.28). На issues — версия, в которой нашли баг. На PR'ах — первый релиз, который PR войдёт.

Committers могут менять заголовок issue/PR, если автор недостаточно описательный.

Если PR прошёл CI и не имеет need: лейблов — он готов к ревью, добавьте review и/или design-review.

Issue/PR неактивные >= 30 дней — закрываем. Без status-лейбла — добавьте inactive.

При создании PR, если он должен войти в конкретный релиз — поставьте version-лейбл. Например, для включения в Liteset 1.1 — v1.1.

Гайдлайны по revert'у

Откат изменений, ломающих main, — нормальная и ожидаемая часть процесса разработки. Последствия изменения не всегда понятны полностью. Что учитывать при принятии решения о revert'е:

Доступность автора PR: если автор или мерджер доступен и может починить за разумное время — это аргумент против revert'а.
Серьёзность проблемы: насколько проблема критична? Блокирует ли проект? Влияет ли на пользователей? Какой процент пользователей затронут?
Размер отменяемого изменения: revert маленького PR гораздо безопаснее revert'а массивного multi-PR изменения.
Возраст отменяемого изменения: revert недавнего PR проще, чем старого. Баг в старом PR вряд ли создаёт массовые серьёзные проблемы.
Риск самого revert'а: не сломает ли revert критичную функциональность? Не страшнее ли лекарство болезни?
Сложность фикса: при понятном решении, возможно, лучше фикс, чем revert.

Если решили revert'ить — обязанности контрибьютора, выполняющего revert:

Связаться с заинтересованными: автор PR и мерджер должны быть проинформированы.
Предоставить чёткие шаги воспроизведения: проблема должна быть понятна и воспроизводима автором.
Прогнать revert через ревью: revert должен быть одобрен другим committer'ом.

Гайдлайны по дизайну

Капитализация

Sentence case

Используйте sentence case (только первая буква заглавная) для всего в UI (за исключениями**).

Sentence case — преимущественно lowercase. Заглавная — только в начале первого слова и в случаях, требующих заглавной:

Proper nouns. Объекты в продукте не считаются именами собственными — dashboards, charts, saved queries и т. д. Названия фич — SQL Lab, Preset Manager — являются именами собственными.
Аббревиатуры (CSS, HTML).
При ссылках на UI labels, которые сами уже капитализированы (например, заголовки страниц — Dashboards page, Charts page, Saved queries page).
Пользовательский ввод, отражаемый в UI — например, имя dashboard tab'а.

Sentence case vs. Title case: Title case: "A Dog Takes a Walk in Paris" Sentence case: "A dog takes a walk in Paris"

Почему sentence case?

Считается самой быстрой для чтения.
Легче отличать common nouns от proper.

Как ссылаться на UI-элементы

При описании UI-элемента используйте ту же капитализацию, что и в UI.

Например, поле «Name» в UI — пишется «Name input field». Кнопка с текстом «Save» — «Save button».

Если страница называется «Settings» — пишется «Edit your personal information on the Settings page».

Часто страница имеет то же имя, что и объекты в ней. В этом случае — ссылайтесь на страницу как в UI, а на объекты как common nouns:

Upload a dashboard on the Dashboards page
Go to Dashboards
View dashboard
View all dashboards
Upload CSS templates on the CSS templates page
Queries that you save will appear on the Saved queries page
Create custom queries in SQL Lab then create dashboards

**Исключения из sentence case

Input labels, buttons, UI tabs — all caps.
Пользовательские значения (имена колонок, имена tab'ов SQL Lab) — в исходном регистре.

Программные конвенции

Python

Параметры в config.py (доступные через app.config Flask) считаются всегда определёнными и должны читаться напрямую:

blueprints = app.config["BLUEPRINTS"]

а не:

blueprints = app.config.get("BLUEPRINTS")

Иначе возникают проблемы с типами. Первый — List[Callable], второй — Optional[List[Callable]].

В Liteset тот же паттерн применяется к SupersetSettings (pydantic-settings) и к app.state.config Litestar — при чтении ключей из конфига обращайтесь напрямую, без .get() с дефолтом, если вы знаете, что ключ обязан существовать.

Type Hints / типизация

Для ясности, согласованности и читабельности все новые функции должны использовать type hints и содержать docstring.

По PEP-484 синтаксиса для перечисления явно поднимаемых исключений нет — рекомендуется указывать их в docstring:

import math
from typing import Union


def sqrt(x: Union[float, int]) -> Union[float, int]:
    """
    Return the square root of x.

    :param x: A number
    :returns: The square root of the given number
    :raises ValueError: If the number is negative
    """

    return math.sqrt(x)

TypeScript

TypeScript полностью поддерживается и рекомендуется для всех новых фронтенд-компонентов. При модификации существующих функций/компонентов миграция в TypeScript приветствуется, но не обязательна. Примеры миграции — в #9162 и #9180.

Гайдлайны для Pull Request​

Протокол​

Авторство​

Ревью​

Тестовые окружения​

Merge​

Ответственность после merge​

Управление issues и PR​

Гайдлайны по revert'у​

Гайдлайны по дизайну​

Капитализация​

Sentence case​

Как ссылаться на UI-элементы​

**Исключения из sentence case​

Программные конвенции​

Python​

Type Hints / типизация​

TypeScript​