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/autheliaAuthelia 作为面向 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 MessageGit 提交信息的 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): summarytype必填允许值为build、ci、docs、feat、fix、i18n、perf、refactor、release、revert、testscope可选默认取受影响的包名如authentication、authorization、configuration、handlers、oidc、session、storage、webauthn等但有三个明确例外apiopenapi 规范变更、cmdauthelia/authelia-gen/authelia-scripts/authelia-suites顶层二进制变更、webReact 前端变更跨包改动或与具体包无关的文档改动可省略 scopesummary使用祈使句现在时change 而非 changed首字母小写结尾无句号。body对除docs类型外的所有提交必填且至少20 字符同样使用祈使句现在时重点解释为什么做这个改动motivation可对比新旧行为以说明影响。footer可选用于承载 breaking change 说明与关联 issueBREAKING 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.gointernal/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-lintGo 静态分析全部 Go 代码GitGuardian密钥管理防止密钥泄露CodeRabbit质量与安全评估针对一般 PROpenSSF Scorecard / Best Practices安全实践评估前者自动、后者人工StepSecurity Harden-RunnerCI Agent 安全运行于 GitHub CI 任务zizmorGitHub 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无默认值可省略与requiredyes/no/situational后者需说明依赖哪些其他配置存储与迁移所有迁移必须有 up 和 down 两个方向、最好幂等命名遵循Vversion.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_keykey 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），仅供参考