From 140b7112330432458999f6e420961bf1a9260960 Mon Sep 17 00:00:00 2001
From: Dmitry Dementev <me@dementev.space>
Date: Sun, 8 Feb 2026 20:49:18 +0300
Subject: [PATCH] docs(docs): clarify multiline commit body usage

- Why:
  - commit messages with literal \n are hard to read in UI
- What:
  - add explicit rule for multiline body formatting in CLI
  - add correct examples with git commit -m and -F heredoc
- Check:
  - reviewed new section in docs/COMMIT_RULES.md
---
 docs/COMMIT_RULES.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/docs/COMMIT_RULES.md b/docs/COMMIT_RULES.md
index 147fa22..b570bdb 100644
--- a/docs/COMMIT_RULES.md
+++ b/docs/COMMIT_RULES.md
@@ -52,6 +52,43 @@ Unified commit style for all project contributors. Follows [Conventional Commits
 
 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:
+
+```bash
+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:
+
+```bash
+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)
 
 ```