KnowForge/Apache PLC4X 1.0.0 简体中文
开发者

贡献

qianmoQqianmoQ· 更新于 2026-10-01· 阅读 8 分钟· 0 次阅读
登录后可跨设备保存划线和私人笔记登录

贡献方式

你可以通过多种方式参与到 PLC4X 项目中来。

通常包括但不限于以下几种：

  • 提交 Pull Request
  • 提交 Bug 报告
  • 在我们的邮件列表中积极交流
  • 推广该项目（撰写文章、博客、在会议上做演讲）
  • 编写文档

我们是一个非常友好的团队，不要害怕主动站出来。

提交

我们采用 约定式提交。由于 plc4x 是一个单一的多语言仓库，我们通常将 scope 定义为 …​(plc4[language shortcut here]/subcomponent)（例如，Golang 部分中 Bacnet 的一个新功能，其提交信息为 feat(plc4go/bacnet): cool new feature for…​）。

Pull Request

提交代码变更最简单的方式，是通过 GitHub pull request。

要完成此操作，首先需要创建一个 GitHub 账户并登录你的账户。

完成之后，请前往我们的 GitHub 站点 并创建一个所谓的 Fork。

contributing github fork

此时 GitHub 会在你的账户中创建 PLC4X 仓库的完整副本。只有你可以向这个副本提交代码。

接下来，理想情况下你应该检出你克隆的仓库：

git clone https://github.com/{your-user-id}/plc4x.git

现在你已经在电脑上拥有了一份 PLC4X 的副本，你可以随意修改它；因为这是你自己的副本，所以你甚至可以放心地提交这些更改，不必担心弄坏任何东西。

当你完成修改并希望我们查看时，就该创建所谓的 Pull-Request 了。

具体做法是前往你在 GitHub 上的分叉仓库页面。

每个分叉仓库都会多出一个名为「New Pull Request」的按钮：

contributing github create pull request

点击它之后，我们会收到关于你更改的通知，并可以对其进行评审。我们还可以讨论你的更改，并让你在我们接受并合并到 PLC4X 之前完善你的拉取请求。

AI 辅助与 AI 生成的拉取请求

AI 编程助手让编写拉取请求变得容易了许多，而这类拉取请求的数量也在稳步增长。在提交之前，请先阅读本节内容。

PLC4X 由极少数人维护。评审一个拉取请求所花费的时间远多于你生成它所花的时间：我们必须理解这项更改，依据协议规范以及可能需要从柜子里翻出来的硬件对其进行评估，检查它在多语言单体仓库中可能带来的副作用，并在之后为其承担责任。大多数由 AI 生成的拉取请求并非错误——问题在于它们到来的速度超过了我们这几个人的处理能力，这已经成为该项目一个真正的压力来源。

我们要明确说明我们所作的区分：

  • 如果你使用 AI 是为了弥补自身工具箱的不足，我们非常欢迎。一个典型的例子是：一位对某协议有深刻理解、但 Java 技能较为初级的 OT 工程师——这种协议知识正是本项目所需要的，而我们非常乐意提供指导，帮助你把代码方面做好。
  • 如果你是在扫描开源项目、寻找任何可以贡献的地方，以积累「贡献声誉」，那么请选择另一个项目。我们没有评审能力来补贴这种行为。

请先自我介绍

在接受你的拉取请求之前，我们希望你能订阅我们的开发者邮件列表 dev@plc4x.apache.org，并在其中自我介绍：你是谁、你的背景如何，以及你对 PLC4X 有什么兴趣。关于如何订阅，请参见 Getting in Contact 页面。

这并非形式主义。它能告诉我们正在与谁合作、你已经掌握了哪些知识、在哪些方面指导会有所帮助；也正是在这一点上，一次贡献才会从队列中的一项变成一场对话。

未做此类介绍就提交的拉取请求可能会被拒绝。如果这类拉取请求中包含有效的发现，我们保留自行直接应用所提更改的权利，以避免鼓励更多随意的 AI 投稿。

保持你的分叉仓库同步

由于我们一直在持续开发 PLC4X，而你创建的是我们仓库的一份副本，它很快就会过时。

为了让官方仓库获得我们引入的改动，你需要让 git 知道这一点。

你在本地通过添加一个新的所谓 remote 来完成这件事。默认情况下，你克隆来源的远程仓库被命名为 origin。

通常你会把第二个远程仓库命名为 upstream，但一般来说你可以取任何你喜欢的名字。

在命令行（或你选择的 git 图形界面）中添加该远程仓库：

git remote add upstream https://github.com/apache/plc4x.git

如果使用以下命令列出所有的远程仓库：

git remote -v

它应该输出类似这样的内容：

origin    https://github.com/{your-user-id}/plc4x.git (fetch)
origin    https://github.com/{your-user-id}/plc4x.git (push)
upstream    https://github.com/apache/plc4x.git (fetch)
upstream    https://github.com/apache/plc4x.git (push)

如果确实如此，你可以继续；如果没有……那么你可以通过我们的开发者邮件列表寻求帮助。

要获取上游仓库的所有变更，只需执行以下命令：

git pull upstream

这将从上游获取所有更改并在本地合并。要更新你的 GitHub 版本，你需要将更改推送回 origin。可以通过执行以下命令来完成：

git push

（如果未提供远程仓库，git 将默认使用 origin）

Bug 报告

我们使用 GitHub Issues 作为 Bug 与问题跟踪器。

欢迎提交 feature requests、bug reports、patches、comment on issues、……​

文档

由于我们的文档和网站是构建过程的副产物，从技术上讲，贡献文档与贡献代码是一样的。

我们所有的内容都用 Asciidoctor 编写，位于 src/site/asciidoc 目录中。关于 Asciidoctor 语法的参考，请查看 Asciidoctor 文档。

分支模型

PLC4X 项目使用以下分支模型。

同样的模型被许多其他项目采用，因此应该非常直观。

  • release 包含最新的已发布状态。
  • 开发在 develop 分支上进行。
  • 功能在带有 feature/ 前缀的功能分支中开发。
  • 每个次版本发布都有一个对应的发布分支 rel/1.0.0
  • 发布分支只能从 develop 派生
  • 缺陷修复发布没有专门的发布分支，直接在对应的次版本发布分支上进行

评论

登录后参与评论

正在加载评论…