Element Plus 提交信息规范实战指南Commit Message 格式、模板与自动化校验【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus导读本文基于 Element Plus 官方贡献文档《Commit Examples》整理而成系统讲解 Element Plus 开源项目对 Git 提交信息Commit Message的完整规范从 Why为什么需要规范提交信息、Howsubject/body 的具体书写规则与模板到 Who通过 commitlint、husky、cz-git 实现提交前的自动校验与交互式辅助。读者读完本文后将掌握 Element Plus 仓库实际在用的提交信息格式type: [messages]能够写出符合校验规则、可自动生成 changelog 的高质量提交信息并理解仓库内 commitlint.config.mjs、.husky/commit-msg 等配置文件背后的约束逻辑。为什么需要规范 Commit MessageElement Plus 在 docs/en-US/guide/commit-examples.md 中专门用一章来讲解提交信息规范核心出发点有两点让维护者与协作者理解改动意图一个清晰的提交信息能让任何人在回顾历史时快速明白该提交做了什么、为什么做自动化生成变更日志changelog规范化的提交信息是自动化工具解析的基础可以直接驱动 changelog 的生成。第二点在该仓库中有直接的落地证据CHANGELOG.en-US.md 全文由规范提交信息汇总生成其中的条目格式如- Components [date-picker] add quarter picker (#24490 by LostElkByte)、- Components [form-item] add alert role to validation message (#24680 by lazerg)与本文介绍的提交格式一一对应——type决定分节Features / Bug fixes / Refactors 等scope标识组件或模块subject描述动作。该规范基于社区广泛采用的 Conventional Commits约定式提交约定Element Plus 在 package.json 中通过commitlint/config-conventional继承了这套规则并在此基础上扩展了项目自定义的type与scope取值。Commit Message 书写规则原文档给出了一套完整的书写规则以下逐条列出并结合仓库配置进行解读# (If applied, this commit will...) subject (Max 72 characters) # |---- Using a Maximum Of 72 Characters ----| # Explain why this change is being made # |---- Try To Limit Each Line to a Maximum Of 72 Characters ----| # Provide links or keys to any relevant tickets, articles or other resources # Use issues and merge requests full URLs instead of short references, # as they are displayed as plain text outside of GitLab # --- COMMIT END --- # -------------------- # Remember to # Capitalize the subject line # Use the imperative mood in the subject line # Do not end the subject line with a period # Subject must contain at least 3 words # Separate subject from body with a blank line # Commits that change 30 or more lines across at least 3 files should # describe these changes in the commit body # Do not use Emojis # Use the body to explain what and why vs. how # Can use multiple lines with - for bullet points in body这些规则的要点可归纳为维度规则要求仓库中的落地配置subject 长度不超过 72 个字符header-max-length: [2, always, 72]硬性错误正文每行长度尽量不超过 72 个字符—首字母大写Capitalize the subject linesubject-case排除 sentence/start/pascal/upper 之外的写法警告级语气使用祈使语气imperative mood如 add、fix 而非 added、fixing—句末标点subject 不以句号结尾subject-full-stop: [2, never, .]硬性错误subject 词数至少包含 3 个单词—subject 与 body用空行分隔body-leading-blank: [1, always]警告级正文必要性改动 30 行以上且涉及至少 3 个文件时必须在 body 中描述改动—Emoji禁止使用 Emoji—正文内容解释 what 和 why而不是 how支持以-开头多行罗列—说明上表规则中硬性错误表示违规会导致 commit 被commitlint直接拒绝规则优先级 2警告级优先级 1表示校验不通过但允许提交仅给出提示。在仓库的commitlint规则中还可以看到两条与上述规范配套的约束type-empty: [2, never]、subject-empty: [2, never]type与subject均不可为空scope-case: [2, always, lower-case]scope必须为小写footer-leading-blank: [1, always]footer如关联的 issue/PR 引用前需留空行。Commit Message 标准模板原文档给出了 Element Plus 官方推荐的标准模板feat(components): [button] I did something with button Blank between subject and body is expected.(period is expected) Describes your change in one line or multi-line. Capitalize your first letter when starting a new line Please do not exceeds 72 characters per line, because that would be harder to comprehend. - You can also add bullet list symbol for better layout结合该模板一个规范的提交信息由三部分构成subject首行格式为type: [messages]例如feat(components): [button] I did something with button。注意这里的[messages]是 Element Plus 的一种约定写法——用方括号标明改动针对的具体组件如[button]、[date-picker]这与 changelog 中Components [date-picker] ...的条目风格一致body正文与 subject 之间空一行说明改动的背景与原因可多行、可换行大写开头、每行不超过 72 字符可用-列表footer页脚可选用于关联 issue、PR 等资源引用需在前面留空行。原文档特别提醒应使用 issue 或 merge request 的完整 URL 而非短引用因为短引用在 GitLab 之外的纯文本环境中无法自动解析。type 与 scope 的允许取值subject 头部type:中type和scope都不是随意填写的。原文档指向了仓库的commitlint配置文件当前仓库中该文件为 commitlint.config.mjs其中明确枚举了全部合法取值。type提交类型枚举根据 commitlint.config.mjs 中的type-enum规则Element Plus 允许以下 13 种typetype-enum: [ 2, always, [ build, chore, ci, docs, feat, fix, perf, refactor, revert, release, style, test, improvement, ], ],各类型的语义与 Conventional Commits 约定一致type适用场景feat新增功能featurefix修复 bugdocs仅文档变更style不影响代码含义的格式调整空白、分号等注意区别于 CSS 样式变更refactor重构不新增功能也不修 bugperf性能优化test新增或修改测试build构建系统或外部依赖变更ciCI 配置与脚本变更chore日常维护性改动杂务revert回滚某次提交release版本发布相关提交improvement对既有功能的改进超出上述枚举的type会被 commitlint 以错误级别优先级 2拒绝因此写提交信息前应优先从这张表中选择最贴切的类型。scope作用域枚举scope用于标明改动的影响范围。该配置通过getPackages动态扫描仓库目录生成并结合一组手工维护的固定值const scopes [ ...getPackages(packages), // packages/ 下的全部一级目录 ...getPackages(internal), // internal/ 下的全部一级目录 docs, play, project, core, style, ci, dev, deploy, other, typography, color, border, var, ssr, types, deps, ]其中getPackages通过globSync(*, { cwd: packagePath, onlyDirectories: true })扫描目录名。对照当前仓库结构packages/下包含components、constants、directives、element-plus、hooks、locale、test-utils、theme-chalk、utils等一级目录这些目录名都会自动成为合法的scope而docs文档站、playPlayground、ssrSSR 测试、ciCI 相关等则对应仓库中相应的目录或工作区。由于scope同时受scope-case: [2, always, lower-case]约束命名时应使用小写 kebab-case连字符小写如date-picker、theme-chalk。智能默认 scope/subject值得一提的是该配置文件还实现了一个实用的自动化细节通过git status --porcelain检测当前暂存区中修改的packages/与packages/components/路径自动推导出默认的scope如用户改了packages/components/button相关文件则默认 scope 即为components和默认 subject 前缀如[button]并在prompt配置中作为cz-git交互式提交流程的默认值进一步降低书写成本。自动化commitlint husky cz-git规范的价值在于被强制执行。Element Plus 通过 Husky Git Hooks 在提交前自动运行校验.husky/pre-commit 执行pnpm exec lint-staged仅对暂存区中的.vue/.js/.ts/.md/.json/.scss等文件先跑eslint --fix再prettier --write对应 package.json 中的lint-staged配置保证提交的代码已格式化.husky/commit-msg 执行pnpm exec commitlint --config commitlint.config.mjs --edit ${1}在 commit-msg 钩子阶段对本次提交信息进行完整校验——也就是本文前面介绍的所有规则会在此时生效不合规的提交信息会被直接拦截。此外仓库还集成了交互式提交工具cz-gitpackage.json 中提供cz: czg脚本开发者可运行pnpm cz启动引导式提交Select type → 输入 scope/subject/body/footer仓库根配置的config.commitizen.path指向cz-git其prompt选项会复用commitlint.config.mjs中定义的类型枚举、scope 列表以及上面提到的智能默认 scope/subject。本地手工校验也完全可行开发者可以直接运行pnpm run lint:commit对应commitlint命令对自己最近一次提交信息做校验或在提交前手动运行pnpm exec commitlint --from HEAD~1 --to HEAD一类的命令检查历史提交是否符合规范。项目中的典型用法结合上述规范在 Element Plus 仓库中一个典型的功能提交可以这样写feat(components): [button] add loading duration option Adds a configurable loading duration to the button component, allowing users to control the minimum display time of the loading state. - Added new prop loadingDuration - Updated corresponding tests and docs其中feat表示新功能components是合法的 scopepackages/components目录名[button]进一步点明具体组件正文说明了 why控制 loading 状态最短展示时长并用-列表补充关键改动点。若改动涉及 30 行以上、3 个以上文件如一次跨组件的重构或文档更新则必须按要求在 body 中描述改动内容单文件的小改动可以只写 subject。另外仓库提供pnpm gen name脚本见 scripts/gc.sh用于一键生成新组件脚手架其生成的目录结构src/、style/、__tests__/等也遵循一次提交对应一个主题的组织方式配合规范提交信息可让每次提交的意图与改动范围高度对齐。小结Element Plus 的提交信息规范可概括为三句话格式统一type: [messages]subject 不超过 72 字符、祈使语气、首字母大写、不以句号结尾body 与 subject 空行分隔取值受控type限定 13 种枚举值scope限定为packages/internal目录名与若干固定值全部定义在 commitlint.config.mjs 中超出即被拒绝自动执行借助.husky钩子commit-msg、pre-commit在提交瞬间完成校验与格式化配合pnpm cz交互式引导让每个贡献者都能轻松产出规范的提交信息进而支撑 CHANGELOG.en-US.md 的自动化生成与清晰的提交历史。对于希望在 Element Plus 提交 PR 的开发者或想为自己的 Vue 项目引入规范提交体系的团队均可直接参照本文的规则、模板与配置文件进行落地。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Element Plus 提交信息规范实战指南：Commit Message 格式、模板与自动化校验
Element Plus 提交信息规范实战指南Commit Message 格式、模板与自动化校验【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus导读本文基于 Element Plus 官方贡献文档《Commit Examples》整理而成系统讲解 Element Plus 开源项目对 Git 提交信息Commit Message的完整规范从 Why为什么需要规范提交信息、Howsubject/body 的具体书写规则与模板到 Who通过 commitlint、husky、cz-git 实现提交前的自动校验与交互式辅助。读者读完本文后将掌握 Element Plus 仓库实际在用的提交信息格式type: [messages]能够写出符合校验规则、可自动生成 changelog 的高质量提交信息并理解仓库内 commitlint.config.mjs、.husky/commit-msg 等配置文件背后的约束逻辑。为什么需要规范 Commit MessageElement Plus 在 docs/en-US/guide/commit-examples.md 中专门用一章来讲解提交信息规范核心出发点有两点让维护者与协作者理解改动意图一个清晰的提交信息能让任何人在回顾历史时快速明白该提交做了什么、为什么做自动化生成变更日志changelog规范化的提交信息是自动化工具解析的基础可以直接驱动 changelog 的生成。第二点在该仓库中有直接的落地证据CHANGELOG.en-US.md 全文由规范提交信息汇总生成其中的条目格式如- Components [date-picker] add quarter picker (#24490 by LostElkByte)、- Components [form-item] add alert role to validation message (#24680 by lazerg)与本文介绍的提交格式一一对应——type决定分节Features / Bug fixes / Refactors 等scope标识组件或模块subject描述动作。该规范基于社区广泛采用的 Conventional Commits约定式提交约定Element Plus 在 package.json 中通过commitlint/config-conventional继承了这套规则并在此基础上扩展了项目自定义的type与scope取值。Commit Message 书写规则原文档给出了一套完整的书写规则以下逐条列出并结合仓库配置进行解读# (If applied, this commit will...) subject (Max 72 characters) # |---- Using a Maximum Of 72 Characters ----| # Explain why this change is being made # |---- Try To Limit Each Line to a Maximum Of 72 Characters ----| # Provide links or keys to any relevant tickets, articles or other resources # Use issues and merge requests full URLs instead of short references, # as they are displayed as plain text outside of GitLab # --- COMMIT END --- # -------------------- # Remember to # Capitalize the subject line # Use the imperative mood in the subject line # Do not end the subject line with a period # Subject must contain at least 3 words # Separate subject from body with a blank line # Commits that change 30 or more lines across at least 3 files should # describe these changes in the commit body # Do not use Emojis # Use the body to explain what and why vs. how # Can use multiple lines with - for bullet points in body这些规则的要点可归纳为维度规则要求仓库中的落地配置subject 长度不超过 72 个字符header-max-length: [2, always, 72]硬性错误正文每行长度尽量不超过 72 个字符—首字母大写Capitalize the subject linesubject-case排除 sentence/start/pascal/upper 之外的写法警告级语气使用祈使语气imperative mood如 add、fix 而非 added、fixing—句末标点subject 不以句号结尾subject-full-stop: [2, never, .]硬性错误subject 词数至少包含 3 个单词—subject 与 body用空行分隔body-leading-blank: [1, always]警告级正文必要性改动 30 行以上且涉及至少 3 个文件时必须在 body 中描述改动—Emoji禁止使用 Emoji—正文内容解释 what 和 why而不是 how支持以-开头多行罗列—说明上表规则中硬性错误表示违规会导致 commit 被commitlint直接拒绝规则优先级 2警告级优先级 1表示校验不通过但允许提交仅给出提示。在仓库的commitlint规则中还可以看到两条与上述规范配套的约束type-empty: [2, never]、subject-empty: [2, never]type与subject均不可为空scope-case: [2, always, lower-case]scope必须为小写footer-leading-blank: [1, always]footer如关联的 issue/PR 引用前需留空行。Commit Message 标准模板原文档给出了 Element Plus 官方推荐的标准模板feat(components): [button] I did something with button Blank between subject and body is expected.(period is expected) Describes your change in one line or multi-line. Capitalize your first letter when starting a new line Please do not exceeds 72 characters per line, because that would be harder to comprehend. - You can also add bullet list symbol for better layout结合该模板一个规范的提交信息由三部分构成subject首行格式为type: [messages]例如feat(components): [button] I did something with button。注意这里的[messages]是 Element Plus 的一种约定写法——用方括号标明改动针对的具体组件如[button]、[date-picker]这与 changelog 中Components [date-picker] ...的条目风格一致body正文与 subject 之间空一行说明改动的背景与原因可多行、可换行大写开头、每行不超过 72 字符可用-列表footer页脚可选用于关联 issue、PR 等资源引用需在前面留空行。原文档特别提醒应使用 issue 或 merge request 的完整 URL 而非短引用因为短引用在 GitLab 之外的纯文本环境中无法自动解析。type 与 scope 的允许取值subject 头部type:中type和scope都不是随意填写的。原文档指向了仓库的commitlint配置文件当前仓库中该文件为 commitlint.config.mjs其中明确枚举了全部合法取值。type提交类型枚举根据 commitlint.config.mjs 中的type-enum规则Element Plus 允许以下 13 种typetype-enum: [ 2, always, [ build, chore, ci, docs, feat, fix, perf, refactor, revert, release, style, test, improvement, ], ],各类型的语义与 Conventional Commits 约定一致type适用场景feat新增功能featurefix修复 bugdocs仅文档变更style不影响代码含义的格式调整空白、分号等注意区别于 CSS 样式变更refactor重构不新增功能也不修 bugperf性能优化test新增或修改测试build构建系统或外部依赖变更ciCI 配置与脚本变更chore日常维护性改动杂务revert回滚某次提交release版本发布相关提交improvement对既有功能的改进超出上述枚举的type会被 commitlint 以错误级别优先级 2拒绝因此写提交信息前应优先从这张表中选择最贴切的类型。scope作用域枚举scope用于标明改动的影响范围。该配置通过getPackages动态扫描仓库目录生成并结合一组手工维护的固定值const scopes [ ...getPackages(packages), // packages/ 下的全部一级目录 ...getPackages(internal), // internal/ 下的全部一级目录 docs, play, project, core, style, ci, dev, deploy, other, typography, color, border, var, ssr, types, deps, ]其中getPackages通过globSync(*, { cwd: packagePath, onlyDirectories: true })扫描目录名。对照当前仓库结构packages/下包含components、constants、directives、element-plus、hooks、locale、test-utils、theme-chalk、utils等一级目录这些目录名都会自动成为合法的scope而docs文档站、playPlayground、ssrSSR 测试、ciCI 相关等则对应仓库中相应的目录或工作区。由于scope同时受scope-case: [2, always, lower-case]约束命名时应使用小写 kebab-case连字符小写如date-picker、theme-chalk。智能默认 scope/subject值得一提的是该配置文件还实现了一个实用的自动化细节通过git status --porcelain检测当前暂存区中修改的packages/与packages/components/路径自动推导出默认的scope如用户改了packages/components/button相关文件则默认 scope 即为components和默认 subject 前缀如[button]并在prompt配置中作为cz-git交互式提交流程的默认值进一步降低书写成本。自动化commitlint husky cz-git规范的价值在于被强制执行。Element Plus 通过 Husky Git Hooks 在提交前自动运行校验.husky/pre-commit 执行pnpm exec lint-staged仅对暂存区中的.vue/.js/.ts/.md/.json/.scss等文件先跑eslint --fix再prettier --write对应 package.json 中的lint-staged配置保证提交的代码已格式化.husky/commit-msg 执行pnpm exec commitlint --config commitlint.config.mjs --edit ${1}在 commit-msg 钩子阶段对本次提交信息进行完整校验——也就是本文前面介绍的所有规则会在此时生效不合规的提交信息会被直接拦截。此外仓库还集成了交互式提交工具cz-gitpackage.json 中提供cz: czg脚本开发者可运行pnpm cz启动引导式提交Select type → 输入 scope/subject/body/footer仓库根配置的config.commitizen.path指向cz-git其prompt选项会复用commitlint.config.mjs中定义的类型枚举、scope 列表以及上面提到的智能默认 scope/subject。本地手工校验也完全可行开发者可以直接运行pnpm run lint:commit对应commitlint命令对自己最近一次提交信息做校验或在提交前手动运行pnpm exec commitlint --from HEAD~1 --to HEAD一类的命令检查历史提交是否符合规范。项目中的典型用法结合上述规范在 Element Plus 仓库中一个典型的功能提交可以这样写feat(components): [button] add loading duration option Adds a configurable loading duration to the button component, allowing users to control the minimum display time of the loading state. - Added new prop loadingDuration - Updated corresponding tests and docs其中feat表示新功能components是合法的 scopepackages/components目录名[button]进一步点明具体组件正文说明了 why控制 loading 状态最短展示时长并用-列表补充关键改动点。若改动涉及 30 行以上、3 个以上文件如一次跨组件的重构或文档更新则必须按要求在 body 中描述改动内容单文件的小改动可以只写 subject。另外仓库提供pnpm gen name脚本见 scripts/gc.sh用于一键生成新组件脚手架其生成的目录结构src/、style/、__tests__/等也遵循一次提交对应一个主题的组织方式配合规范提交信息可让每次提交的意图与改动范围高度对齐。小结Element Plus 的提交信息规范可概括为三句话格式统一type: [messages]subject 不超过 72 字符、祈使语气、首字母大写、不以句号结尾body 与 subject 空行分隔取值受控type限定 13 种枚举值scope限定为packages/internal目录名与若干固定值全部定义在 commitlint.config.mjs 中超出即被拒绝自动执行借助.husky钩子commit-msg、pre-commit在提交瞬间完成校验与格式化配合pnpm cz交互式引导让每个贡献者都能轻松产出规范的提交信息进而支撑 CHANGELOG.en-US.md 的自动化生成与清晰的提交历史。对于希望在 Element Plus 提交 PR 的开发者或想为自己的 Vue 项目引入规范提交体系的团队均可直接参照本文的规则、模板与配置文件进行落地。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考