Руководство по оформлению коммитов

Настоящий документ определяет правила оформления Git-коммитов в проекте YaoXiang и призван поддерживать историю коммитов ясной, читаемой и понятной.

Содержание

Формат коммита
Типы коммитов
Полный справочник по Emoji
Область изменений (scope)
Управление версиями
Правила оформления сообщений
Языковые правила
🔖 Коммит релиза
Примеры
Использование шаблона коммита
Часто задаваемые вопросы

Формат коммита

ОЧЕНЬ ВАЖНО!!!!!! НЕ ЗАБУДЬТЕ!!! Все сообщения коммитов должны соответствовать следующему формату:

:emoji_код: type(scope): Тема (на китайском)

[Необязательное тело сообщения]

[Необязательный колонтитул]

⚠️ Важно: Необходимо использовать emoji-код (например, :sparkles:), а не сам символ emoji напрямую.
Рекомендуется использовать сообщения коммитов на китайском языке для обеспечения единообразия командного общения.

Составные части

Часть	Описание	Обязательно
emoji_код	Эмодзи-идентификатор типа коммита	✅
type	Тип коммита	✅
scope	Область влияния	✅
subject	Краткое описание (на китайском, до 50 символов)	✅
body	Подробное описание (необязательно)	❌
footer	Критические изменения или закрытие issue (необязательно)	❌

Типы коммитов

emoji-код	type	Описание
✨	feat	Новая функциональность
🐛	fix	Исправление бага
📝	docs	Только изменения в документации
💄	style	Форматирование кода (без влияния на функциональность)
♻️	refactor	Рефакторинг кода
⚡	perf	Оптимизация производительности
✅	test	Добавление или изменение тестов
🔧	chore	Изменения в инструментах сборки и вспомогательных инструментах
🏗️	build	Изменения в системе сборки
🚀	ci	Изменения в конфигурации CI

Полный справочник по Emoji

Ниже приведён полный список emoji, совместимый с проектом gitmoji, из которого можно выбирать подходящий emoji в зависимости от содержания коммита:

emoji	emoji-код	Описание коммита
🎨	`:art:`	Улучшение структуры/формата кода
⚡️	`:zap:` / `:racehorse:`	Повышение производительности
🔥	`:fire:`	Удаление кода или файлов
🐛	`:bug:`	Исправление бага
🚑	`:ambulance:`	Важный патч
✨	`:sparkles:`	Внедрение новой функциональности
📝	`:memo:`	Написание документации
🚀	`:rocket:`	Развёртывание функциональности
💄	`:lipstick:`	Обновление UI и файлов стилей
🎉	`:tada:`	Начальный коммит
✅	`:white_check_mark:`	Добавление тестов
🔒	`:lock:`	Исправление проблем безопасности
🍎	`:apple:`	Исправления для macOS
🐧	`:penguin:`	Исправления для Linux
🏁	`:checkered_flag:`	Исправления для Windows
🤖	`:robot:`	Исправления для Android
🍏	`:green_apple:`	Исправления для iOS
🔖	`:bookmark:`	Тег релиза/версии
🚨	`:rotating_light:`	Удаление предупреждений линтера
🚧	`:construction:`	Работа в процессе
💚	`:green_heart:`	Исправление проблем CI-сборки
⬇️	`:arrow_down:`	Откат зависимости
⬆️	`:arrow_up:`	Обновление зависимости
📌	`:pushpin:`	Фиксация зависимости на конкретной версии
👷	`:construction_worker:`	Добавление системы CI-сборки
📈	`:chart_with_upwards_trend:`	Добавление кода аналитики или трекинга
♻️	`:recycle:`	Рефакторинг кода
🔨	`:hammer:`	Крупный рефакторинг
➖	`:heavy_minus_sign:`	Удаление зависимости
🐳	`:whale:`	Работа, связанная с Docker
➕	`:heavy_plus_sign:`	Добавление зависимости
🔧	`:wrench:`	Изменение конфигурационных файлов
🌐	`:globe_with_meridians:`	Интернационализация и локализация
✏️	`:pencil2:`	Исправление опечаток
💩	`:hankey:`	Написание плохого кода, требующего доработки
⏪️	`:rewind:`	Откат изменений
🔀	`:twisted_rightwards_arrows:`	Слияние веток
📦	`:package:`	Обновление скомпилированных файлов или пакетов
👽	`:alien:`	Обновление кода из-за изменений внешнего API
🚚	`:truck:`	Перемещение или переименование файлов
📄	`:page_facing_up:`	Добавление или обновление лицензии
💥	`:boom:`	Внесение критических изменений
🍱	`:bento:`	Добавление или обновление ресурсов
👌	`:ok_hand:`	Обновление кода по результатам код-ревью
♿️	`:wheelchair:`	Улучшение доступности
💡	`:bulb:`	Документирование исходного кода
🍻	`:beers:`	Написание кода в состоянии «навеселе»
💬	`:speech_balloon:`	Обновление текста и надписей
🗃️	`:card_file_box:`	Изменения, связанные с базой данных
🔊	`:loud_sound:`	Добавление логирования
🔇	`:mute:`	Удаление логирования
👥	`:busts_in_silhouette:`	Добавление контрибьюторов
🚸	`:children_crossing:`	Улучшение пользовательского опыта/удобства использования
🏗️	`:building_construction:`	Архитектурные изменения
📱	`:iphone:`	Работа над адаптивным дизайном
🤡	`:clown_face:`	Ироничное отношение к чему-либо
🥚	`:egg:`	Добавление пасхалки
🙈	`:see_no_evil:`	Добавление или обновление файла .gitignore
📸	`:camera_flash:`	Добавление или обновление снэпшотов

Область изменений (scope)

Область изменений основывается на структуре каталога src/ проекта. Необходимо использовать только следующие предопределённые scope:

Модули верхнего уровня

Scope	Соответствующий каталог	Описание
`frontend`	`src/frontend/`	Фронтенд: лексический анализ, парсинг, проверка типов
`middle`	`src/middle/`	Промежуточный слой: IR, оптимизации, мономорфизация
`backends`	`src/backends/`	Бэкенд: интерпретатор, runtime, REPL
`std`	`src/std/`	Стандартная библиотека
`formatter`	`src/formatter/`	Форматировщик кода
`lsp`	`src/lsp/`	Language Server Protocol
`package`	`src/package/`	Менеджер пакетов
`util`	`src/util/`	Утилиты: диагностика, кэширование, i18n

Подмодули фронтенда

Scope	Соответствующий каталог	Описание
`parser`	`src/frontend/core/parser/`	Синтаксический парсер
`lexer`	`src/frontend/core/lexer/`	Лексический анализатор
`typecheck`	`src/frontend/core/typecheck/`	Проверка типов
`types`	`src/frontend/core/types/`	Определение системы типов

Подмодули промежуточного слоя

Scope	Соответствующий каталог	Описание
`codegen`	`src/middle/passes/codegen/`	Генерация кода (байткод)
`monomorphize`	`src/middle/passes/monomorphize/`	Проход мономорфизации
`lifetime`	`src/middle/passes/lifetime/`	Анализ времени жизни

Подмодули бэкенда

Scope	Соответствующий каталог	Описание
`repl`	`src/backends/dev/repl/`	Интерактивная командная строка REPL
`shell`	`src/backends/dev/shell.rs`	Обработка команд shell
`runtime`	`src/backends/runtime/`	Среда выполнения

Scope для документации

Scope	Описание
`docs`	Общие обновления документации
`design`	Спецификации дизайна языка (RFC)
`plan`	Документы с планами реализации

Прочие scope

Scope	Описание
`build`	Система сборки, конфигурация Cargo
`ci`	Конфигурация CI/CD (GitHub Actions)
`test`	Вопросы, связанные с тестированием
`release`	Вопросы, связанные с релизами
`meta`	Метаконфигурация проекта (.claude, .gitignore и т.п.)

Правила оформления сообщений

Управление версиями

Номер версии определяется в поле version файла Cargo.toml в корне проекта:

toml

[package]
version = "0.7.2"

Применяется семантическое версионирование MAJOR.MINOR.PATCH:

Тип версии	Описание	Пример
major	Крупное обновление, несовместимые изменения API	0.7.2 → 1.0.0
minor	Новая функциональность, обратно совместимо	0.7.2 → 0.8.0
patch	Исправление багов, обратно совместимо	0.7.2 → 0.7.3

⚠️ При выпуске релиза обновляйте номер версии в Cargo.toml в ветке dev, а после слияния PR в main CI автоматически создаст тег и релиз. Не создавайте тег вручную, иначе CI пропустит процесс релиза.

Процесс релиза через CI

Релиз автоматически выполняется через GitHub Actions (release.yml) по следующему процессу:

1. В ветке dev обновите поле version в Cargo.toml
2. cargo build для обновления Cargo.lock
3. Сделайте коммит в формате релиза (см. 🔖 Коммит релиза ниже)
   - сообщение коммита должно содержать все изменения с момента предыдущего релиза
     (то есть полное содержимое PR)
4. Создайте PR из dev в main
5. Слейте PR в main
6. CI автоматически проверяет:
   - читает версию из Cargo.toml → "v{version}"
   - проверяет, существует ли уже такой тег
   - не существует → запускает полный процесс релиза
   - существует → пропускает (повторная публикация не выполняется)
7. CI автоматически:
   - параллельно: кросс-платформенная сборка (Linux/Windows/macOS) + аудит безопасности + тесты
   - после прохождения всех проверок: создание тега, упаковка артефактов, публикация GitHub Release

Ключевые правила

Правило	Описание
Не создавайте теги вручную	CI решает, публиковать ли релиз, по наличию тега; ручное создание тега приведёт к пропуску CI
Версия обновляется в dev	Коммит релиза выполняется в dev и попадает в main через PR
Коммит релиза содержит полный changelog	Сообщение коммита должно содержать все изменения этого релиза, т.к. оно становится описанием PR
Не сливайте main обратно в dev	После слияния PR ветка dev синхронизируется автоматически, обратное слияние не требуется

Правила оформления сообщений

Языковые правила

Рекомендуется использовать сообщения коммитов на китайском языке для обеспечения единообразия командного общения.

Subject пишется на китайском, кратко и ясно
В body можно подробно описать на китайском
Специальные технические термины допускается оставлять на английском

Subject (тема)

Пишется на китайском, кратко и ясно
Длина не более 50 символов
Без точки в конце

Body (тело сообщения)

Подробно описывает причину и способ изменений
Каждая строка не должна превышать 72 символа
Для перечисления пунктов используйте - или *

Критические изменения: начинаются с BREAKING CHANGE:
Закрытие Issue: используйте 关闭 #123 или 修复 #456 (оставлено на китайском согласно оригиналу)

Примеры

✨ feat — новая функциональность

:sparkles: feat(parser): 添加闭包语法解析支持

实现闭包表达式解析：
- 支持 |args| body 简写语法
- 支持 move 语义捕获
- 添加闭包类型推断

关闭 #42

🐛 fix — исправление бага

:bug: fix(repl): 修复多行输入时补全器失效的问题

SessionREPL 在多行模式下未正确注册补全器，
导致 Tab 补全无法触发。

修复 #128

📝 docs — обновление документации

:memo: docs(design): 更新所有权模型与类型系统规范

同步 RFC-009 和 RFC-011 的最新设计变更。

♻️ refactor — рефакторинг

:recycle: refactor(typecheck): 分离原语值类型与 Dup 浅拷贝语义

将 MonoType 中的值类型和拷贝语义解耦，
消除 match 分支中的特殊情况。

⚡️ perf — оптимизация производительности

:zap: perf(types): 优化 const generic 求值性能

为递归求值添加深度限制（默认 128），
避免恶意构造的类型表达式导致栈溢出。

✅ test — тесты

:white_check_mark: test(typecheck): 补充 scope VarInfo 可变性测试

覆盖场景：
- 不可变绑定的只读访问
- mut 绑定的可变性追踪
- 跨作用域的可变性传播

🔧 chore — прочее

:wrench: chore(build): bump rand, hashbrown, tempfile, ron, clap

升级 6 个生产依赖至最新稳定版本。

🚀 ci — конфигурация CI

:rocket: ci: 修复 nightly 构建 Rust 版本过低的问题

将 RUST_TOOLCHAIN 从 1.91.0 更新至 1.96.0，
匹配 Cargo.toml 中的 rust-version 要求。

💄 style — форматирование

:lipstick: style(frontend): 应用 cargo fmt 格式化

统一函数签名的换行风格。

🔖 Коммит релиза

Если данный коммит является релизом (Release), необходимо строго следовать следующим правилам:

Формат коммита релиза

:bookmark: V<номер_версии>: <заголовок_релиза>

## 📦 Информация о версии

**Дата выпуска:** YYYY-MM-DD

**Номер версии:** <старая_версия> → <новая_версия>

---

## ✨ Новая функциональность

### <модуль_функциональности>
- :sparkles: feat(<scope>): <описание_функциональности>

---

## ♻️ Рефакторинг и оптимизация

- :recycle: refactor(<scope>): <описание_рефакторинга>

---

## 🐛 Исправления багов

- :bug: fix(<scope>): <описание_исправления>

---

## 🔧 Прочие изменения

- :wrench: chore: <описание_изменения>

---

## 📦 Новые файлы

- `<путь_к_файлу>` - <описание_файла>

---



### Требования к коммиту релиза

1. **Заголовок сообщения**: должен использовать формат `:bookmark:` + `V<номер_версии>`
2. **Номер версии**: должен соответствовать семантическому версионированию
3. **Полнота содержимого**: должен включать описание **всех коммитов** с момента предыдущего релиза
4. **Классификация по типам**: организуйте содержимое по типам `feat`, `fix`, `refactor`, `chore` и т.д.

### Пример коммита релиза

🔖 V0.7.2: REPL 重写与类型系统改进

📦 版本信息

发布日期: 2026-06-01

版本号: 0.7.1 → 0.7.2

✨ 新功能

✨ feat(typecheck): 实现泛型类型参数自动推断
✨ feat(typecheck): 添加 MonoType::Generic 结构化泛型表示
feat: 接入 CLI REPL 命令到 SessionREPL

♻️ 重构优化

♻️ refactor(backends): 移除 tui_repl 模块，重写为 SessionREPL
♻️ refactor(typecheck): scope 变量存储引入 VarInfo 追踪可变性
♻️ refactor(typecheck): 分离原语值类型与 Dup 浅拷贝语义

🐛 Bug 修复

🐛 fix(repl): 配置默认 REPL 历史记录，修复 shell evaluate_code
🐛 fix(repl): 注册补全器并修复多行输入
🐛 fix(repl): 移除 wrap_code 中多余的分号以保留表达式值

⚡ 性能优化

⚡ perf(types): 为 const generic 求值添加递归深度限制

🔧 其他变更

🔧 chore(build): bump rand, hashbrown, tempfile, ron, clap, owo-colors
✅ test(typecheck): 补充 scope VarInfo 可变性测试

Шаблон для справки

Документ релиза оформляйте в соответствии с шаблоном release.md.

1. Настройка шаблона коммита

bash

# Выполните в корне проекта
git config commit.template .gitmessage.txt

2. Файл шаблона

Файл .gitmessage.txt в корне проекта имеет следующий формат:

# emoji代码 type(scope): 主题（中文）
#
# 主体内容（可选）
#
# 页脚（可选）
#
# Types: ✨feat, 🐛fix, 📝docs, 💄style, ♻️refactor, ⚡️perf, ✅test, 🔧chore, 🚀ci, 🔖release
# Scopes: frontend, parser, lexer, typecheck, types, middle, codegen,
#         monomorphize, lifetime, backends, repl, shell, runtime,
#         std, formatter, lsp, package, util, docs, design, plan,
#         build, ci, test, release, meta
#
# 示例:
# ✨ feat(db): 添加批量删除待办功能
# 🐛 fix(provider): 修复计时器后台恢复问题
#
# 发版格式: 🔖 V1.0.0: 发版标题

Часто задаваемые вопросы

В: Как выбрать тип коммита?

feat: изменения функциональности, видимые пользователю
fix: исправление проблем, о которых сообщили пользователи
docs: README, комментарии и другая документация
chore: обновления зависимостей, конфигурационные файлы
refactor: оптимизация кода без изменения поведения

В: Когда следует разделять коммит?

Каждый коммит должен делать одну вещь
Связанную функциональность объединяйте в один коммит, несвязанную — разделяйте
Следуйте принципу атомарных коммитов (Atomic Commits)

Справочные материалы

Conventional Commits
gitmoji
emoji.md — полный список Emoji
release.md — шаблон релиза

💡 Совет: Поддерживайте атомарность коммитов и ясность описаний — это делает код-ревью и откат более эффективными!

Руководство по оформлению коммитов ​

Содержание ​

Формат коммита ​

Составные части ​

Типы коммитов ​

Полный справочник по Emoji ​

Область изменений (scope) ​

Модули верхнего уровня ​

Подмодули фронтенда ​

Подмодули промежуточного слоя ​

Подмодули бэкенда ​

Scope для документации ​

Прочие scope ​

Правила оформления сообщений ​

Управление версиями ​

Процесс релиза через CI ​

Ключевые правила ​

Правила оформления сообщений ​

Языковые правила ​

Subject (тема) ​

Body (тело сообщения) ​

Footer (колонтитул) ​

Примеры ​

✨ feat — новая функциональность ​

🐛 fix — исправление бага ​

📝 docs — обновление документации ​

♻️ refactor — рефакторинг ​

⚡️ perf — оптимизация производительности ​

✅ test — тесты ​

🔧 chore — прочее ​

🚀 ci — конфигурация CI ​

💄 style — форматирование ​

🔖 Коммит релиза ​

Формат коммита релиза ​

📦 版本信息 ​

✨ 新功能 ​

♻️ 重构优化 ​

🐛 Bug 修复 ​

⚡ 性能优化 ​

🔧 其他变更 ​

Шаблон для справки ​

1. Настройка шаблона коммита ​

2. Файл шаблона ​

Часто задаваемые вопросы ​

В: Как выбрать тип коммита? ​

В: Когда следует разделять коммит? ​

Справочные материалы ​

Руководство по оформлению коммитов

Содержание

Формат коммита

Составные части

Типы коммитов

Полный справочник по Emoji

Область изменений (scope)

Модули верхнего уровня

Подмодули фронтенда

Подмодули промежуточного слоя

Подмодули бэкенда

Scope для документации

Прочие scope

Правила оформления сообщений

Управление версиями

Процесс релиза через CI

Ключевые правила

Правила оформления сообщений

Языковые правила

Subject (тема)

Body (тело сообщения)

Footer (колонтитул)

Примеры

✨ feat — новая функциональность

🐛 fix — исправление бага

📝 docs — обновление документации

♻️ refactor — рефакторинг

⚡️ perf — оптимизация производительности

✅ test — тесты

🔧 chore — прочее

🚀 ci — конфигурация CI

💄 style — форматирование

🔖 Коммит релиза

Формат коммита релиза

📦 版本信息

✨ 新功能

♻️ 重构优化

🐛 Bug 修复

⚡ 性能优化

🔧 其他变更

Шаблон для справки

1. Настройка шаблона коммита

2. Файл шаблона

Часто задаваемые вопросы

В: Как выбрать тип коммита?

В: Когда следует разделять коммит?

Справочные материалы