Nikita Kiselev
3cc82e45f0
Some checks are pending
Telegram Mini App Shop Builder / Compute version metadata (push) Waiting to run
Telegram Mini App Shop Builder / Run Frontend tests (push) Waiting to run
Telegram Mini App Shop Builder / Run Backend tests (push) Waiting to run
Telegram Mini App Shop Builder / Run PHP_CodeSniffer (push) Waiting to run
Telegram Mini App Shop Builder / Build module. (push) Blocked by required conditions
Telegram Mini App Shop Builder / release (push) Blocked by required conditions
102 lines
3.2 KiB
Markdown
102 lines
3.2 KiB
Markdown
# 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
|