Authelia Pull Request 贡献指南Squash Merge、Force Push 与合并审查全流程解析【免费下载链接】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 开源仓库的 Pull Request 提交与合并规范展开系统讲解其 Squash Merge 合并策略、force push 的禁区与例外、双维护者审批制审查流程以及一份可直接对照自检的合并要求清单。读完本文你将清楚知道在向 Authelia 提交代码时应如何组织分支提交、规避常见踩坑操作并理解每一条要求背后对应的自动化工具与仓库内证据。一、总体原则三条核心共识Authelia 对 Pull Request 的管理有一套明确约定目的是在持续接纳社区贡献的同时维持master分支历史的整洁与可审查性。原文案归纳为两条顶层要求勾选Allow edits by maintainers由于项目采用 Squash Merge 合并策略维护者需要能够直接在你的 PR 分支上做必要调整因此该复选框必须保持开启。避免 force push除下文列出的极少数例外外不要在 PR 创建后对分支执行强制推送这会严重干扰审查过程。这两条原则背后是同一个诉求让维护者能够准确、连续地审查你的每一次提交。相关背景见 贡献指南总览其中还建议贡献者在动手前先在社区讨论拟议的改动以避免重复劳动与贡献冲突。二、Squash Merge唯一的合并方式Authelia 明确规定每一个 Pull Request 最终都会被 squash merge 进master分支。这意味着你的 PR 分支在合并前必须与master保持同步up-to-date否则合并会被阻塞无论你的 PR 里有多少个 commit最终都只会折叠成一个 commit 进入主分支因此你完全不需要在 PR 分支上精心雕琢提交历史——想提交多少次就提交多少次最终的历史整洁由 squash 机制保证。这一策略的好处是master的历史保持线性且每个 commit 都对应一个完整的功能单元配合下方介绍的 Commit Message 规范header 不超过 72 字符、body 至少 20 字符等可以极大提升 git 历史的可读性与可导航性。三、Force Push 规则默认禁止例外有限文档对 force push 的态度非常明确在 PR 创建之后尤其是维护者已经开始 review 或明确表示即将 review 时请不要对 PR 分支执行 force push。原因是重写历史会让维护者难以对照前后版本准确审查你的改动。允许的例外仅有两类例外场景说明调整 commit message例如为了使提交信息符合 Commit Message 指南 而修改 header/body/footerrebase 到最新分支将你的改动基于master或其他分支的最新状态进行变基同时文档特别提醒在维护者完成首轮 review 之后如果需要同步origin/master的最新改动请使用 merge 而不是 rebase/force push任何重写历史的操作都会使后续审查变得困难。换句话说提交阶段可以随意 commit审查开始后请保持历史稳定。四、Review 流程至少两位维护者批准每个 Pull Request 都必须经过正式审查流程且有两个硬性门槛至少两名维护者批准At minimum two maintainers must approve所有检查checks必须全部通过。在此基础上组织内没有任何单一成员有权绕过这些要求合并 PR还需满足仓库 ruleset 中规定的额外约束。从仓库的自动化配置可以印证这套检查必须全绿的机制并非空谈.github/workflows/pr-labels.yml 在 PR 的opened、edited、synchronize、reopened事件上自动为 PR 打标签并使用了 StepSecurity Harden-Runner 加固 CI runner.github/workflows/codeql-analysis.yml、scorecard.yml、slsa.yml 分别承担代码安全扫描、供应链安全评分与软件供应链SLSA验证前端与文档目录下均存在 web/commitlint.config.mjs 等配置配合 lefthook git hook 在本地提交阶段就拦截不合规的 commit message。此外 测试指南 中详细列出了项目在每次提交到master前后运行的测试与质量工具矩阵包括go test -cover、go test -race、go test -fuzz、SonarQube、CodeQL、Codecov、golangci-Lint、GitGuardian 秘密扫描、Code Rabbit、OpenSSF Scorecard、StepSecurity Harden-Runner、zizmorGitHub Actions 静态分析等——这意味着你的 PR 在合并前会经过多层次的自动化检验。五、合并要求清单可对照自检的 Checklist以下要求既是 PR 被接受的前提也是维护者在审查时的核对清单。提交 PR 前请逐项确认行为变更必须补充文档如果改动新增或改变了行为必须同步更新相应文档见 文档贡献指南该文还介绍了 Hugo Doks 建站、本地运行pnpm dev预览以及用authelia-gen生成 CLI/JSON Schema 文档的流程。遵守全套开发指南具体包括通用指南贡献前先沟通、避免重复劳动Commit Message 规范header/body/footer 三段式格式header 不超过 72 字符body 至少 20 字符且用祈使句footer 用于标注 breaking change 与Fixes #issue数据库 Schema 规范表名/列名全小写、下划线分隔、单数形式外键命名table_column_fkey、唯一键命名table_key_key文档规范一律使用example.com域、证书有效期控制、私钥 PEM 块尾部附加^invalid DO NOT USE等测试规范bug 修复必须附带修复前失败、修复后通过的测试新功能尽量做到可测行全覆盖无障碍规范前端文案尽量走翻译体系、响应式设计只允许单一方向纵向滚动代码风格规范全文件最大行宽 120 字符、Go 错误字符串不以大写开头且不以标点结尾、存储迁移命名Vversion.name.engine.direction.sql等。通过全部 lint 与质量自动化如上节所述项目在 CI 中集成了大量静态/动态分析工具。正确关联并关闭 issue在 PR 描述中恰当提及相关 issue如Fixes #number使合并时自动关闭对应 issue。遵循 Security by Design 安全设计原则具体包含三点提供安全的默认配置secure defaults禁止严重不安全的配置项disallows critically insecure settings对于可能降低安全性的特定配置必须要求用户明确知晓explicit awareness。未来可能要求REUSE 合规仓库根目录已存在 REUSE.toml且 测试指南 中列出的 linter 矩阵也包含 REUSE 许可与版权合规检查目前文档将其列为潜在未来项。六、常见问题与最佳实践总结基于上述规则给贡献者几点实操建议提交前先 fork 并同步master在独立分支上开发频繁 commit 无需顾虑提交后保持分支稳定不做 force push如需同步上游优先 merge 而非 rebase审查中耐心等待至少两位维护者批准及时回应 review 意见改动继续以普通 commit 追加即可最终会被 squash合并前逐条核对第五节 Checklist尤其不要遗漏文档更新与安全默认值原则留意自动化反馈项目通过 .github/workflows 下的多个 workflow 在 PR 打开、编辑、同步时自动打标签与扫描检查结果会直接反映在 PR 页面上。七、相关文档导航贡献指南总览Commit Message 规范数据库 Schema 规范文档规范测试规范无障碍规范代码风格规范文档贡献流程【免费下载链接】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），仅供参考