Authelia 贡献指南体系解析：贡献前讨论、自动化流程与生成式 AI 政策
【免费下载链接】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 作为面向 Web 应用的单点登录（SSO）与多因素认证门户，其代码库横跨 Go 后端、React/TypeScript 前端、SQL 迁移、文档与 CI/CD 流水线，贡献者需要一套清晰的规则才能保证数千个文件的演进质量。本文以仓库中 指南章节引言 为核心，系统梳理 Authelia 的贡献指南体系：哪些规则由自动化流程在 PR 中强制、哪些依赖人工判断、贡献前为什么要先讨论、以及生成式 AI 参与贡献时的边界与义务，并深入到 Pull Request 指南、Commit Message 指南、测试指南 等姊妹文档与仓库实际配置中，帮助开发者快速理解并顺利提交高质量的贡献。
指南章节的定位：自动化之外的人工约定
Authelia 的贡献指南（Guidelines）章节并不只是一堆"建议"，它有一个非常务实的出发点：项目通过大量自动化流程在 Pull Request 中提供即时反馈（lint、测试、安全扫描、许可证合规检查等），但自动化并不能覆盖所有场景。指南章节同时收录了"已被自动化覆盖"与"尚未被自动化覆盖"两类规则，贡献者需要通读全文并自行判断。
正如 指南引言 所述：
- 项目通过自动流程在 PR 中反馈大部分规范问题，但并非所有情况都被覆盖；
- 虽然期望大家尽量遵守全部指南，但项目理解任何指南都存在逻辑上的例外——如果你的改动确实有充分理由偏离某条规则，在 PR 中说明理由即可，只要合理，维护者大概率会认同。
这句话奠定了整个指南体系的基调：指南是共识的沉淀，而不是僵硬的教条。这也是理解后续所有细则（行宽 120 字符、错误字符串大小写、迁移文件命名等）的前提。
General Guidelines：贡献之前，先讨论
指南引言给出了所有贡献者最先需要遵守的一条"元规则"——在动手贡献之前，先与社区讨论你计划做的改动。理由有三条，每一条都直接关系到贡献者的时间成本：
- 避免重复劳动：多人同时实现同一功能或修复同一缺陷，最终只有一份能合入；
- 避免冲突：未对齐的改动可能在合并时产生大量冲突，增加维护成本；
- 避免浪费有限时间：方向不对的贡献可能最终无法被接受，先讨论可以确保你的投入方向正确。
这一原则在仓库根目录的 CONTRIBUTING.md 中得到了呼应：它同样建议在发起 Pull Request 之前先创建 issue 讨论需求与实现方式，并让维护者知道"你计划处理某个 issue"，从而避免重复工作。也就是说，"先讨论再动手"不仅是指南引言的规定，也是整个项目贡献流程的事实标准。
指南体系全景：一份完整的贡献检查清单
Pull Request 指南 中有一份供维护者评审使用的检查清单，它同时也是贡献者的自查清单，完整列出了指南章节下的所有子指南：
| 指南文档（仓库相对路径） | 覆盖范围 |
|---|---|
| Commit Message | Git 提交信息的 header/body/footer 格式、类型与作用域 |
| Database Schema | 表名、列名、外键/唯一键/主键的命名约定 |
| Documentation | 文档中域名、证书、私钥示例的规范 |
| Testing | 测试覆盖率要求、bug 修复回归测试、测试工具链 |
| Accessibility | 前端翻译、响应式设计、目标分辨率 |
| Style | 行宽、错误字符串、配置文档格式、存储迁移规则 |
| Introduction | 一般原则、讨论文化、生成式 AI 政策入口 |
除此之外，PR 评审还要求：行为变更必须同步更新文档（见 文档贡献指南）；改动必须通过全部相关 lint 与质量自动化检查；PR 需要以合适的方式关联并关闭相关 issue；贡献需遵循"安全默认值、禁止严重不安全配置、对可能降低安全性的配置明确提示"的安全设计原则。
Squash Merge 与 Force Push 约定
Pull Request 指南 明确了两条影响协作方式的规则：
- Squash Merge：所有 PR 最终都会被 squash 合并进
master分支，因此要求 PR 分支与master保持同步，并建议勾选Allow edits by maintainers复选框； - Force Push 限制：创建 PR 后，尤其是维护者已开始评审后，不要对 PR 分支执行 force push，否则会破坏评审者对提交历史的准确审查。仅有两类例外：为符合 Commit Message 指南 而调整提交信息；以及基于 master 或其他分支做 rebase。由于最终会 squash，你在 PR 分支上可以放心多次提交。
评审门槛
每个 PR 都要经过正式评审流程，至少两位维护者批准且所有检查通过后才能合入，任何成员（包括组织成员）都不能绕过这一要求。评审过程的设计目标是确保代码处于可合入master的状态，而重写历史（force push）会严重干扰这一过程——这正是上述约定的根本原因。
Commit Message 指南：让 git 历史可读、可导航
Commit Message 指南 采用的格式脱胎于 AngularJS Git Commit Message Format，目的是让 git 历史"易于导航、易于阅读"。每条提交信息由三部分组成：
<header> <BLANK LINE> <body> <BLANK LINE> <footer>其中header必填且不能超过72 字符，格式为：
<type>(<scope>): <summary>type必填，允许值为build、ci、docs、feat、fix、i18n、perf、refactor、release、revert、test；scope可选，默认取"受影响的包名"（如authentication、authorization、configuration、handlers、oidc、session、storage、webauthn等），但有三个明确例外：api（openapi 规范变更）、cmd（authelia/authelia-gen/authelia-scripts/authelia-suites顶层二进制变更）、web（React 前端变更），跨包改动或与具体包无关的文档改动可省略 scope；summary使用祈使句现在时（"change" 而非 "changed"），首字母小写，结尾无句号。
body对除docs类型外的所有提交必填，且至少20 字符，同样使用祈使句现在时，重点解释为什么做这个改动（motivation），可对比新旧行为以说明影响。footer可选，用于承载 breaking change 说明与关联 issue：
BREAKING CHANGE: <breaking change summary> <BLANK LINE> <breaking change description + migration instructions> <BLANK LINE> <BLANK LINE> Fixes #<issue number> Signed-off-by: <AUTHOR>指南还给出了一个完整的示例——fix(logging): disable colored logging outputs when file is specified，其 body 解释了当log_file_path被配置且检测到 TTY 时，终端着色输出会被写入日志文件、进而破坏 fail2ban 正则匹配的问题，以及修复思路，最后以Fixes #1480.关联 issue。这个示例本身就能看出 body 应该"讲清楚来龙去脉"。
在仓库中，这套约定被自动化工具强制：前端目录 web/commitlint.config.mjs 配置了 commitlint，并在本地通过 lefthook 作为 git hook 运行（见 测试指南 的 linting 表格），确保不合规的提交信息在进入历史之前就被拦截。
Testing 指南：覆盖率、回归测试与多层工具链
测试指南 是 Authelia 质量体系的纲领，核心要求如下：
- 覆盖率目标：尽力对新增/修改代码达到 100% 覆盖，但不强制在无实际意义处强行凑数——"仅仅标记某行被测试过"不算有效的测试；
- 命名规范：测试命名应反映"测什么、测代码的哪一部分"；
- Bug 修复必须有回归测试：修复类贡献必须附带一个"修复前失败、修复后通过"的测试，且必须包含在贡献中，否则大概率被拒绝（除非核心团队明确同意豁免）；
- 功能类贡献鼓励充分测试：任何可测的行都应被测试；如果某行无法测试，通常意味着需要重构。
方法论上，项目在 Go 与 React 代码上于每次提交master前后运行测试与覆盖率统计，并同时采用 SAST（静态分析）与 DAST（动态分析）工具。仓库中的实际佐证随处可见：internal/下几乎每个包都配有*_test.go，例如 internal/configuration/configuration_test.go、internal/handlers/handler_authz_builder_test.go；internal/suites 目录下还有整套端到端集成测试套件（scenario_*.go、action_*.go），覆盖 LDAP、MySQL、Postgres、OIDC 等真实环境。
多层次质量与安全工具链
测试指南用一张表格完整列出了项目依赖的自动化工具及其定位：
| 工具 | 定位 | 说明 |
|---|---|---|
| Go Test | 覆盖率、静态与动态分析 | go test -cover、go test -race、go test -fuzz，每次提交master前执行 |
| React Testing Library | 覆盖率、静态与动态分析 | React 代码，每次提交master前执行 |
| SonarQube | 静态代码分析 | 全部代码 |
| CodeQL | 静态代码分析 | 全部代码，且按计划定期运行 |
| Codecov | 覆盖率统计 | 为 Go 与 TypeScript 生成统计 |
| Grype | 漏洞管理 | SBOM 扫描 |
| Renovate | 漏洞与依赖管理 | 按计划运行 |
| golangci-lint | Go 静态分析 | 全部 Go 代码 |
| GitGuardian | 密钥管理 | 防止密钥泄露 |
| CodeRabbit | 质量与安全评估 | 针对一般 PR |
| OpenSSF Scorecard / Best Practices | 安全实践评估 | 前者自动、后者人工 |
| StepSecurity Harden-Runner | CI Agent 安全 | 运行于 GitHub CI 任务 |
| zizmor | GitHub Action 静态分析 | 防止 GitHub Actions 安全问题 |
Linting：经 lefthook 落地的本地防线
除 SAST/DAST 外，项目还通过 lefthook、web/eslint.config.mjs、根目录的 REUSE.toml（规定每个文件的 SPDX 版权与许可证标注，仓库里几乎每个文件都带有对应的.license或 SPDX 头）。
Style 指南：从行宽到数据库迁移的细节约定
Style 指南 是一份持续演进的清单，覆盖多个方面：
- 行宽：所有文件（Go、YAML、Markdown、JS、TS）尽量不超过120 字符，以便现代显示器并排展示两个文件；同时也承认存在合理例外（如 README 中 All Contributors 的条目）；
- 错误字符串：遵循 Go 代码评审惯例——错误不以大写字母开头（专有名词、缩写除外）、不以标点结尾；这些限制仅针对 error 类型本身，不适用于日志输出；
- 配置文档格式：每个配置区域先写区域说明，再给 h2 配置标题与完整配置示例，每个配置项用 h3 标题 + 带图标的
confkey短代码描述其type（如string、integer、list(string)、duration）、default（无默认值可省略）与required（yes/no/situational，后者需说明依赖哪些其他配置）； - 存储与迁移：所有迁移必须有 up 和 down 两个方向、最好幂等，命名遵循
V<version>.<name>.<engine>.<direction>.sql格式，其中 version 是 4 位顺序数字、name 只含字母数字与下划线（下划线视为空格）、engine 为all/mysql/postgres/sqlite；所有表必须有整数自增主键（PostgreSQL 用 serial）；表名、列名一律 snake_case（全小写、下划线分词）；所有数据库方法都应携带 context 以便及时终止不再需要的请求。
这些规则在 internal/storage/migrations 目录中有大量真实样例（174 个 SQL 文件），例如V0001.Initial_Schema.all.up.sql这类命名，可以对照理解。
Database Schema 指南：跨引擎一致的命名规范
数据库 Schema 指南 为表名、列名与键名给出精确约定，目标是让 MySQL、PostgreSQL、SQLite 三个引擎下的 schema 保持一致：
- 表名：所有数据库实现中一致、全小写、使用单数形式、单词间用下划线、只含字母数字与下划线；下划线仅用于单词之间或作为临时表前缀；表名必须以字母开头和结尾；
- 列名：所有实现中一致、全小写、只含字母数字与下划线、下划线仅用于单词之间、以字母开头和结尾；
- 键名：
- 外键：
<table_name>_<column_name>_fkey； - 唯一键：
<table_name>_<key_name>_key（key name 可以是所辖列名）； - 主键：多数数据库引擎不允许自定义主键名，因此除非要恢复默认格式，否则不显式设置主键名。
- 外键：
Documentation 指南：示例内容的安全与一致性
文档指南 看似简短，实则关乎文档示例的安全性与一致性：
- 域名：文档中一律使用通用域名
example.com（或其子域）；若确需多个域名，请在 PR 中征求具体反馈； - 证书：文档中包含的证书必须保证自
Jan 1 00:00:00 1970起有效期恰好 1 年，从而避免示例证书因多种原因"意外有效"； - 私钥：始终在 PEM 块的末尾、base64 填充
=（若存在）之前追加无效数据，推荐文本^invalid DO NOT USE——其中的^是非法 base64 字符，配合警示文字确保使用者不会误用示例私钥。
Accessibility 指南：前端翻译与响应式设计
无障碍指南 分别约束后端与前端：后端没有专门的无障碍规则，只要求"合理的日志输出"（这本身是主观的）；前端则强调两点：
- 翻译覆盖：尽可能让面向用户的界面信息默认可翻译，既方便社区以自动或手动方式贡献翻译，也允许管理员在本地覆盖这些文案（仓库 internal/server/locales 下有 177 个语言的 JSON 翻译文件，docs/i18n/en.toml 则承载文档站点翻译）；
- 响应式设计：高效利用可用空间、尽量少滚动，且用户只需在**单一方向（垂直）**滚动即可查看全部信息。指南还给出了常见目标分辨率建议：桌面端 1920x1080、1366x768、2560x1440、1280x720；平板（触控、横屏）768x1024、810x1080、800x1280；移动端（触控、横屏）360x800、390x844、414x896、412x915。
生成式 AI 指南：欢迎使用，但责任在人
指南引言明确指向了 人工智能政策。Authelia 对社区使用生成式 AI总体持欢迎态度，但围绕"专业与负责任地使用"制定了一系列规则，适用于 PR（代码与讨论区）、Issue、GitHub/Discord/Matrix 讨论、私有漏洞报告与邮件等所有场景，并作为 行为准则 的补充，违反者可依据行为准则的补救流程处理。
核心规则（General Policy）：
- 人 100% 对 AI 生成的内容负责；
- 提交前必须完整审查并真正理解内容；
- 使用 AI 生成内容时，必须在提交内容描述的第一段披露使用方式与位置；
- 人与人沟通的场合（邮件、issue、讨论、聊天室等）不应使用 AI 生成内容；
- 刻意隐藏、规避或误导关于 AI 使用的事实，被视为对该政策的直接违反，且有合理可能被认定为蓄意恶意行为。
针对Pull Request的额外规则：
- 改动必须经人工审查，所有 linter 与测试通过；若在代码创作中使用了 AI 工具，必须在 PR 描述第一行明确披露；作者必须能清晰解释任何一处改动，否则 PR 可能被直接拒绝；
- 评审者与作者不得在正式评审流程中（提问、请求变更、回复评审）使用生成式 AI，辅助性使用必须显式且仅是辅助；
- 大型改动不得仅由生成式 AI 产出；
- AI 工具或其公司不得以
Co-authored-by、Signed-off-by、Reviewed-by等 commit trailer 形式列为变更参与者； - 使用 CodeRabbit 等辅助工具时，不要盲从建议，应等待评审者评估、自行评估或询问维护者意见。
政策还给出了翻译场景的例外：允许使用 AI 将内容翻译成英文，但输入必须由人提供，且翻译输入需按指定格式附在披露段落之后（GitHub 上使用<details>折叠块展示{{ Input }}，其他渠道附 Gist 或等价链接）。
政策 rationale 部分解释了为什么如此严格：多项研究表明 AI 生成代码中超过 40% 存在显著安全漏洞；多数司法辖区不承认非人类输入的版权/许可有效性；AI 生成代码的版权归属尚不明确；以及项目方希望确认自己在与真实的人类沟通。对安全敏感的单点登录项目而言，这些顾虑都直接关系到代码评审质量。
逻辑例外原则：指南不是枷锁
贯穿整个指南体系的一条主线是"指南存在逻辑例外"。指南引言 明确表示：如果某个场景下遵循指南没有意义，只要在 PR 中说明理由（若理由不明显），维护者很可能认同你。Style 指南 也重申"这是指南而非棍棒"（a guide not a cudgel），并给出了 README 中 All Contributors 行宽超限这一真实例外。
因此，对贡献者的实操建议可以归纳为四点：
- 先讨论后动手：在 issue/讨论区对齐需求与实现方向，避免重复劳动与方向错误；
- 以自动化工具为第一道防线：本地跑通 lefthook 挂钩的 lint 与测试，让 commitlint、golangci-lint、typos、REUSE 等在提交前拦截问题；
- 对照检查清单自查：以 Pull Request 指南 中的评审清单逐项核对——文档是否更新、提交信息是否合规、回归测试是否齐全、是否满足安全设计原则；
- 用足例外条款：当确有合理理由偏离某条规则时，在 PR 中主动说明，而不是默默绕过。
这套"自动化强制 + 人工判断兜底 + 例外条款"的指南体系，正是 Authelia 这样一个涉及认证安全、多数据库引擎与多语言前端的复杂项目能够长期稳定演进的组织保障。无论你打算提交代码、修复文档还是补充翻译，都可以从这份指南引言出发，顺着各子指南与仓库中的真实配置找到可执行的规范。
【免费下载链接】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），仅供参考
