Back to Details

using-commit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Guía de Conventional Commits

Conventional Commits 指南

Guía completa para escribir mensajes de commit estructurados siguiendo la especificación de Conventional Commits.
遵循Conventional Commits规范编写结构化提交信息的完整指南。

Descripción General

概述

Conventional Commits es una especificación para escribir mensajes de commit legibles por humanos y máquinas. Esta skill proporciona:
  • Especificación completa basada en conventionalcommits.org
  • Tipos estándar de commits y cuándo usarlos
  • Formato para scopes, breaking changes y footers
  • Patrones para commits Multi-módulo y relacionados
  • Mejores prácticas con ejemplos buenos y malos
  • Integración con herramientas de versionado semántico
Conventional Commits是一种用于编写人类和机器均可阅读的提交信息的规范。本技能提供：
  • 基于conventionalcommits.org的完整规范说明
  • 标准提交类型及其适用场景
  • 作用域（scope）、破坏性变更及页脚的格式规范
  • 多模块及关联提交的模式
  • 包含正反示例的最佳实践
  • 与语义化版本控制工具的集成方案

Requisitos Previos

前置要求

  • Git instalado y configurado
  • Conocimientos básicos de control de versiones
  • Opcional: Herramientas como commitizen, commitlint, standard-version
  • Opcional: Configuración de hooks con husky
  • 已安装并配置Git
  • 具备版本控制基础知识
  • 可选：Commitizen、Commitlint、Standard-Version等工具
  • 可选：使用Husky配置Git钩子

Instrucciones

操作步骤

1. Usar el Formato Básico

1. 使用基础格式

La estructura de un commit sigue este patrón:
<tipo>[scope opcional]: <descripción>

[cuerpo opcional]

[footer(s) opcional(es)]
Ejemplo mínimo:
feat: añadir sistema de autenticación
Ejemplo completo:
feat(auth): implementar login con OAuth2

Añade soporte para autenticación mediante Google y GitHub.
Incluye manejo de tokens y refresh automático.

Closes #123
BREAKING CHANGE: El endpoint /login ahora requiere redirect_uri
提交信息遵循以下结构：
<类型>[可选作用域]: <描述>

[可选正文]

[可选页脚]
最简示例：
feat: 添加身份验证系统
完整示例：
feat(auth): 实现OAuth2登录功能

新增Google和GitHub账号的身份验证支持，包含令牌管理与自动刷新机制。

Closes #123
BREAKING CHANGE: 登录端点/login现在需要传递redirect_uri参数

2. Elegir el Tipo Correcto

2. 选择正确的提交类型

Los tipos más comunes son:
bash
undefined
最常用的提交类型如下：
bash
undefined

Nuevas funcionalidades

新增功能

git commit -m "feat: añadir búsqueda por filtros avanzados"
git commit -m "feat: 添加高级筛选搜索"

Corrección de errores

修复Bug

git commit -m "fix: corregir cálculo de impuestos en checkout"
git commit -m "fix: 修复结账流程中的税费计算错误"

Cambios en documentación

文档变更

git commit -m "docs: actualizar guía de instalación"
git commit -m "docs: 更新安装指南"

Cambios de formato (no afectan funcionalidad)

格式调整（不影响功能）

git commit -m "style: aplicar formato con Prettier"
git commit -m "style: 使用Prettier统一代码格式"

Refactorización de código

代码重构

git commit -m "refactor: simplificar lógica de validación"
git commit -m "refactor: 简化验证逻辑"

Mejoras de rendimiento

性能优化

git commit -m "perf: optimizar consulta de usuarios"
git commit -m "perf: 优化用户查询效率"

Añadir o actualizar tests

添加或更新测试

git commit -m "test: añadir tests para módulo de pagos"
git commit -m "test: 为支付模块添加测试用例"

Cambios en build o dependencias

构建系统或依赖变更

git commit -m "build: actualizar a Node 20"
git commit -m "build: 升级至Node 20"

Cambios en CI/CD

CI/CD流程变更

git commit -m "ci: añadir workflow de GitHub Actions"
git commit -m "ci: 添加GitHub Actions工作流"

Tareas de mantenimiento

维护任务

git commit -m "chore: actualizar dependencias"

Para una lista completa de tipos y cuándo usar cada uno, ver [references/tipos.md](references/tipos.md).
git commit -m "chore: 更新依赖包"

完整的提交类型及适用场景请参考[references/tipos.md](references/tipos.md)。

3. Especificar Scope (Ámbito)

3. 指定作用域（Scope）

El scope indica qué parte del proyecto se modificó:
bash
undefined
作用域用于标识修改涉及的项目部分：
bash
undefined

Por módulo/componente

按模块/组件划分

git commit -m "feat(parser): añadir soporte para JSON5" git commit -m "fix(navbar): corregir menu en móviles"
git commit -m "feat(parser): 添加JSON5格式支持" git commit -m "fix(navbar): 修复移动端菜单问题"

Por capa de aplicación

按应用层级划分

git commit -m "refactor(api): extraer lógica de negocio" git commit -m "test(service): añadir tests unitarios"
git commit -m "refactor(api): 抽离业务逻辑" git commit -m "test(service): 添加单元测试"

Por funcionalidad

按功能划分

git commit -m "feat(i18n): añadir traducciones al francés" git commit -m "fix(auth): resolver timeout en login"
git commit -m "feat(i18n): 添加法语翻译" git commit -m "fix(auth): 解决登录超时问题"

Múltiples scopes (separados por coma)

多个作用域（用逗号分隔）

git commit -m "fix(auth,api): sincronizar validación de tokens"
git commit -m "fix(auth,api): 同步令牌验证规则"

Sin scope (cuando afecta todo el proyecto)

无作用域（修改影响整个项目时）

git commit -m "chore: migrar a TypeScript 5"
undefined
git commit -m "chore: 迁移至TypeScript 5"
undefined

4. Escribir Descripciones Claras

4. 编写清晰的描述信息

La descripción debe ser concisa e imperativa:
bash
undefined
描述需简洁且使用祈使语气：
bash
undefined

✅ BIEN - Modo imperativo, claro

✅ 正确 - 祈使语气、清晰明确

git commit -m "feat: añadir validación de email" git commit -m "fix: prevenir race condition en cache" git commit -m "refactor: extraer utilidades de fecha"
git commit -m "feat: 添加邮箱验证" git commit -m "fix: 避免缓存中的竞态条件" git commit -m "refactor: 抽离日期工具函数"

❌ MAL - Tiempo pasado o poco descriptivo

❌ 错误 - 过去式或描述模糊

git commit -m "feat: añadido un feature" # Vago git commit -m "fix: arreglé el bug" # Tiempo pasado git commit -m "update" # Sin tipo ni contexto

**Reglas para la descripción:**

- Máximo 72 caracteres (idealmente 50)
- Minúscula después de los dos puntos
- Sin punto final
- Modo imperativo: "añadir" no "añadido", "corregir" no "corrigió"
git commit -m "feat: 新增了一个功能" # 模糊不清 git commit -m "fix: 修复了一个Bug" # 过去式 git commit -m "update" # 无类型及上下文

**描述信息规则：**

- 最长72个字符（理想长度为50个字符）
- 冒号后使用小写字母开头
- 结尾无句号
- 使用祈使语气：如“添加”而非“已添加”，“修复”而非“已修复”

5. Añadir Cuerpo para Contexto

5. 添加正文补充上下文

El cuerpo explica el qué y por qué, no el cómo:
bash
git commit -m "feat(cache): implementar estrategia LRU

Reemplaza el cache simple por un LRU para optimizar memoria.
Esto previene que el cache crezca indefinidamente en
aplicaciones long-running.

La implementación usa un Map con orden de inserción para
track el último acceso a cada entrada.
"
Mejores prácticas para el cuerpo:
  • Separar de la descripción con una línea en blanco
  • Máximo 72 caracteres por línea
  • Explicar motivación y contexto
  • Mencionar trade-offs o decisiones importantes
正文用于解释做了什么和为什么做，而非怎么做：
bash
git commit -m "feat(cache): 实现LRU缓存策略

将简单缓存替换为LRU缓存以优化内存使用，防止缓存在长期运行的应用中无限增长。

实现方案使用带插入顺序的Map来跟踪每个条目的最后访问时间。
"
正文最佳实践：
  • 与描述信息之间用空行分隔
  • 每行最长72个字符
  • 解释修改动机与上下文
  • 提及权衡方案或重要决策

6. Indicar Breaking Changes

6. 标记破坏性变更

Para cambios que rompen compatibilidad:
bash
undefined
对于破坏兼容性的变更：
bash
undefined

Opción 1: ! después del tipo/scope

方式1：在类型/作用域后添加!

git commit -m "feat(api)!: cambiar formato de respuesta JSON
BREAKING CHANGE: El campo 'user_id' ahora se llama 'userId'. Actualizar código cliente para usar la nueva nomenclatura."
git commit -m "feat(api)!: 修改JSON响应格式
BREAKING CHANGE: 用户ID字段'user_id'更名为'userId'，请更新客户端代码以使用新命名。"

Opción 2: BREAKING CHANGE en el footer

方式2：在页脚中添加BREAKING CHANGE

git commit -m "refactor: reorganizar estructura de exports
BREAKING CHANGE: Los módulos internos ya no son exportados. Usar solo los exports del index principal."
git commit -m "refactor: 重构导出结构
BREAKING CHANGE: 内部模块不再对外导出，请仅使用主入口的导出内容。"

Con multiple footers

多页脚示例

git commit -m "feat(auth)!: migrar a JWT
Reemplaza sesiones basadas en cookies por tokens JWT.
BREAKING CHANGE: Requiere actualizar auth middleware. Closes #456 Reviewed-by: @tech-lead "
undefined
git commit -m "feat(auth)!: 迁移至JWT
将基于Cookie的会话替换为JWT令牌。
BREAKING CHANGE: 需要更新身份验证中间件。 Closes #456 Reviewed-by: @tech-lead "
undefined

7. Usar Footers para Metadata

7. 使用页脚添加元数据

Los footers agregan información extra:
bash
undefined
页脚可补充额外信息：
bash
undefined

Referencias a issues

关联Issue

git commit -m "fix(parser): manejar strings vacíos
Closes #234 Fixes #567 See also: #890"
git commit -m "fix(parser): 处理空字符串
Closes #234 Fixes #567 See also: #890"

Revisores y co-autores

评审者与协作者

git commit -m "feat: añadir modo dark
Co-authored-by: Juan Pérez juan@example.com Reviewed-by: María García maria@example.com"
git commit -m "feat: 添加深色模式
Co-authored-by: Juan Pérez juan@example.com Reviewed-by: María García maria@example.com"

Información de despliegue

部署信息

git commit -m "chore: actualizar versión
Refs: #456 Deployed-to: production Release-notes: https://example.com/v2.0"
git commit -m "chore: 更新版本号
Refs: #456 Deployed-to: production Release-notes: https://example.com/v2.0"

Breaking change con contexto

带上下文的破坏性变更

git commit -m "refactor(api)!: cambiar estructura de endpoints
BREAKING CHANGE: Los endpoints ahora usan /api/v2 como base. Migration-guide: docs/migration-v2.md Deprecated: /api/v1 (soporte hasta 2026-06-01)"
undefined
git commit -m "refactor(api)!: 调整端点结构
BREAKING CHANGE: 端点现在以/api/v2为基础路径。 Migration-guide: docs/migration-v2.md Deprecated: /api/v1（支持至2026-06-01）"
undefined

Referencias a Tickets JIRA

JIRA工单关联

Para proyectos que usan JIRA, incluye el ticket en los footers:
bash
undefined
对于使用JIRA的项目，可在页脚中关联工单：
bash
undefined

Un solo ticket JIRA

单个JIRA工单

git commit -m "feat(checkout): añadir opción de pago con PayPal
Implementa integración completa con PayPal SDK. Incluye manejo de webhooks para confirmación.
JIRA: PROJ-1234"
git commit -m "feat(checkout): 添加PayPal支付选项
实现与PayPal SDK的完整集成，包含Webhook确认处理。
JIRA: PROJ-1234"

Múltiples tickets relacionados

多个关联工单

git commit -m "fix(api): corregir validación de tokens expirados
Corrige bugs relacionados con refresh de tokens y manejo de expiración en peticiones concurrentes.
JIRA: PROJ-456, PROJ-789 Fixes: PROJ-890"
git commit -m "fix(api): 修复过期令牌验证问题
修复与令牌刷新及并发请求过期处理相关的Bug。
JIRA: PROJ-456, PROJ-789 Fixes: PROJ-890"

Ticket en el subject (formato alternativo)

主题中包含工单（替代格式）

git commit -m "[PROJ-1234] feat(checkout): añadir pago con PayPal"
git commit -m "[PROJ-1234] feat(checkout): 添加PayPal支付"

Combinado con otros footers

与其他页脚结合

git commit -m "feat(reports)!: migrar a nueva API de reportes
BREAKING CHANGE: La API antigua quedará deprecada. Closes #123 JIRA: PROJ-567 Reviewed-by: @team-lead"

**Formatos comunes para JIRA:**

- **En footer (recomendado)**: `JIRA: PROJ-1234` o `Refs: PROJ-1234`
- **En subject**: `[PROJ-1234] tipo(scope): descripción`
- **Múltiples tickets**: `JIRA: PROJ-123, PROJ-456` o en líneas separadas

**Mejores prácticas JIRA:**

- Un solo ticket principal por commit (preferible)
- Si hay múltiples, listar el principal primero
- Usar formato consistente en todo el equipo
- Configurar integración JIRA-Git para enlace automático
git commit -m "feat(reports)!: 迁移至新报表API
BREAKING CHANGE: 旧API将被弃用。 Closes #123 JIRA: PROJ-567 Reviewed-by: @team-lead"

**常用JIRA格式：**

- **页脚中（推荐）**：`JIRA: PROJ-1234` 或 `Refs: PROJ-1234`
- **主题中**：`[PROJ-1234] 类型(作用域): 描述`
- **多个工单**：`JIRA: PROJ-123, PROJ-456` 或分行列出

**JIRA最佳实践：**

- 每个提交关联一个主要工单（优先选择）
- 多个工单时，优先列出主要工单
- 团队内使用统一格式
- 配置JIRA-Git集成以自动建立链接

8. Aplicar Mejores Prácticas

8. 遵循最佳实践

  1. Un commit = un cambio lógico - No mezclar refactor con feature
  2. Commits atómicos - Cada commit debe dejar el código funcional
  3. Descripción descriptiva - Que se entienda sin ver el diff
  4. Usar scope consistentemente - Definir scopes en el equipo
  5. Breaking changes explícitos - Siempre documentar incompatibilidades
  6. Tests antes de commit - Verificar que todo funciona
Para ejemplos detallados de commits buenos y malos, ver references/buenas-practicas.md.
  1. 一个提交 = 一个逻辑变更 - 不要同时包含重构与新功能
  2. 原子提交 - 每个提交应保证代码可正常运行
  3. 描述性信息 - 无需查看代码差异即可理解变更内容
  4. 一致使用作用域 - 团队内定义统一的作用域规则
  5. 明确标记破坏性变更 - 始终记录兼容性变更
  6. 提交前测试 - 验证所有功能正常运行
提交信息的正反示例详情请参考references/buenas-practicas.md。

Tipos de Commit

提交类型

Para referencia rápida:
TipoUsoAfecta semver
feat
Nueva funcionalidadMINOR (0.X.0)
fix
Corrección de bugPATCH (0.0.X)
docs
Solo documentación-
style
Formato, espacios (no lógica)-
refactor
Cambio de código sin bug ni feature-
perf
Mejora de rendimientoPATCH (0.0.X)
test
Añadir o corregir tests-
build
Sistema build, dependencias-
ci
Scripts CI/CD-
chore
Tareas mantenimiento-
revert
Revertir commit anteriorVaría
! o BREAKING CHANGECambio incompatibleMAJOR (X.0.0)
Ver references/tipos.md para descripción completa.
快速参考：
类型用途影响语义化版本
feat
新增功能MINOR (0.X.0)
fix
修复BugPATCH (0.0.X)
docs
仅修改文档-
style
格式调整（不影响逻辑）-
refactor
代码重构（无Bug修复或功能新增）-
perf
性能优化PATCH (0.0.X)
test
添加或修改测试用例-
build
构建系统或依赖变更-
ci
CI/CD脚本变更-
chore
维护任务-
revert
回滚之前的提交视情况而定
! 或 BREAKING CHANGE破坏性变更MAJOR (X.0.0)
完整的提交类型说明请参考references/tipos.md。

Salida Esperada

预期收益

Al usar Conventional Commits obtienes:
  • Historial legible - Commits estructurados fáciles de buscar y filtrar
  • Changelogs automáticos - Herramientas como standard-version generan CHANGELOG.md
  • Versionado semántico - Determina automáticamente la próxima versión
  • Integración CI/CD - Hooks que validan formato antes de push
  • Búsqueda eficiente - 
    git log --grep="^feat"
    encuentra todas las features
  • Releases automatizados - Semantic-release publica basándose en commits
使用Conventional Commits可获得：
  • 易读的历史记录 - 结构化的提交信息便于搜索与筛选
  • 自动化变更日志 - 使用Standard-Version等工具自动生成CHANGELOG.md
  • 语义化版本控制 - 自动确定下一个版本号
  • CI/CD集成 - 推送前验证提交格式的钩子
  • 高效搜索 - 
    git log --grep="^feat"
    可筛选所有新增功能
  • 自动化发布 - Semantic Release基于提交信息自动发布版本

Ejemplos

示例

Ejemplo: Feature con scope y breaking change
Situación: Modificas la API de autenticación para usar headers en lugar de cookies.
bash
git commit -m "feat(auth)!: migrar autenticación a headers

Cambiamos de cookies a Authorization header con Bearer tokens
para mejorar compatibilidad con aplicaciones móviles y SPAs.

Beneficios:
- Menor complejidad en CORS
- Mejor soporte para apps nativas
- Tokens con expiración explícita

BREAKING CHANGE: Los clientes deben enviar tokens en el header
Authorization en lugar de cookies. Ver guía de migración en
docs/auth-migration.md

Closes #789
"
Ejemplo: Fix con contexto y referencias
Situación: Corriges un race condition que causaba datos duplicados.
bash
git commit -m "fix(database): prevenir inserción duplicada en race condition

Añade lock optimista usando version field para prevenir que
requests concurrentes creen registros duplicados.

El bug ocurría cuando múltiples workers procesaban el mismo
evento simultáneamente. Ahora el segundo insert falla y se
reintenta leyendo el registro existente.

Fixes #456
Related: #234, #345
"
Ejemplo: Chore simple sin cuerpo
Situación: Actualizas las dependencias del proyecto.
bash
git commit -m "chore(deps): actualizar dependencias a últimas versiones"
Ejemplo: Docs con múltiples scopes
Situación: Actualizas README y añades ejemplos en varios componentes.
bash
git commit -m "docs(readme,examples): actualizar guía de inicio rápido

Añade sección de troubleshooting común y ejemplos actualizados
para la v2.0 de la API.
"
示例：带作用域与破坏性变更的功能提交
场景：修改身份验证API，使用请求头替代Cookie。
bash
git commit -m "feat(auth)!: 迁移至基于请求头的身份验证

将Cookie验证改为使用带Bearer令牌的Authorization请求头，以提升与移动端应用及SPA的兼容性。

优势：
- 降低CORS复杂度
- 更好的原生应用支持
- 令牌过期时间明确

BREAKING CHANGE: 客户端需在Authorization请求头中传递令牌，而非使用Cookie。请参考docs/auth-migration.md中的迁移指南。

Closes #789
"
示例：带上下文与关联引用的Bug修复
场景：修复导致数据重复的竞态条件。
bash
git commit -m "fix(database): 防止竞态条件下的重复插入

使用版本字段添加乐观锁，防止并发请求创建重复记录。

该Bug发生在多个Worker同时处理同一事件时。现在第二个插入请求会失败，并重新读取已存在的记录。

Fixes #456
Related: #234, #345
"
示例：无正文的简单维护提交
场景：更新项目依赖包。
bash
git commit -m "chore(deps): 更新至最新版本依赖包"
示例：多作用域的文档更新
场景：更新README并添加多个组件的示例。
bash
git commit -m "docs(readme,examples): 更新快速入门指南

新增常见问题排查章节及API v2.0的更新示例。
"

Recursos

参考资源