# Changelog Documentation Rules

## General requirements

- **Format**: Markdown
- **Structure**: One version = one page
- **Style**: Professional, concise, without marketing slogans
- **Language**: English
- **Target audience**: Developers and store owners
- **Content**: Only key changes, without unnecessary technical details

## Page structure

### Intro paragraph
- Short release description (1–2 sentences)
- Add 1–2 sentences about key changes
- Mention the main features and improvements

### Sections (strictly in this order)

1. **🚀 Added** – new features and capabilities
2. **✨ Improved** – improvements to existing features
3. **🐞 Fixed** – bug fixes
4. **⚠️ Breaking changes** – non‑backward compatible changes
5. **🔧 Technical changes** – technical changes (separate section)

### Section rules

- **Do NOT** add a section if it has no items
- Use markdown bullet lists, no numbering
- Do not add links unless they are explicitly specified
- Do not add extra explanations, conclusions, or summaries
- Output only the content of the Markdown file, without comments

## Separating changes

### Business logic and processes
Sections "Added", "Improved", "Fixed", "Breaking changes" contain only changes related to:
- Store business processes
- User experience
- Functionality for store owners
- Selling / value‑driven features

### Technical changes
All technical changes go into a separate **🔧 Technical changes** section:
- No subsections, everything in a single list
- Only the most important technical changes
- Do not describe details that are not interesting to end users

## Writing style

### Terminology
- Use English terms (e.g. "navbar", not a localized variant)
- Avoid low‑level technical terms in business sections (e.g. "customer_id" → "automatic customer linking")

### Descriptions

**For key selling features:**
- Provide detailed descriptions
- Highlight capabilities and advantages
- Emphasize value for the user

**For technical changes:**
- Be brief and to the point
- Avoid unnecessary details

**For regular features:**
- Be concise but informative
- Focus on user benefit

## Ordering

### In the "Added" section
Place key selling features **first**:
1. Main page configuration system based on blocks
2. Form builder based on FormKit
3. Yandex.Metrica integration
4. Privacy policy
5. Support for coupons and gift certificates
6. Other features

## Examples of good wording

### ✅ Good
- "Automatic linking of Telegram customers with ECommerce customers: the system automatically finds and links customers from the Telegram shop with existing customers in ECommerce by email or phone number, creating a unified customer base"

### ❌ Bad
- "Saving customer_id with the order to link with ECommerce customers: automatic linking of orders from Telegram with customers in ECommerce, unified customer base"

### ✅ Good
- "Navbar with logo and application name"

### ❌ Bad
- "Navigation bar with logo and application name" (too verbose, no added value)

## What not to include

- Internal development details (tests, static analysis, obfuscation)
- Technical details not interesting to users
- Excessively detailed technical descriptions
- Marketing slogans and calls to action