Dokku 贡献指南：从提交 Issue 到合并 Pull Request 的完整协作流程-港品优选

Dokku 贡献指南：从提交 Issue 到合并 Pull Request 的完整协作流程

【免费下载链接】dokkuA docker-powered PaaS that helps you build and manage the lifecycle of applications项目地址: https://gitcode.com/GitHub_Trending/do/dokku

导读

本文基于 Dokku 仓库根目录的 CONTRIBUTING.md 展开，系统讲解向 Dokku（一个基于 Docker 的 PaaS 平台）提交贡献的完整路径：从发现 Bug、撰写高质量 Issue，到创建 Topic 分支、遵循编码规范、提交 Pull Request，再到在本地运行完整测试套件验证改动。读完本文，你将掌握 Dokku 社区认可的协作节奏、分支与提交纪律、合并规则，以及如何借助仓库内的 tests.mk、docs/development/testing.md 与 ISSUE_TEMPLATE.md 完成一次合格的代码贡献。

参与贡献的多种方式

Dokku 项目欢迎各种形式的贡献，提交代码补丁只是其中一种。根据 CONTRIBUTING.md 的说明，社区认可的参与方式包括：

提交 Issue：发现 Bug 时，在项目的 issue 跟踪系统中创建问题报告；
编写测试用例：为尚未解决的 Bug issue 补充测试，帮助复现与验证；
编写补丁：为开放的 Bug/Feature issue 提交修复或实现，最好附带测试用例；
贡献文档：完善使用手册、教程等官方文档；
展示项目 Logo：以非商业方式展示 Dokku 的 Logo，扩大项目影响力；
撰写博客：分享你使用 Dokku 的方式与经验；
财务赞助：通过赞助渠道支持项目持续开发。

无论选择哪一条路径，都需要遵守一些基本协作准则，以保证维护者能够高效地跟进每个人的贡献。

安全漏洞：走私密报告通道

Dokku 维护者对安全问题非常重视。如果你发现了安全漏洞，绝对不要提交公开 Issue，而是应当立即将报告私密发送至维护者邮箱dokku@josediazgonzalez.com。

安全报告会得到高度重视，且项目会公开致谢报告者。这是安全研究与普通 Bug 报告之间最重要的流程差异：漏洞细节在修复完成前必须保密，避免被恶意利用。

如何撰写高质量 Bug 报告

撰写详尽、结构清晰的 Bug 报告本身就是对项目的重要贡献。在提交 Issue 之前，请先完成两步准备工作：

检索现有 issue 数据库：确认你的问题或建议是否已经被报告过；
若存在相同 issue：追加一条 "+1" 或 "我也有这个问题" 的评论即可，这能帮助维护者识别最普遍的问题并排定优先级。

正式提交时，请按照仓库根目录 ISSUE_TEMPLATE.md 中的模板填写全部信息。结合模板内容，一份合格的报告至少应包含：

问题描述：问题的现象、可复现程度、复现步骤、实际结果与期望结果；
dokku report APP_NAME输出：模板中明确标注这是必填项，缺失该信息的 Issue 可能被直接关闭。对于影响所有应用的问题，可运行不带参数的dokku report查看顶层报告信息；
安装方式与环境：通过deb还是make方式安装，运行环境是 AWS、VirtualBox 还是物理机等；
辅助诊断信息：如适用，附上dokku ps:inspect APP_NAME的容器检查输出、dokku nginx:show-config APP_NAME的 Nginx 配置；
部署相关信息：应用名称、应用类型（node/php/python/ruby 等）、使用的自定义 buildpack、Dockerfile内容、Procfile内容；
追踪输出：运行dokku trace:on后执行失败命令的输出。模板特别警告：trace:on会打印某些命令的环境变量，发布前务必用XXXXXX替换敏感信息，避免泄露凭据。

同时，请在报告中注明你确认最早出现该问题的版本，这将显著加速定位与修复。

贡献前的准备清单

在动手修改代码前，CONTRIBUTING.md 要求完成以下准备：

拥有一个 GitHub 账号；
提交一个 Issue（若尚不存在），清晰描述问题，Bug 需包含复现步骤；
Fork 仓库到你的账号下。

Making Changes：分支策略与提交纪律

进入编码阶段后，需要遵守明确的分支与提交规范：

创建 Topic 分支

从你希望基于的分支创建 Topic 分支，通常基于master；
除非你确定修复必须落在某个特定分支上，否则不要直接以其他分支为目标；
快速创建基于 master 的 Topic 分支：

git checkout -b my_contribution origin/master

尽量避免直接在master分支上工作——这会减少后续从 origin 拉取更新时产生冲突的概率。

以逻辑单元为单位提交

每次提交应构成一个逻辑单元：例如"实现一个新函数并在另一文件中调用它"应算作一个完整的工作单元；
提交 Pull Request 前，使用交互式变基整理提交历史：

git rebase -i git push -f

绝大多数提交应该被压缩为单个 commit；拿不准时，就把改动 squash 成一个提交；
提交前用git diff --check检查并清理多余的空白字符；
使用描述性的提交信息，并在信息中引用对应的 issue 编号（如#123）。

遵守编码规范

Dokku 的 shell 代码遵循 bashstyle 风格约定（文档中以 "Dokku coding standards" 指代）。在仓库的 tests.mk 中可以找到与编码规范对应的落地工具链：make lint依次执行lint-shfmt（调用shfmt -l -bn -ci -i 2 -d .做格式化校验）与lint-ci（基于 shellcheck 做静态检查，并借助 tests/shellcheck-to-junit 将结果转为 JUnit 格式），Go 插件则通过golangci-lint校验。也就是说，"符合编码规范"在 CI 中是可自动验证的硬性门禁。

保持 PR 干净可合并

Pull Request 必须干净地 rebase 到 master 之上，不得将多个分支的改动混杂在同一个 PR 中；
Git 技巧：当 PR 无法干净合并时，在特性分支中使用rebase master更新你的 PR，而不是merge master。

分支基线：始终基于最新 master

所有变更都应基于最新的 master 提交。这是社区合并工作的基线要求，确保你的改动与主干保持同步，降低冲突与回归风险。

提交 Pull Request

完成编码与本地验证后：

将改动推送到你 fork 仓库中的 Topic 分支；
向原仓库提交 Pull Request，并选择正确的目标分支（通常是master）。

合并规则与评审预期

提交 PR 后请保持耐心：维护者会尽快评审所有 PR 并给出评论，期间可能就细节进行多轮往返讨论。若你的 PR 最终未被合并（这种情况很少见），维护者会提供替代补丁方案，或引导你走向更优的解决思路。

在项目的 pre-1.0 周期内，合并 PR 遵循以下通用规则（对应语义化版本号的变化幅度）：

变更类型	版本号影响
Bug 修复（bugfix）	patch
安全修复（security）	patch/minor
次要特性（minor feature）	patch
不兼容变更（backwards incompatible change）	minor
主要特性（major feature）	minor

这意味着：小改动以低版本号增量合入，而破坏性或不兼容的改动会以更高的版本号增量发布，从而在发布节奏上为下游用户留出缓冲。

在本地运行测试：把质量门禁前置

贡献者应在提交 PR 前自行验证改动。CONTRIBUTING.md 指引读者阅读 docs/development/testing.md 获取完整的测试设置与运行技巧。结合该文档，Dokku 的测试体系由三部分组成：

Linter：基于 shellcheck 的静态检查（另有 shfmt 格式校验与 Go 插件的 golangci-lint）；
功能单元测试：基于 Bats 测试框架，测试文件位于 tests/unit（如apps_1.bats、config.bats等，以.bats结尾），公共辅助逻辑集中在 tests/unit/test_helper.bash（其中定义了DOKKU_DOMAIN=dokku.me等测试常量与全局 setup/teardown 清理逻辑）；
应用部署测试：部署 tests/apps 下覆盖主流语言与框架的示例应用，验证端到端部署能力。

CI 环境

所有 PR 都会在 CI（Ubuntu Noble 24.04、提供 Docker 支持）上执行测试。若某次提交确实无需测试（例如纯文档改动），可在提交信息中加入[ci skip]标记；但本应测试却携带该标记的提交不会被合并。这也侧面印证了测试门禁的强制性。

本地执行环境

Vagrant VM：按 docs/getting-started/install/vagrant.md 搭建 Dokku VM 后执行：

vagrant ssh sudo su - cd ~/dokku make ci-dependencies setup-deploy-tests

VSCode Dev Container：在 DevContainer 的终端中直接执行同样的make ci-dependencies setup-deploy-tests。

修改本地 Dokku 克隆后，别忘了同步到 Vagrant 中的 Dokku 安装：

# 从本地 git 克隆更新 vagrant dokku 安装 make copyfiles # 单独构建某个插件 make go-build-plugin copyplugin PLUGIN_NAME=apps

常用测试命令

# 运行完整测试套件（linter + bats 单元测试 + 应用部署测试） make test # 仅运行 linter make lint # 仅运行全部 bats 单元测试 make unit-tests # 仅运行全部应用部署测试 make deploy-tests

定向运行测试

运行单个应用部署测试：使用形如make deploy-test-nodejs-express的目标；完整的部署测试目标列表位于仓库根目录 tests.mk（例如deploy-test-dockerfile、deploy-test-python-flask、deploy-test-go、deploy-test-main-branch等）；
运行单个测试套件：当只改动某个插件时，可指定套件路径，例如：

bats tests/unit/apps_1.bats

这套"先本地、后 CI"的验证闭环，与上一节的分支、提交规范共同构成了 Dokku 贡献流程的质量保障体系：规范的提交历史 + 可自动验证的编码标准 + 必须通过的测试门禁，三者缺一不可。

附加资源

编码规范：Dokku coding standards（bashstyle 风格约定）；
现有 issue 列表：用于检索重复问题、了解开放任务；
测试文档：完整的测试设置说明与运行技巧；
Issue 模板：提交报告时的必填字段清单；
测试基础设施：linter、单元测试与部署测试的全部 make 目标。

无论你是首次接触 Dokku 的新贡献者，还是准备为某个插件提交修复的资深用户，遵循上述流程都能让你的贡献更顺畅地被评审与合并——这也正是开源协作中"让维护者省心"的最佳实践。

【免费下载链接】dokkuA docker-powered PaaS that helps you build and manage the lifecycle of applications项目地址: https://gitcode.com/GitHub_Trending/do/dokku

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析