Authelia 提交信息规范Commit Message Guidelines完全指南【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia导读本文基于 Authelia 官方开发指南 commit-message.md系统讲解 Authelia 项目强制要求的 Git 提交信息格式——从 header/body/footer 三段式结构、11 种提交类型、39 个可作用域到 Breaking Change、Revert 与签名规范并深入仓库源码与 commitlint 配置揭示这套规范如何在 CI 与本地钩子中被强制执行。读完本文你将能写出完全符合 Authelia 规范、可被 commitlint 校验通过的提交信息也能为任意 Go Web 多包仓库设计一套可自动生成、可校验的提交信息治理方案。为什么 Authelia 要严格约定提交信息Authelia 在开发指南开篇就点明了这套约定的两个核心动机简单导航 git 历史simple navigation through git history统一的 type/scope 前缀让开发者可以快速过滤出某类变更例如git log --grep^fix(oidc)即可定位 OIDC 模块的所有修复更易阅读 git 历史easier to read git history一致的句式祈使句、现在时与长度限制header 不超过 72 字符让历史记录像一份结构化的变更日志。从源码层面看这一动机有更直接的落点Authelia 通过自动生成 commitlint 配置与文档模板把“约定”固化为“可执行的规则”任何不合规的提交都会在提交阶段被拦截详见下文“仓库中的落地实现”。Commit Message 整体结构Authelia 的提交信息采用经典三段式结构与 AngularJS Git Commit Message Format 一脉相承文档末尾明确注明了这一来源header BLANK LINE body BLANK LINE footer各部分约束如下部分是否必填约束要点header必填必须符合 Header 格式长度不超过 72 字符body除docs类型外必填存在时至少 20 个字符必须符合 Body 格式footer可选用于记录破坏性变更、关联 issue/PR格式见 Footer 格式注意header 与 body 之间、body 与 footer 之间都必须以空行分隔否则会被 commitlint 判为格式错误。Commit Message HeaderHeader 是提交信息的门面其完整格式为type(scope): summary │ │ │ │ │ └─⫸ Summary in present tense. Not capitalized. No period at the end. │ │ │ └─⫸ Commit Scope: api|autheliabot|authentication|authorization|buildkite|bundler|clock| │ cmd|codecov|commands|configuration|deps|docker|duo|expression|go| │ golangci-lint|handlers|lefthook|logging|metrics|middlewares|mocks| │ model|notification|npm|ntp|oidc|random|regulation|renovate|reviewdog| │ server|service|session|storage|suites|templates|totp|utils|web| │ webauthn │ └─⫸ Commit Type: build|ci|docs|feat|fix|i18n|perf|refactor|release|revert|test其中type与summary为必填项(scope)为可选项。若省略 scope形如fix: correct typo若使用 scope则必须从官方允许的枚举值中选择type与scope之间不加空格冒号后跟一个空格再写 summary。允许的 Commit TypeType含义示例 Scopebuild影响构建系统或外部依赖的变更bundler, deps, docker, go, npmci对 CI 配置文件和脚本的变更autheliabot, buildkite, codecov, lefthook, golangci-lint, renovate, reviewdogdocs仅文档变更—feat新功能—fix缺陷修复—i18n更新翻译或国际化设置—perf提升性能的代码变更—refactor既非修复 bug 也非新增功能的代码重构—release发布 Authelia 新版本—test补充缺失的测试或修正现有测试—这 11 个 type 在仓库中并非手写维护而是定义在生成器源码中。cmd_commit_msg.go 里用NameDescriptionTmpl结构体逐一登记了这些 type 及其对应的示例 scope例如ci绑定了autheliabot、buildkite、codecov、lefthook、golangci-lint、renovate、reviewdog等 CI 相关 scope。而revert则作为额外 type 追加在列表尾部见 cmd_commit_msg.go 的commitTypesExtra这也解释了为什么上文类型表里没有把它和常规 type 并列——它专门用于回滚提交格式另有要求。允许的 Commit ScopeScope 原则上应使用受影响包package的名字以“阅读由提交信息生成的变更日志的人”的视角来命名。标准 scope 清单如下authenticationauthorizationclockcommandsconfigurationduoexpressionhandlersloggingmetricsmiddlewaresmocksmodelnotificationntpoidcrandomregulationserverservicesessionstoragesuitestemplatestotputilswebauthn这些 scope 并非拍脑袋写死的而是由生成器扫描仓库目录动态发现的getGoPackages函数递归遍历cmd/与internal/目录凡是包含.go文件的子目录都会被收录为包名 scope见 cmd_commit_msg.go。你可以对照仓库实际结构验证——例如 internal/oidc、internal/storage、internal/configuration 等目录与 scope 清单一一对应。在“使用包名”这一总原则之外存在少量例外 scopeapi用于修改 openapi 规范即 api/openapi.yml的变更cmd用于修改authelia|authelia-gen|authelia-scripts|authelia-suites这些顶层二进制的变更在生成模板中该描述会动态填入实际发现的命令名见 cmd_commit_msg.goweb用于修改基于 React 的前端即 web/src的变更none/空字符串即省略 scope适用于跨多个包完成的test、refactor变更例如test: add missing unit tests也适用于与具体包无关的文档变更例如docs: fix typo in tutorial。Summary 写作规则Summary 是对变更的精炼描述必须遵守三条硬规则使用祈使句、现在时用 change不用 changed 或 changes首字母不要大写结尾不加句号.。配合 header 总长 72 字符的限制这要求开发者把变更要点压缩在一条简洁的短语中。Commit Message BodyBody 的句式要求与 Summary 一致使用祈使句、现在时例如 fix 而非 fixed 或 fixes。Body 的核心使命是解释变更的动机why。官方指南明确建议说明你为什么要做这个变更并可对比变更前的行为与变更后的行为以呈现变更带来的影响。结合 commit-message.md 的示例可以看出Authelia 期望的 body 是一段能独立讲清问题的叙述先描述缺陷出现的场景再解释根因最后说明修复方案。同时注意 commitlint 规则body-min-length要求 body至少 20 个字符而body-max-line-length被放宽为无限详见下文落地实现因此长说明文字不会被行宽截断。Commit Message FooterFooter 用于承载两类信息破坏性变更Breaking Changes关联的 GitHub issues 与其他 PR本提交关闭或相关的 issue。标准 footer 模板如下BREAKING CHANGE: breaking change summary BLANK LINE breaking change description migration instructions BLANK LINE BLANK LINE Fixes #issue number Signed-off-by: AUTHORBreaking Change 段落必须以短语BREAKING CHANGE:开头后跟一句破坏性变更摘要接着空一行再写包含迁移指引的详细描述。这种结构便于工具自动识别破坏性变更并生成迁移说明也有助于下游用户评估升级风险。Revert Commits回滚提交回滚提交有专门的格式要求header 必须以revert:开头后接被回滚提交的 headerbody 必须包含被回滚提交的 SHA格式为This reverts commit SHA对回滚原因的清晰说明。由于revert被单独列为额外 typecmd_commit_msg.go它不占用常规 11 种 type 的语义空间回滚操作在 git 历史中因此具有很高的辨识度。Commit Message 完整示例官方文档给出了一个完整的合规示例对应fix(logging)的典型提交fix(logging): disable colored logging outputs when file is specified In some scenarios if a user has a log_file_path specified and a TTY seems to be detected this causes terminal coloring outputs to be written to the file. This in turn will cause issues when attempting to utilize the log with the provided fail2ban regexes. We now override any TTY detection/logging treatments and disable coloring/removal of the timestamp when a user is utilizing the text based logger to a file. Fixes #1480. Signed-off-by: John Smith jsmithorg.com逐段拆解这个示例可以直观看到全部规范的组合运用headerfix(logging)满足“type(scope)”格式summary 为祈使句、小写、无句号整体长度远低于 72 字符body第一段描述问题场景指定log_file_path且检测到 TTY 时终端着色输出被写入文件第二段说明后果破坏配套 fail2ban 正则匹配第三段给出修复行为完整覆盖了 why 前后行为对比且远超 20 字符下限footerFixes #1480.关联 issueSigned-off-by声明提交者符合 Linux 内核社区通用的开发者认证惯例。仓库中的落地实现规范如何被强制执行Authelia 的这套规范不是停留在文档层面的“倡议”而是被固化为工具链规则。核心证据有三处1. commitlint 规则由生成器自动产出仓库根目录的 web/commitlint.config.mjs 与生成模板 dot_commitlintrc.cjs.tmpl 完全一致其规则与本文档逐条对应export default { defaultIgnores: true, extends: [commitlint/config-conventional], helpUrl: https://www.authelia.com/contributing/guidelines/commit-message/, rules: { body-max-line-length: [2, always, Infinity], body-min-length: [2, always, 20], header-case: [2, always, lower-case], header-max-length: [2, always, 72], scope-enum: [2, always, [/* 动态生成的 scope 列表 */]], type-enum: [2, always, [build, ci, docs, feat, fix, i18n, perf, refactor, release, revert, test]], }, };可以看到header-max-length72 字符、body-min-length20 字符、scope-enum枚举校验、type-enum11 种 type revert、header-case强制小写正是本文档规则的机器可读版本。而body-max-line-length被设为Infinity意味着 body 行宽不受 72 字符限制允许撰写长句说明上文示例中 body 里的长句即为佐证。2. scope/type 清单随代码结构自动同步commitLintRunEcmd_commit_msg.go的执行流程体现了“单一事实来源”的设计扫描cmd/与internal/目录动态发现 Go 包名作为 scope合并api、cmd、web三个例外 scope 及各 type 绑定的示例 scope对 scope 与 type 列表排序后同时生成commitlint 配置文件与本文档.md指南两个产物。这意味着当仓库新增一个内部包如新增internal/foo时只要重新运行生成器scope-enum规则和本文档的 scope 清单就会同步更新杜绝了“文档写了但 lint 不认”的漂移问题。文档头部Code generated by go generate. DO NOT EDIT.的注释见 dot_commitlintrc.cjs.tmpl也印证了这一点。3. 本地钩子与 CI 双重把关仓库通过 .lefthook.yml 配置 Lefthook 本地 git 钩子在pre-commit阶段并行执行 docs lint、eslint、golangci-lint、reuse 等项目级检查commit-msg 阶段的 commitlint 校验则由 CI 工作流.github/workflows与本地钩子共同完成。开发者在本地提交时即可获得即时反馈避免把不合规的提交推到远程后才被 CI 拒绝。实践建议快速自查清单在提交前可对照以下清单自查headertype(scope): summary总长 ≤ 72 字符summary 为祈使句、小写、无结尾句号type必须是build|ci|docs|feat|fix|i18n|perf|refactor|release|revert|test之一scope使用受影响的包名authentication、oidc、storage等或例外api/cmd/web跨包变更可省略body除docs外必填≥ 20 字符说明 why 并对比前后行为用祈使句现在时footer破坏性变更以BREAKING CHANGE:开头并附迁移说明关联 issue 用Fixes #numberrevert以revert:开头body 含This reverts commit SHA与原因说明签名按需保留Signed-off-by: AUTHOR。延伸阅读Pull Request 指南提交信息之外PR 标题、描述与审查流程的配套规范贡献指南总览Authelia 贡献流程的整体介绍生成器实现cmd_commit_msg.go 与模板 docs-contributing-development-commitmsg.md.tmplcommitlint 配置web/commitlint.config.mjs本地钩子配置.lefthook.yml。本文依据 Authelia 官方开发文档 commit-message.md 整理并对照仓库源码cmd_commit_msg.go、dot_commitlintrc.cjs.tmpl、web/commitlint.config.mjs与钩子配置.lefthook.yml核实文中所有约束与示例均以当前仓库实际内容为准。【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Authelia 提交信息规范Commit Message Guidelines完全指南【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia导读本文基于 Authelia 官方开发指南 commit-message.md系统讲解 Authelia 项目强制要求的 Git 提交信息格式——从 header/body/footer 三段式结构、11 种提交类型、39 个可作用域到 Breaking Change、Revert 与签名规范并深入仓库源码与 commitlint 配置揭示这套规范如何在 CI 与本地钩子中被强制执行。读完本文你将能写出完全符合 Authelia 规范、可被 commitlint 校验通过的提交信息也能为任意 Go Web 多包仓库设计一套可自动生成、可校验的提交信息治理方案。为什么 Authelia 要严格约定提交信息Authelia 在开发指南开篇就点明了这套约定的两个核心动机简单导航 git 历史simple navigation through git history统一的 type/scope 前缀让开发者可以快速过滤出某类变更例如git log --grep^fix(oidc)即可定位 OIDC 模块的所有修复更易阅读 git 历史easier to read git history一致的句式祈使句、现在时与长度限制header 不超过 72 字符让历史记录像一份结构化的变更日志。从源码层面看这一动机有更直接的落点Authelia 通过自动生成 commitlint 配置与文档模板把“约定”固化为“可执行的规则”任何不合规的提交都会在提交阶段被拦截详见下文“仓库中的落地实现”。Commit Message 整体结构Authelia 的提交信息采用经典三段式结构与 AngularJS Git Commit Message Format 一脉相承文档末尾明确注明了这一来源header BLANK LINE body BLANK LINE footer各部分约束如下部分是否必填约束要点header必填必须符合 Header 格式长度不超过 72 字符body除docs类型外必填存在时至少 20 个字符必须符合 Body 格式footer可选用于记录破坏性变更、关联 issue/PR格式见 Footer 格式注意header 与 body 之间、body 与 footer 之间都必须以空行分隔否则会被 commitlint 判为格式错误。Commit Message HeaderHeader 是提交信息的门面其完整格式为type(scope): summary │ │ │ │ │ └─⫸ Summary in present tense. Not capitalized. No period at the end. │ │ │ └─⫸ Commit Scope: api|autheliabot|authentication|authorization|buildkite|bundler|clock| │ cmd|codecov|commands|configuration|deps|docker|duo|expression|go| │ golangci-lint|handlers|lefthook|logging|metrics|middlewares|mocks| │ model|notification|npm|ntp|oidc|random|regulation|renovate|reviewdog| │ server|service|session|storage|suites|templates|totp|utils|web| │ webauthn │ └─⫸ Commit Type: build|ci|docs|feat|fix|i18n|perf|refactor|release|revert|test其中type与summary为必填项(scope)为可选项。若省略 scope形如fix: correct typo若使用 scope则必须从官方允许的枚举值中选择type与scope之间不加空格冒号后跟一个空格再写 summary。允许的 Commit TypeType含义示例 Scopebuild影响构建系统或外部依赖的变更bundler, deps, docker, go, npmci对 CI 配置文件和脚本的变更autheliabot, buildkite, codecov, lefthook, golangci-lint, renovate, reviewdogdocs仅文档变更—feat新功能—fix缺陷修复—i18n更新翻译或国际化设置—perf提升性能的代码变更—refactor既非修复 bug 也非新增功能的代码重构—release发布 Authelia 新版本—test补充缺失的测试或修正现有测试—这 11 个 type 在仓库中并非手写维护而是定义在生成器源码中。cmd_commit_msg.go 里用NameDescriptionTmpl结构体逐一登记了这些 type 及其对应的示例 scope例如ci绑定了autheliabot、buildkite、codecov、lefthook、golangci-lint、renovate、reviewdog等 CI 相关 scope。而revert则作为额外 type 追加在列表尾部见 cmd_commit_msg.go 的commitTypesExtra这也解释了为什么上文类型表里没有把它和常规 type 并列——它专门用于回滚提交格式另有要求。允许的 Commit ScopeScope 原则上应使用受影响包package的名字以“阅读由提交信息生成的变更日志的人”的视角来命名。标准 scope 清单如下authenticationauthorizationclockcommandsconfigurationduoexpressionhandlersloggingmetricsmiddlewaresmocksmodelnotificationntpoidcrandomregulationserverservicesessionstoragesuitestemplatestotputilswebauthn这些 scope 并非拍脑袋写死的而是由生成器扫描仓库目录动态发现的getGoPackages函数递归遍历cmd/与internal/目录凡是包含.go文件的子目录都会被收录为包名 scope见 cmd_commit_msg.go。你可以对照仓库实际结构验证——例如 internal/oidc、internal/storage、internal/configuration 等目录与 scope 清单一一对应。在“使用包名”这一总原则之外存在少量例外 scopeapi用于修改 openapi 规范即 api/openapi.yml的变更cmd用于修改authelia|authelia-gen|authelia-scripts|authelia-suites这些顶层二进制的变更在生成模板中该描述会动态填入实际发现的命令名见 cmd_commit_msg.goweb用于修改基于 React 的前端即 web/src的变更none/空字符串即省略 scope适用于跨多个包完成的test、refactor变更例如test: add missing unit tests也适用于与具体包无关的文档变更例如docs: fix typo in tutorial。Summary 写作规则Summary 是对变更的精炼描述必须遵守三条硬规则使用祈使句、现在时用 change不用 changed 或 changes首字母不要大写结尾不加句号.。配合 header 总长 72 字符的限制这要求开发者把变更要点压缩在一条简洁的短语中。Commit Message BodyBody 的句式要求与 Summary 一致使用祈使句、现在时例如 fix 而非 fixed 或 fixes。Body 的核心使命是解释变更的动机why。官方指南明确建议说明你为什么要做这个变更并可对比变更前的行为与变更后的行为以呈现变更带来的影响。结合 commit-message.md 的示例可以看出Authelia 期望的 body 是一段能独立讲清问题的叙述先描述缺陷出现的场景再解释根因最后说明修复方案。同时注意 commitlint 规则body-min-length要求 body至少 20 个字符而body-max-line-length被放宽为无限详见下文落地实现因此长说明文字不会被行宽截断。Commit Message FooterFooter 用于承载两类信息破坏性变更Breaking Changes关联的 GitHub issues 与其他 PR本提交关闭或相关的 issue。标准 footer 模板如下BREAKING CHANGE: breaking change summary BLANK LINE breaking change description migration instructions BLANK LINE BLANK LINE Fixes #issue number Signed-off-by: AUTHORBreaking Change 段落必须以短语BREAKING CHANGE:开头后跟一句破坏性变更摘要接着空一行再写包含迁移指引的详细描述。这种结构便于工具自动识别破坏性变更并生成迁移说明也有助于下游用户评估升级风险。Revert Commits回滚提交回滚提交有专门的格式要求header 必须以revert:开头后接被回滚提交的 headerbody 必须包含被回滚提交的 SHA格式为This reverts commit SHA对回滚原因的清晰说明。由于revert被单独列为额外 typecmd_commit_msg.go它不占用常规 11 种 type 的语义空间回滚操作在 git 历史中因此具有很高的辨识度。Commit Message 完整示例官方文档给出了一个完整的合规示例对应fix(logging)的典型提交fix(logging): disable colored logging outputs when file is specified In some scenarios if a user has a log_file_path specified and a TTY seems to be detected this causes terminal coloring outputs to be written to the file. This in turn will cause issues when attempting to utilize the log with the provided fail2ban regexes. We now override any TTY detection/logging treatments and disable coloring/removal of the timestamp when a user is utilizing the text based logger to a file. Fixes #1480. Signed-off-by: John Smith jsmithorg.com逐段拆解这个示例可以直观看到全部规范的组合运用headerfix(logging)满足“type(scope)”格式summary 为祈使句、小写、无句号整体长度远低于 72 字符body第一段描述问题场景指定log_file_path且检测到 TTY 时终端着色输出被写入文件第二段说明后果破坏配套 fail2ban 正则匹配第三段给出修复行为完整覆盖了 why 前后行为对比且远超 20 字符下限footerFixes #1480.关联 issueSigned-off-by声明提交者符合 Linux 内核社区通用的开发者认证惯例。仓库中的落地实现规范如何被强制执行Authelia 的这套规范不是停留在文档层面的“倡议”而是被固化为工具链规则。核心证据有三处1. commitlint 规则由生成器自动产出仓库根目录的 web/commitlint.config.mjs 与生成模板 dot_commitlintrc.cjs.tmpl 完全一致其规则与本文档逐条对应export default { defaultIgnores: true, extends: [commitlint/config-conventional], helpUrl: https://www.authelia.com/contributing/guidelines/commit-message/, rules: { body-max-line-length: [2, always, Infinity], body-min-length: [2, always, 20], header-case: [2, always, lower-case], header-max-length: [2, always, 72], scope-enum: [2, always, [/* 动态生成的 scope 列表 */]], type-enum: [2, always, [build, ci, docs, feat, fix, i18n, perf, refactor, release, revert, test]], }, };可以看到header-max-length72 字符、body-min-length20 字符、scope-enum枚举校验、type-enum11 种 type revert、header-case强制小写正是本文档规则的机器可读版本。而body-max-line-length被设为Infinity意味着 body 行宽不受 72 字符限制允许撰写长句说明上文示例中 body 里的长句即为佐证。2. scope/type 清单随代码结构自动同步commitLintRunEcmd_commit_msg.go的执行流程体现了“单一事实来源”的设计扫描cmd/与internal/目录动态发现 Go 包名作为 scope合并api、cmd、web三个例外 scope 及各 type 绑定的示例 scope对 scope 与 type 列表排序后同时生成commitlint 配置文件与本文档.md指南两个产物。这意味着当仓库新增一个内部包如新增internal/foo时只要重新运行生成器scope-enum规则和本文档的 scope 清单就会同步更新杜绝了“文档写了但 lint 不认”的漂移问题。文档头部Code generated by go generate. DO NOT EDIT.的注释见 dot_commitlintrc.cjs.tmpl也印证了这一点。3. 本地钩子与 CI 双重把关仓库通过 .lefthook.yml 配置 Lefthook 本地 git 钩子在pre-commit阶段并行执行 docs lint、eslint、golangci-lint、reuse 等项目级检查commit-msg 阶段的 commitlint 校验则由 CI 工作流.github/workflows与本地钩子共同完成。开发者在本地提交时即可获得即时反馈避免把不合规的提交推到远程后才被 CI 拒绝。实践建议快速自查清单在提交前可对照以下清单自查headertype(scope): summary总长 ≤ 72 字符summary 为祈使句、小写、无结尾句号type必须是build|ci|docs|feat|fix|i18n|perf|refactor|release|revert|test之一scope使用受影响的包名authentication、oidc、storage等或例外api/cmd/web跨包变更可省略body除docs外必填≥ 20 字符说明 why 并对比前后行为用祈使句现在时footer破坏性变更以BREAKING CHANGE:开头并附迁移说明关联 issue 用Fixes #numberrevert以revert:开头body 含This reverts commit SHA与原因说明签名按需保留Signed-off-by: AUTHOR。延伸阅读Pull Request 指南提交信息之外PR 标题、描述与审查流程的配套规范贡献指南总览Authelia 贡献流程的整体介绍生成器实现cmd_commit_msg.go 与模板 docs-contributing-development-commitmsg.md.tmplcommitlint 配置web/commitlint.config.mjs本地钩子配置.lefthook.yml。本文依据 Authelia 官方开发文档 commit-message.md 整理并对照仓库源码cmd_commit_msg.go、dot_commitlintrc.cjs.tmpl、web/commitlint.config.mjs与钩子配置.lefthook.yml核实文中所有约束与示例均以当前仓库实际内容为准。【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
