clickstream-ch-kafka-superset-demo/docs/COMMIT_RULES.md

Commit Rules

Unified commit style for all project contributors. Follows Conventional Commits specification.

Language

• Primary language: Russian
• If language is not specified, use Russian
• For AI-generated commits, Russian is mandatory unless task explicitly sets lang:en
• English is allowed only by explicit instruction (lang:en) or external collaboration requirements
• Do not mix languages in free-text parts of one commit message (subject + body + footer)
• Conventional Commit type(scope) stays in English
• Technical terms (Airflow, ClickHouse, Kafka, MV, DDL) keep as-is

Header Format

<type>(<scope>): <short description>

• Maximum header length: 72 characters
• For Russian subject, use result form (e.g. "добавлено", "исправлено", "обновлено")
• For English subject, use imperative present form (e.g. "add", "fix", "update")
• For English subject, do not use past forms (e.g. "added", "fixed", "updated")
• No trailing period
• Keep subject specific; avoid vague messages like "update", "fix bug", "changes"

Allowed type

Type	Description
feat	New feature
fix	Bug fix
refactor	Code restructuring without behavior change
docs	Documentation only
test	Tests, checks, validations
chore	Maintenance (configs, scripts, hooks)
ci	CI/CD changes
perf	Performance optimization
revert	Revert previous commit

Recommended scope for this repo

Scope	Used for
airflow	DAGs, operators, Airflow config
stg	STG layer tables and pipelines
ods	ODS layer tables and pipelines
dds	DDS layer tables and pipelines
dm	Data mart views and tables
kafka	Kafka topics, producers, consumers
superset	Dashboards, datasets, charts
monitoring	Prometheus, Grafana, alerts
scripts	Shell scripts, automation
docs	Documentation, README, plans
infra	Docker, compose, infrastructure

Body Structure

For non-trivial changes, body is required. Use bullet points for readability.

Body is considered required when at least one condition is true:

• behavior or API/contract changed
• migration, rollback risk, or compatibility impact exists
• more than one meaningful file/module changed
• fix is non-obvious from header alone

Multiline body in CLI (important)

• Do not pass body as one quoted string with \n (it will be stored literally).
• Use multiple -m flags, or -F with heredoc.

Correct:

git commit \
  -m "feat(monitoring): добавлены правила алертов Grafana" \
  -m "- Зачем:
  - нужны ранние сигналы проблем ClickHouse
- Что:
  - добавлен provisioning-файл алертов по failed queries, memory, parts
  - зафиксирован uid источника Prometheus для стабильной привязки
- Проверка:
  - POST /api/admin/provisioning/alerting/reload
  - GET /api/v1/provisioning/alert-rules"

Also correct:

git commit -F- <<'MSG'
feat(monitoring): добавлены правила алертов Grafana

- Зачем:
  - нужны ранние сигналы проблем ClickHouse
- Что:
  - добавлен provisioning-файл алертов по failed queries, memory, parts
  - зафиксирован uid источника Prometheus для стабильной привязки
- Проверка:
  - POST /api/admin/provisioning/alerting/reload
  - GET /api/v1/provisioning/alert-rules
MSG

Template (Russian - default)

<type>(<scope>): <краткое описание результата>

- Зачем:
  - причина изменения
- Что:
  - ключевое изменение 1
  - ключевое изменение 2
- Проверка:
  - как проверено

Template (English - only with lang:en)

<type>(<scope>): <short action description>

- Why:
  - reason for change
- What:
  - key change 1
  - key change 2
- Check:
  - how verified (command/test/smoke-check)

Commit Scope Rules

• One commit = one logical task
• Don't mix feature changes with large refactoring
• Update docs in the same commit where behavior changes

Breaking Changes

Use ! in header for breaking changes:

feat(ods)!: change browser_event table contract

Add footer:

BREAKING CHANGE: column event_type renamed to event_name

Examples

Good examples

feat(superset): добавлен дашборд e-commerce аналитики

- Зачем:
  - нужна визуализация clickstream для бизнеса
- Что:
  - добавлен сервис superset-init в docker-compose
  - добавлены скрипты подключения к ClickHouse
  - добавлены 10 графиков (KPI, traffic, geo, UTM, DQ)
  - добавлены команды superset-* в Makefile
- Проверка:
  - дашборд открывается на http://localhost:8088
  - все графики загружают данные из dm.v_events_enriched

fix(kafka): исправлен путь volume для режима KRaft

- Зачем:
  - Kafka не стартует из-за permission denied на /tmp/kraft-combined-logs
- Что:
  - путь volume изменен на /var/lib/kafka/data
- Проверка:
  - `make up` поднимает Kafka без ошибок

docs(architecture): обновлена схема потоков данных после миграции ODS

chore(scripts): синхронизирован make transform с новым ETL пайплайном

Bad examples (don't do this)

❌ added superset dashboard        # no type, past tense
❌ feat: добавлен дашборд          # no scope
❌ fix: исправлен баг              # no scope, vague and non-actionable
❌ feat(ui): added new filters     # past tense in English subject
❌ feat(airflow): add feature and fix bug and update docs  # multiple concerns
❌ feat(dm): add витрину и почини alert # mixed languages in one message

Quick Reference

# Feature
feat(scope): добавлена новая возможность

# Bug fix
fix(scope): исправлена проблема

# Documentation
docs(scope): обновлена документация

# Refactoring
refactor(scope): упрощена структура без изменения поведения

# Performance
perf(scope): ускорено выполнение

# Maintenance
chore(scope): обновлены служебные настройки

# Feature (lang:en)
feat(scope): add new capability

# Bug fix (lang:en)
fix(scope): correct response parsing

# Documentation (lang:en)
docs(scope): update setup guide