mailcow-dockerized 贡献指南深度解读PR 提交流程、Issue 报告规范与镜像版本化实践【免费下载链接】mailcow-dockerizedmailcow: dockerized - 项目地址: https://gitcode.com/GitHub_Trending/ma/mailcow-dockerizedmailcow: dockerized 是一个以 Docker 为底座、集成了邮件服务器与群件组件SOGo、Rspamd、Dovecot、Postfix 等的开源邮件系统。本文基于仓库根目录的 CONTRIBUTING.md最后更新于 2025 年 11 月 12 日为主线逐条解读 mailcow 社区的 Pull Request 与 Issue 协作规范并结合 docker-compose.yml、.github 下的模板与 CI 工作流、update.sh 开发者模式等仓库实际文件说明每一条规则背后的工程动因。读完本文你将掌握向 mailcow 提交高质量 PR 的完整流程、符合要求的 Bug 报告写法以及 mailcow 自研镜像的标签版本化约定。一、协作模型总览staging / master / nightly 三分支mailcow 的所有社区贡献都围绕三个分支展开理解这一模型是读懂本文后续所有规则的前提分支定位说明master稳定发布分支面向生产环境的稳定版本不接受直接 PRstaging合并与验证分支所有 Pull Request 的目标分支社区改动在此汇集nightly夜间构建分支由 CI 从 staging 自动生成用于提前暴露问题仓库中的自动化工作流证实了这一分工check_prs_if_on_staging.yml 会在github.event.pull_request.base.ref ! staging时自动触发提醒——这正是 CONTRIBUTING.md 中提到的moobot 提醒机制的落地实现pr_to_nightly.yml 与check_if_support_labeled.yml等负责后续的合并与标签管理image_builds.yml、rebuild_backup_image.yml 则对应镜像的构建与重建流程。从源码结构看update.sh也内置了--nightly等参数允许实例切换到夜间构建通道方便贡献者提前验证新特性。二、Pull Request 指南8 条规则与背后的工程约束CONTRIBUTING.md 对 PR 提交给出了 8 条硬性要求仓库会在不满足要求时直接关闭 PR。逐条解读如下规则 1始终基于 staging 分支创建 PRALWAYS使用本地克隆实例的 staging 分支作为 PR 的基底批准后改动会落入 staging。官方建议按类型 内容为 PR 新建命名分支例如feat/前缀功能更新如sogo-6.0.0SOGo 升级到 6.0fix/前缀缺陷修复如html-escape修复 mailcow 中 HTML 转义问题对应 PULL_REQUEST_TEMPLATE.md 中的 Affected Containers 一节提交者需要列出所有受影响的 Docker 容器方便维护者评估镜像重建范围。规则 2 与 3使用英文并保持分支整洁尽管 mailcow 是德国公司背景所有 issue/feature 报告必须使用英文以便非德语用户也能参与讨论PR 分支应保持干净不要混入无关提交例如其他分支、其他用户的 commit。若修改了update.sh等会触发自动提交的脚本应使用开发者模式进行干净开发详见下文第五节。规则 4提交前自测并留下证据如有可能附上一段测试日志或用截图 / GIF演示功能效果。虽然维护者也会自行测试但提交者的自测证据能省去你到底测没测的来回确认。这与仓库中 helper-scripts/dev_tests 目录的存在相互印证——社区确实会为关键功能编写开发期测试脚本。规则 5使用 PR 模板并清理注释创建 PR 时必须使用模板。模板中形如!-- CONTENT --的注释块可以删除或保留GitHub 渲染时不会显示但正文应只保留真实内容。查看 PULL_REQUEST_TEMPLATE.md 可以看到模板要求的核心字段Contribution Guidelines确认已阅读并同意贡献指南必选勾选未勾选 PR 不会被评审Short DescriptionPR 做了什么Affected Containers涉及哪些 Docker 容器Did you run tests?测了什么、预期结果与实际结果各是什么。规则 6目标分支必须是 staging绝不直接指向 master这是规则 1 的强化版。如果忘记切换moobot即 check_prs_if_on_staging.yml会自动提醒你切换 base 分支。该工作流附带的说明图如下规则 7耐心等待合并PR 可能不会被立即接受甚至可能因各种原因不被接受。mailcow 团队会尽力将社区的有意义改动纳入项目但合并节奏由维护者把握提交者不应因等待而失望。规则 8大改动先立项再动手计划提交较大、较复杂的 PR 时建议先在独立 issue 中提出构想待想法被接受后再开始实现以避免方向性返工带来的不必要挫折。规则 9镜像重建时的标签版本化方案重点如果 PR 需要重建 Docker 镜像即改动涉及 Dockerfile 或data/Dockerfiles/下的文件必须同步更新 docker-compose.yml 中的镜像标签。mailcow 采用基础镜像版本 补丁字母的约定版本号递增主版本升级时递增数字例如ghcr.io/mailcow/sogo:5.12.4→:5.12.5补丁修复追加字母在同一基础版本上的修复在版本号后追加小写字母例如:5.12.4→:5.12.4a。查看当前 docker-compose.yml 可以直观看到这套约定在实际仓库中的形态例如image: ghcr.io/mailcow/unbound:1.25.1-1 image: ghcr.io/mailcow/clamd:1.71 image: ghcr.io/mailcow/rspamd:4.1.4-1 image: ghcr.io/mailcow/phpfpm:8.2.29-3 image: ghcr.io/mailcow/sogo:5.12.9-1 image: ghcr.io/mailcow/dovecot:2.3.21.1-2 image: ghcr.io/mailcow/postfix:3.10.12-1 image: ghcr.io/mailcow/postfix-tlspol:1.8.23 image: ghcr.io/mailcow/nginx:1.30.4-1 image: ghcr.io/mailcow/acme:1.98 image: ghcr.io/mailcow/netfilter:1.64 image: ghcr.io/mailcow/watchdog:2.11 image: ghcr.io/mailcow/dockerapi:2.12 image: ghcr.io/mailcow/olefy:1.15这套数字 连字符修订号 / 字母补丁的命名如2.3.21.1-2、5.12.9-1能让维护者与用户一眼区分上游版本升级与mailcow 自研补丁是容器化项目里值得借鉴的可追溯版本实践。三、Issue 报告指南安全披露、8 条准则与报告流程3.1 安全披露Security disclosures安全漏洞与安全修复必须先保密提交通过 SECURITY.md 中指定的联系地址info at servercow.de私下报告等待联系人的响应确保协调式、负责任的披露responsible disclosure在整合、发布或公开披露之前不得将漏洞贴进公开 issue/PR。SECURITY.md 进一步说明了后续流程收到报告后团队会指派主要处理人primary handler依次完成确认问题并确定受影响版本 → 审计代码查找类似问题 → 为仍在维护的所有发布版本准备修复。3.2 Issue 报告 8 条准则Issue 跟踪器只用于 Bug 报告或改进请求不用于支持类提问。支持问题应转向社区支持渠道mailcow 社区 Telegram或付费商业支持仅在具备邮件服务器管理与 Docker 使用基础知识的前提下报告错误。mailcow 是构建在 Docker 之上的完整邮件服务器含群件组件调试与运维需要一定技术功底一律使用英文报告/请求同 PR 规则只报告最新发布系列中包含的 Bug。最新系列的定义是最后一个主要补丁如 2023-12及其下所有次要补丁修订版如 2023-12a、b、c。自 2024 年 1 月 1 日起的新报告必须满足此标准旧版本不再受支持尽可能详细包括对 mailcow 安装所做的哪怕最细微的改动认真填写 Bug 报告表单以减少来回确认提交前先检索已有 issue若存在相似请求直接加入该请求即可创建 issue/feature 请求不保证团队或社区会立即实现或修复提交前务必对报告中的敏感信息做匿名化处理。3.3 Issue 报告指南7 步排查法CONTRIBUTING.md 要求报告者先自行排查七步依次为读日志顺着日志找出问题原因顺着日志线索调查重启出问题的服务或整个堆栈确认问题是否仍然存在阅读出问题服务的官方文档并检索其 bugtracker在mailcow 的 issues 列表中检索是否已有相同问题若确认是 Bug 或急需的功能创建 issue但必须附带全部日志和完整问题描述在社区驱动的支持渠道中提问。3.4 Bug 报告模板系统信息采集命令仓库的 Bug_report.yml 将上述准则落实为结构化表单其中包含一套可直接复制的诊断命令报告者按模板填写即可采集项命令当前分支git rev-parse --abbrev-ref HEADCPU 架构uname -m操作系统lsb_release -dsDocker 版本docker versioncompose 版本docker-compose version或docker compose versionmailcow 版本git describe --tags git rev-list --tags --max-count1代码改动git diff origin/master需脱敏防火墙规则iptables -L -vn、ip6tables -L -vn、iptables -L -vn -t nat、ip6tables -L -vn -t nat容器内 DNS 检查docker exec -it $(docker ps -qf nameacme-mailcow) dig short stackoverflow.com 172.22.1.254若修改了 mailcow 内部网络IP 需相应调整表单还要求填写服务器规格、是否启用 AppArmor/SELinux、虚拟化技术LXC 与 OpenVZ 不受支持、反向代理等环境信息并明确邮件内容须附带容器日志末尾几行以及iptables四类规则输出——这些细节对排查端口映射与防火墙类问题至关重要。与之对比Feature_request.yml 则更轻量仅要求Summary想法概述、Motivation对用户的价值、Additional context补充背景或截图三部分。四、创建 issue / feature request / PR 时的指南确认机制CONTRIBUTING.md 明确要求创建 issue/feature request 或 pull request 时必须确认同意本指南。这一机制在模板中得到了落实PULL_REQUEST_TEMPLATE.md 的第一项复选框即为Ive read the contribution guidelines and wholeheartedly agree them未勾选则 PR 不会被评审Bug_report.yml 同样把已阅读并完全同意贡献指南设为必选复选框并额外要求确认已检索历史 issues环境满足官方文档的前置系统要求等事项仓库根目录另有 CODE_OF_CONDUCT.md 规定社区行为准则与贡献指南共同构成 mailcow 的社区协作契约。五、从规则到源码开发者模式与自动化工作流CONTRIBUTING.md 规则 3 提到修改update.sh等触发提交的脚本时通常有开发者模式可用于干净工作。这一点可以在 update.sh 中得到验证脚本在第 2226 行优先解析--dev/-d参数并设置DEVy当DEV未设置时update.sh脚本会计算_modules目录的文件哈希find ... | sha256sum并在更新后比对哈希以决定是否覆盖本地模块而在开发者模式下update.sh会打印 Developer mode: Skipping _modules update from git 并跳过从 git 拉取_modules的更新避免本地测试改动被仓库内容覆盖帮助信息update.sh明确注释-d|--dev - Enables Developer Mode (No Checkout of update.sh for tests)即开发者模式不会重新检出update.sh本身专为本地测试场景设计。这套机制确保贡献者在修改核心脚本时能够在不污染本地工作区、不产生无关提交的前提下完成开发与自测从工程实现层面支撑了保持 PR 分支干净的协作要求。六、总结一份可执行的贡献清单综合 CONTRIBUTING.md 与仓库实际实现向 mailcow 提交高质量贡献的完整动作如下开发前fork 后基于staging拉出命名分支feat/或fix/前缀大改动先开 issue 征询方向开发中涉及update.sh等脚本时使用./update.sh --dev开发者模式保持分支干净、无无关提交提交 PR 时目标分支选择staging使用 PULL_REQUEST_TEMPLATE.md 并勾选同意指南附自测日志/截图若改动 data/Dockerfiles 下的 Dockerfile 或镜像相关文件按版本号递增 / 追加补丁字母的约定同步更新 docker-compose.yml 中的镜像标签报告 Bug 时先按 7 步排查法自查再使用 Bug_report.yml 表单完整填写系统信息与日志涉及安全漏洞则先走 SECURITY.md 的保密披露通道提交后耐心等待合并若 moobot 提醒分支错误按提示将 base 切换回staging。这套以 staging 为中心、以模板和自动化工作流为保障的协作体系是 mailcow 能够在持续演进中保持稳定发布节奏的关键工程实践也值得其他 Docker 化开源项目借鉴。【免费下载链接】mailcow-dockerizedmailcow: dockerized - 项目地址: https://gitcode.com/GitHub_Trending/ma/mailcow-dockerized创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考