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: English
• Russian is allowed for internal team convenience
• Technical terms (Airflow, ClickHouse, Kafka, MV, DDL) keep as-is

Header Format

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

• Maximum header length: 72 characters
• Use imperative mood ("add", "fix", "update", not "added", "fixed")
• No trailing period

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.

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): add Grafana alert rules" \
  -m "- Why:
  - need proactive signals for ClickHouse health
- What:
  - add alert provisioning file for failed queries, memory, parts
  - pin Prometheus datasource uid for stable dashboard binding
- Check:
  - POST /api/admin/provisioning/alerting/reload
  - GET /api/v1/provisioning/alert-rules"

Also correct:

git commit -F- <<'MSG'
feat(monitoring): add Grafana alert rules

- Why:
  - need proactive signals for ClickHouse health
- What:
  - add alert provisioning file for failed queries, memory, parts
  - pin Prometheus datasource uid for stable dashboard binding
- Check:
  - POST /api/admin/provisioning/alerting/reload
  - GET /api/v1/provisioning/alert-rules
MSG

Template (English)

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

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

Template (Russian - допустимо)

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

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

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): add e-commerce analytics dashboard

- Why:
  - Business needs visualization for clickstream analysis
- What:
  - Add superset-init service to docker-compose
  - Create Python scripts for ClickHouse connection
  - Add 10 charts (KPI, traffic, geo, UTM, DQ)
  - Makefile commands superset-*
- Check:
  - Dashboard opens at http://localhost:8088
  - All charts load data from dm.v_events_enriched

fix(kafka): correct volume path for KRaft mode

- Why:
  - Kafka fails to start with permission denied on /tmp/kraft-combined-logs
- What:
  - Change volume path to /var/lib/kafka/data
- Check:
  - make up starts Kafka successfully

docs(architecture): update data flow diagram after ODS migration

chore(scripts): sync make transform with new ETL pipeline

Bad examples (don't do this)

❌ added superset dashboard        # no type, past tense
❌ feat: добавлен дашборд          # no scope, mixed languages
❌ fix: исправлен баг              # no scope, past tense, vague description
❌ feat(airflow): add feature and fix bug and update docs  # multiple concerns

Quick Reference

# Feature
feat(scope): add something new

# Bug fix
fix(scope): correct something

# Documentation
docs(scope): update something

# Refactoring
refactor(scope): restructure something

# Performance
perf(scope): optimize something

# Maintenance
chore(scope): update something