dbx-commit-messages

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dbx-commit-messages

Guide for writing commit messages in the dbx-components workspace.

dbx-components工作区的提交信息编写指南。

Convention

规范

This project uses @commitlint/config-angular with a restricted set of commit types defined in

.commitlintrc.json

本项目使用**@commitlint/config-angular**规范，允许的提交类型在

.commitlintrc.json

文件中定义。

Format

格式

type(scope): subject
                          <-- blank line required before body
- additional detail line
- another detail line

type - Required. One of the allowed types below.
scope - Optional. Indicates what area of the codebase is affected.
subject - Required. Very brief, lowercase description. No period. The entire first line (
```
type(scope): subject
```
) must be 72 characters or less (enforced by pre-commit hook).
body lines - Optional. Must be separated from the title by a blank line. Each line starts with a dash (
```
-
```
) and gives a short explanation. Use when the title alone is too brief to convey the change. The first body line can continue/clarify the title.

type(scope): subject
                          <-- 正文前必须有空行
- 额外的详情行
- 其他详情行

type - 必填。为下方允许的类型之一。
scope - 选填。标识代码库受影响的区域。
subject - 必填。非常简短的小写描述，不要加句号。第一行整体(
```
type(scope): subject
```
)必须不超过72个字符（由pre-commit钩子强制校验）。
body行 - 选填。必须和标题之间隔一个空行。每一行以短横线(
```
-
```
)开头，给出简短说明，当标题不足以说明变更内容时使用。首行正文可以承接/补充说明标题内容。

Allowed Types (for Developer Use)

允许使用的类型（开发者可用）

Type	When to Use
`refactor`	Code changes that don't add new features or fix user-facing bugs. This is the most common type. Use for restructuring, renaming, style fixes, updating configurations, adding utilities, etc.
`build`	Build system or tooling changes. Commonly used as `build: lint fix` after running linters.
`fix`	Bug fixes for existing functionality.
`test`	Adding or updating tests.
`docs`	Documentation-only changes.
`perf`	Performance improvements.
`checkpoint`	Work-in-progress commit that isn't a complete refactor. Use when saving progress on an incomplete task.
`ai`	Commits related to AI skills, AI-generated content, or AI-specific configuration (e.g., `.claude/` directory changes).
`demo`	Changes to demo applications or example code.

Type	适用场景
`refactor`	不新增功能、也不修复用户侧bug的代码变更。这是最常用的类型，适用于代码重构、重命名、样式修复、配置更新、新增工具函数等场景。
`build`	构建系统或工具链变更，运行lint后通常会提交 `build: lint fix` 。
`fix`	修复现有功能的bug。
`test`	新增或更新测试用例。
`docs`	仅涉及文档的变更。
`perf`	性能优化相关变更。
`checkpoint`	尚未完成的工作进度提交，适用于保存未完成任务的进度。
`ai`	与AI技能、AI生成内容或AI专属配置相关的提交（例如 `.claude/` 目录变更）。
`demo`	演示应用或示例代码的变更。

Reserved Types (Do NOT Use Manually)

保留类型（请勿手动使用）

Type	Reserved For
`feat`	Feature PRs on GitHub only. Never use in direct commits to develop.
`ci`	CircleCI configuration changes only.
`release`	Auto-generated by CircleCI release tooling.
`merge`	Auto-generated when merging main back into develop after a release.

Important:
feat
and any breaking changes (
feat!
,
refactor!
, etc.) are reserved for pull requests. Do not use them in regular commits on the develop branch.

Type	保留用途
`feat`	仅用于GitHub上的功能PR，禁止直接提交到develop分支时使用。
`ci`	仅用于CircleCI配置变更。
`release`	由CircleCI发布工具自动生成。
`merge`	版本发布后将main分支合并回develop时自动生成。

注意：
feat
和所有破坏性变更（
feat!
、
refactor!
等）仅保留给拉取请求使用，请勿在develop分支的常规提交中使用。

Scope Patterns

作用域模式

Scopes are optional but helpful. Common patterns from the project history:

No scope - Most common. Used when the change is general or touches multiple areas.
- ```
refactor: style fixes
```
- ```
build: lint fix
```
Specific component/service name - When the change is focused on one thing.
- ```
refactor: fixed DbxMapboxMapDirective
```
- ```
refactor: added DbxLinkifyService
```

Area description - Brief description of what area was changed.

refactor: updated dbx-grid, dbx-accordion

```
refactor: package.json fixes
```

作用域为选填项，但使用后会更清晰。项目历史中的常用模式：

无作用域 - 最常用，适用于通用变更或涉及多个模块的变更。
- ```
refactor: style fixes
```
- ```
build: lint fix
```

特定组件/服务名称 - 适用于仅修改单一模块的场景。

```
refactor: fixed DbxMapboxMapDirective
```
```
refactor: added DbxLinkifyService
```

区域描述 - 对变更涉及的区域的简短描述。

refactor: updated dbx-grid, dbx-accordion

```
refactor: package.json fixes
```

Style Guide

风格指南

72 character limit - The entire first line must fit within 72 characters. A pre-commit hook enforces this.
Keep it brief - Subjects should be short and to the point. Most commits in this project are 3-6 words.
Subject is lowercase - Start the subject with a lowercase letter.
No period - Don't end the subject with a period.
Past tense or imperative - Both styles are used; past tense is more common (e.g., "added", "fixed", "updated").
Prefer
refactor
- When in doubt between types,
```
refactor
```
is almost always the right choice for regular development work.

72字符限制 - 首行总长度不能超过72个字符，由pre-commit钩子强制校验。
保持简洁 - 主题应当简短切题，本项目的大多数提交主题仅3-6个单词。
主题小写 - 主题首字母小写。
不加句号 - 主题末尾不要加句号。
过去时或祈使句 - 两种风格都允许，过去时更常用（例如"added"、"fixed"、"updated"）。
优先使用
refactor
- 如果不确定选什么类型，常规开发工作几乎都可以用
```
refactor
```
。

Examples

示例

Single-line (most common)

单行提交（最常用）

refactor: style fixes
refactor: updated vitest config
refactor: package.json fixes
build: lint fix
checkpoint: accordion view
ai: moved skills to .claude

refactor: style fixes
refactor: updated vitest config
refactor: package.json fixes
build: lint fix
checkpoint: accordion view
ai: moved skills to .claude

Multi-line (when more detail is needed)

多行提交（需要更多说明时使用）

refactor: updated dbx-grid, dbx-accordion
- added responsive breakpoint support
- fixed column alignment in grid

refactor: fixed early destroy on components
- subscription was completing before cleanup

fix: resolved null reference in form validation
- checked for undefined before accessing nested field

test: added unit tests for object filter
- covers edge cases for empty and nested objects

refactor: updated dbx-grid, dbx-accordion
- 新增响应式断点支持
- 修复网格的列对齐问题

refactor: fixed early destroy on components
- 订阅会在清理前完成

fix: resolved null reference in form validation
- 访问嵌套字段前先检查是否为undefined

test: added unit tests for object filter
- 覆盖空对象和嵌套对象的边界场景

AI Attribution

AI署名

Do not add

Co-Authored-By

or similar attribution trailers by default. Only add AI attribution when the user explicitly grants permission for significant contributions (e.g., large feature implementations or PRs).

默认不要添加

Co-Authored-By

或类似的署名标记，仅当用户明确许可重大贡献（例如大型功能实现或PR）时才添加AI署名。

Common Mistakes to Avoid

需要避免的常见错误

Using
```
feat
```
for regular commits (reserved for PRs)
Using
```
ci
```
for non-CircleCI changes
Starting the subject with an uppercase letter
Adding a period at the end of the subject
Using overly long subjects (keep it scannable)
Missing the blank line between the title and body lines

常规提交使用
```
feat
```
（该类型仅保留给PR使用）
非CircleCI变更使用
```
ci
```
类型
主题首字母大写
主题末尾加句号
主题过长（要保证可读性）
标题和正文之间缺少空行